The Development Environment
In this section, we’ll discuss the details of the setting up a local Catalyst project and the installation options available to you.
Installing Catalyst
As we’ve seen, when viewing a Catalyst storefront channel in the BigCommerce control panel, you will be presented with a quick “Start development” CLI command to set up a local project.
This command uses the Catalyst CLI installer:
This flexible installer is the key entry point for setting up a local Catalyst development environment. When run without any of the pre-configured options seen in the control panel, the installation process is interactive, prompting you with several options around creating or connecting a BigCommerce storefront.
The installation process will also automatically install all npm dependencies.
pnpm Package Manager
Catalyst uses the pnpm package manager by default, so you’ll see this syntax used for further commands in the sections below and in subsequent lessons.
You can also use pnpm for the initial installation command. Use corepack to make sure you have pnpm enabled.
Installer Options
The CLI installer supports a number of options to customize or configure your installation, including --gh-ref to provide a specific Git commit hash, branch name, or tag to install, or even --repository to specify a different repository to install from instead of the Catalyst GitHub.
The installer options can be used to specify all necessary configuration for the project, bypassing the need for the interactive prompts for connecting your store.
Note that these options are included in the example CLI command provided in the store control panel when viewing your storefront in Channels, allowing you to automatically install and connect your local project without the interactive prompts.
Run the CLI command with the --help option to see all available options.
Installing with Makeswift Support
The built-in Makeswift integration supports creating and visually editing static pages, as well as complex visual editing capabilities for a number of dynamic pages such as product detail pages.
Initiate your Catalyst installation using the --gh-ref option. While the upstream/integrations/makeswift pattern will install the most recent development code, you can also opt to use the tag reference @bigcommerce/catalyst-makeswift@latest for the latest release candidate.
Note that the release tag @bigcommerce/catalyst-makeswift@latest is what is deployed to your preview environment when initially creating your Catalyst storefront channel.
Connecting a BigCommerce Store
When you initially run the installer, you’ll connect your BigCommerce store either via explicit option values or via a device auth workflow and interactive prompts. You must be able to log into your store’s control panel with a user account that has permission to create store-level API accounts. You’ll be prompted to authorize Catalyst in your browser, after which the installer will take care of the rest, creating and configuring all credentials needed to run the storefront application.
If you need to re-connect your project, whether to the same or a different storefront channel, it’s easy to do so at a later time using one of two methods:
- Manual - The connection process configures environment variables in
.env.local. You can set up this file manually to connect your store. We’ll examine each of the variables in this file. - Automatic - Run the following command in an existing Catalyst project to walk through the same connection process available at install:
The init CLI command makes use of the API token initially stored in the file .catalyst. You may choose to remove this file before running init if you want to connect to an entirely different store.
It is not recommended to connect your Catalyst project to your default storefront channel or any other Stencil channel.
Note that the CLI installer will give you the option to create a new channel rather than connecting to an existing one. This is an alternative to creating the new storefront channel via the control panel. However, currently, the One-Click Catalyst app must be installed on the store in order for this flow to work.
This will be taken care of if a Catalyst storefront has previously been created in the control panel, or you may choose to install the app manually via this URL:
Local File Structure
When the installer is complete, your local project will be a clone of the Catalyst GitHub.
Your Catalyst project is a clone of the Catalyst monorepo. All relevant code for the Catalyst storefront is contained in the core project directory.
In all subsequent sections, when referring to file paths, these will be relative to core.
ESLint Configuration
Catalyst comes with a carefully curated configuration for ESLint, a static code analysis tool that can help ensure your code is stable, reliable, well-formed, and free of syntax errors.
@bigcommerce/eslint-config-catalystprovides several categories of core configuration..eslintrc.cjsis the central config file and can be used to customize your project’s configuration.
ESLint will be run automatically during the Next.js build process, which will fail if any static tests result in errors. You can also run these tests at any time in your local environment with the following command:
Edit .eslintrc.cjs to customize the ESLint rules to meet your project’s needs. The following is an example of disabling the opinionated formatting rules from Prettier:
If certain ESLint rules make sense to leave enabled in general, but you have a specific reason to ignore them in certain circumstances, you can use inline comments to disable them selectively. This is an example of disabling the rule disallowing TypeScript type assertions:
Keep in mind that Catalyst’s default ESLint rules are in place to enforce best practices, so consider very carefully before disabling them via config or inline comments.
