Getting Started
Installation
Make sure you've satisfied all prerequisites before continuing.
We recommend using the CLI to create a new Catalyst project. The CLI will guide you through the process of creating a new project and setting up your development environment. If you prefer to create a project manually, you can follow the manual installation instructions; there is no difference in the end result between the two methods.
Run the Catalyst CLI
pnpm create @bigcommerce/catalyst@latestSet up a GitHub fork
You can click here to create a fork (opens in a new tab) or, navigate to https://github.com/bigcommerce/catalyst (opens in a new tab) and click "Fork" at the top of the page.
GitHub will prompt you to choose a name for your fork; for the purposes of this guide, we'll refer to name of the fork as <YOUR_FORK_NAME>. You should replace <YOUR_FORK_NAME> in all of the commands below with your actual fork name.
Back in your terminal, add your fork as a remote to your local repository:
git remote add origin git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_FORK_NAME>.gitRun the development server
Finally, you can run the following command from the monorepo root to run the development server:
pnpm run devThe following table lists localhost URLs with the default ports. When a port is unavailable, Catalyst uses the next available port. For example, if 3000 is in use, core will run on 3001.
| Process | URL with port |
|---|---|
| Catalyst storefront | http://localhost:3000 |
Project structure
The structure of the Catalyst repository you just created is a monorepo (opens in a new tab) with multiple codebases, including but not limited to the following:
- The core Next.js reference storefront application, in
/core(opens in a new tab) - Packages published to NPM, in
/packages(opens in a new tab) - Product documentation, in
/docs(opens in a new tab)
It's important to note that we use several tools throughout the Catalyst monorepo, such as Turborepo (opens in a new tab) and pnpm Workspaces (opens in a new tab); you'll notice references to these tools as you spend more time in the repository, but most developers likely won't need to change any files, code, or configuration related to these tools in their normal Catalyst workflows.
Choose your workflow
Now that you can run Catalyst locally, your next steps are dependent on your goals as a Catalyst developer. You might be:
- A Storefront Developer, looking to create a custom storefront using Catalyst as your foundation.
- An Integration Developer, aiming to build add-ons or integrations that can be optionally included in Catalyst storefronts.
- A Contributor, interested in enhancing the Catalyst project by submitting pull requests for new features, bug fixes, or other improvements.
Please proceed by choosing a workflow below: