-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
290 changed files
with
1,094 additions
and
988 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Validating CODEOWNERS rules …
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| * @bigcommerce/team-catalyst |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,39 +8,27 @@ jobs: | |
| name: Deployment Audit | ||
| timeout-minutes: 30 | ||
| runs-on: ubuntu-latest | ||
| if: ${{ github.event.deployment_status.state == 'success' && contains(github.event.deployment_status.target_url, 'catalyst-latest') }} | ||
|
|
||
| steps: | ||
| - name: Checkout code | ||
| uses: actions/checkout@main | ||
|
|
||
| - uses: pnpm/action-setup@v2 | ||
|
|
||
| - name: Requires audit | ||
| id: requires_audit | ||
| env: | ||
| DEPLOY_URL: ${{ github.event.deployment_status.target_url }} | ||
| run: | | ||
| if [[ $DEPLOY_URL =~ "storybook" ]]; then | ||
| echo "AUDIT=false" >> "$GITHUB_ENV" | ||
| else | ||
| echo "AUDIT=true" >> "$GITHUB_ENV" | ||
| fi | ||
| - uses: pnpm/action-setup@v3 | ||
|
|
||
| - name: Audit preview URL with Lighthouse | ||
| if: env.AUDIT == 'true' | ||
| id: lighthouse_audit | ||
| uses: treosh/lighthouse-ci-action@v10 | ||
| uses: treosh/lighthouse-ci-action@v11 | ||
| with: | ||
| urls: | | ||
| ${{ github.event.deployment_status.target_url }} | ||
| uploadArtifacts: true | ||
| temporaryPublicStorage: true | ||
| runs: 1 | ||
| runs: 3 | ||
|
|
||
| - name: Format lighthouse score | ||
| if: env.AUDIT == 'true' | ||
| id: format_lighthouse_score | ||
| uses: actions/github-script@v6 | ||
| uses: actions/github-script@v7 | ||
| with: | ||
| script: | | ||
| const lighthouseCommentMaker = require('./.github/workflows/lighthouseCommentMaker.js'); | ||
|
|
@@ -54,14 +42,12 @@ jobs: | |
| core.setOutput("comment", comment); | ||
| - name: Find pull request | ||
| if: env.AUDIT == 'true' | ||
| uses: jwalton/gh-find-current-pr@v1 | ||
| uses: jwalton/[email protected] | ||
| id: finder | ||
|
|
||
| - name: Add comment to PR | ||
| if: env.AUDIT == 'true' | ||
| id: comment_to_pr | ||
| uses: marocchino/sticky-pull-request-comment@v2.8.0 | ||
| uses: marocchino/sticky-pull-request-comment@v2.9.0 | ||
| with: | ||
| recreate: true | ||
| GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,100 +1,161 @@ | ||
| # Catalyst | ||
| <a href="https://catalyst.dev" target="_blank" rel="noopener norerrer"> | ||
| <img src="https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_banner.png" alt="Catalyst for Composable Commerce Image Banner" title="Catalyst"> | ||
| </a> | ||
|
|
||
| > [!WARNING] | ||
| > - Catalyst is in development and should not be used in production environments. | ||
| <br /> | ||
| <br /> | ||
|
|
||
| **Catalyst** is a composable, fully customizable headless storefront that offers a set of opinionated defaults. It is intended to fit the needs of modern developers, merchants, and shoppers. Catalyst is built with [Next.js (nextjs.org)](https://nextjs.org/) and uses our [React.js-based (react.dev)](https://react.dev/) storefront components. | ||
| <div align="center"> | ||
|
|
||
| The Catalyst monorepo contains the following: | ||
| [](LICENSE.md) | ||
| [](https://github.com/bigcommerce/catalyst/actions/workflows/lighthouse.yml) [](https://github.com/bigcommerce/catalyst/actions/workflows/basic.yml) | ||
|
|
||
| * The core **Catalyst** Next.js storefront, in [apps/core](apps/core). | ||
| * The storefront component library, in [packages/components](packages/components). | ||
| * The BigCommerce [GraphQL Storefront API (BigCommerce Dev Center)](https://developer.bigcommerce.com/docs/graphql-storefront) client, in [packages/client](packages/client). | ||
| </div> | ||
|
|
||
| ## Requirements | ||
| **Catalyst** is the composable, fully customizable headless commerce framework for | ||
| [BigCommerce](https://www.bigcommerce.com/). Catalyst is built with [Next.js](https://nextjs.org/), uses | ||
| our [React](https://react.dev/) storefront components, and is backed by the | ||
| [GraphQL Storefront API](https://developer.bigcommerce.com/docs/storefront/graphql). | ||
|
|
||
| * [Node.js 18+](#node.js) | ||
| * [Corepack-managed pnpm](#corepack-and-pnpm) | ||
| By choosing Catalyst, you'll have a fully-functional storefront within a few seconds, and spend zero time on wiring | ||
| up APIs or building SEO, Accessibility, and Performance-optimized ecommerce components you've probably written many | ||
| times before. You can instead go straight to work building your brand and making this your own. | ||
|
|
||
| ### Node.js | ||
|  | ||
|
|
||
| Use Node.js 18+. | ||
| <p align="center"> | ||
| <a href="https://www.catalyst.dev">🚀 catalyst.dev</a> • | ||
| <a href="https://developer.bigcommerce.com/community">🤗 BigCommerce Developer Community</a> • | ||
| <a href="https://github.com/bigcommerce/catalyst/discussions">💬 GitHub Discussions</a> | ||
| </p> | ||
|
|
||
| You may wish to use Node Version Manager, or [nvm (GitHub)](https://github.com/nvm-sh/nvm#installing-and-updating), to facilitate moving back and forth between different versions of node. You can install nvm using either the instructions at the preceding link or your operating system package manager of choice. | ||
|  | ||
|
|
||
| ### Corepack and pnpm | ||
|
|
||
| This project uses [corepack (nodejs.org)](https://nodejs.org/api/corepack.html) to install and enable the [pnpm (pnpm.io)](https://pnpm.io/) package manager. Corepack comes bundled with Node 18, so you do not need to install either of these packages on their own. | ||
| ## Deploy on Vercel | ||
|
|
||
| Catalyst is configured such that pnpm replaces npm. When you enhance your project with additional packages or scripts, be sure to use the `pnpm` command. For more information, see the [pnpm documentation](https://pnpm.io/cli/add). | ||
| The easiest way to deploy your Catalyst Storefront is to use the [Vercel Platform](https://vercel.com/new) from the creators of Next.js. | ||
|
|
||
| ## Getting Started | ||
| Check out the [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. | ||
|
|
||
| 1. Clone the project to your local environment: | ||
| <div align="left"> | ||
| <a href="https://vercel.com/new/clone?repository-url=https://github.com/bigcommerce/catalyst&env=BIGCOMMERCE_STORE_HASH,BIGCOMMERCE_CHANNEL_ID,BIGCOMMERCE_ACCESS_TOKEN,BIGCOMMERCE_CUSTOMER_IMPERSONATION_TOKEN,AUTH_SECRET,TURBO_REMOTE_CACHE_SIGNATURE_KEY&envDescription=API+Keys+needed+to+deploy+your+Catalyst+Storefront&envLink=https://github.com/bigcommerce/catalyst/blob/main/.env.example&project-name=my-faster-storefront&repository-name=my-faster-storefront&demo-title=BigCommerce+Catalyst+with+Vercel&demo-description=Create+a+BigCommerce+Catalyst+Storefront+and+Deploy+to+Vercel&demo-url=catalyst-git-main.store&demo-image=https://storage.googleapis.com/s.mkswft.com/RmlsZTozODgzZmY3Yy1hNmVlLTQ1MGUtYjRkMS1mMjEyNzgxNjk5MTY%3D/Social-image-Catalyst.png&root-directory=apps/core"><img src="https://vercel.com/button" alt="Deploy with Vercel"/></a> | ||
| </div> | ||
|
|
||
| ```shell | ||
| git clone [email protected]:bigcommerce/catalyst.git && cd catalyst | ||
| ## Quickstart | ||
|
|
||
| Create a new project interactively by running: | ||
|
|
||
| ```bash | ||
| npm create catalyst-storefront@latest | ||
| ``` | ||
|
|
||
| 2. Use corepack to enable pnpm, then use pnpm to install project dependencies: | ||
| You'll then get the following prompts: | ||
|
|
||
| ```console | ||
| ? What would you like to call your project? my-faster-storefront | ||
| ? Which would you like? | ||
| ❯ Link Catalyst to a BigCommerce Store | ||
| Use sample data | ||
|
|
||
| ? Would you like to create a new channel? y | ||
|
|
||
| ? What would you like to name the new channel? My Faster Storefront | ||
|
|
||
| ```shell | ||
| corepack enable pnpm | ||
| Success! Created 'my-faster-storefront' at '/Users/first.last/Documents/GitHub/my-faster-storefront' | ||
| ``` | ||
|
|
||
| ```shell | ||
| pnpm install | ||
| Next steps: | ||
|
|
||
| ```bash | ||
| cd my-faster-storefront && npm run dev | ||
| ``` | ||
| Learn more about Catalyst at [catalyst.dev](https://catalyst.dev). | ||
|
|
||
| 3. **Set up environment variables.** | ||
| ## Resources | ||
|
|
||
| This repository contains a setup script that generates a local development environment file, `.env.local`. The environment file contains the authentication credentials and other variables required to connect Catalyst to an existing BigCommerce store. Run the script from the root directory of this repository and follow the prompts: | ||
| - [GraphQL Storefront API Playground](https://developer.bigcommerce.com/graphql-storefront/playground) | ||
| - [GraphQL Storefront API Explorer](https://developer.bigcommerce.com/graphql-storefront/explorer) | ||
| - [BigCommerce DevDocs](https://developer.bigcommerce.com/docs/build) | ||
|
|
||
| ```shell | ||
| node scripts/setup.mjs | ||
| ``` | ||
| > [!IMPORTANT] | ||
| > The rest of this README is related to development on top of this monorepo. | ||
| > If you just want to build a storefront, start with the [CLI](#quickstart). | ||
| *If you prefer to manually enter your own environment variables, you can run `cp .env.example .env.local` to get started.* | ||
|  | ||
|
|
||
| The following table contains a description of each variable in the `.env.local` file: | ||
| ## Overview | ||
|
|
||
| | Variable | Description | | ||
| |:---------|:------------| | ||
| | `BIGCOMMERCE_STORE_HASH` | The hash visible in the subject store's URL when signed in to the store control panel. The control panel URL is of the form `https://store-{hash}.mybigcommerce.com`. | | ||
| | `BIGCOMMERCE_ACCESS_TOKEN` | The access token from a [store-level API account (BigCommerce Dev Center)](https://developer.bigcommerce.com/api-docs/getting-started/api-accounts#store-level-api-accounts). The only [OAuth scope (BigCommerce Dev Center)](https://developer.bigcommerce.com/api-docs/getting-started/api-accounts#oauth-scopes) required to run Catalyst is Carts `read-only`. | | ||
| | `BIGCOMMERCE_CUSTOMER_IMPERSONATION_TOKEN` | A bearer token that authorizes server-to-server requests to the [GraphQL Storefront API (BigCommerce Dev Center)](https://developer.bigcommerce.com/docs/storefront/graphql). | | ||
| | `BIGCOMMERCE_CHANNEL_ID` | The channel ID for the Catalyst storefront's dedicated channel. | | ||
| | `AUTH_SECRET` | Used by NextAuth, can be generated by running `openssl rand -hex 32` in your terminal. | | ||
| This Catalyst monorepo contains the following: | ||
|
|
||
| 5. Optionally, to optimize your workflow, use the following command to configure VSCode with the project-specific settings the Catalyst team has created: | ||
| - The core **Catalyst** Next.js storefront, in [apps/core](apps/core). This is what is installed when you run the command above in [Quickstart](#quickstart). | ||
| - By default the storefront supports an end-to-end B2C focused shopper journey, inclusive of: | ||
| - Global Header & Footers | ||
| - Home Page | ||
| - Product Listing Pages (Category, Brand, Search/Faceted search, Comparison page) | ||
| - Product Detail Pages | ||
| - Cart | ||
| - Headless Redirected Checkout | ||
| - This includes end-to-end support for most features connected to Customer accounts, like: | ||
| - Price Lists | ||
| - Customer-specific pricing | ||
| - Customer-specific category visibility | ||
| - Customer-specific product visibility | ||
| - To extend into more complex B2C and B2B scenarios, you'll want to utilize more of our [GraphQL Storefront API](https://developer.bigcommerce.com/docs/storefront/graphql). | ||
| - The storefront component library, in [packages/components](packages/components), and a [Storybook](https://storybook.js.org/) instance to view the collection. | ||
| - The BigCommerce [GraphQL Storefront API](https://developer.bigcommerce.com/docs/graphql-storefront) client, in [packages/client](packages/client). | ||
|
|
||
| ```shell | ||
| cp .vscode/settings.example.json .vscode/settings.json | ||
|  | ||
|
|
||
| ### Requirements to use the monorepo | ||
|
|
||
| - Node.js 18+ | ||
| - Corepack-managed `pnpm` | ||
|
|
||
|  | ||
|
|
||
| ### Getting started | ||
|
|
||
| 1. Clone the project to your local environment: | ||
|
|
||
| ```bash | ||
| git clone [email protected]:bigcommerce/catalyst.git && cd catalyst | ||
| ``` | ||
|
|
||
| 6. Start the Catalyst development server! | ||
| 2. Use corepack to enable pnpm, then use pnpm to install project dependencies: | ||
|
|
||
| ```shell | ||
| pnpm run dev | ||
| ```bash | ||
| corepack enable pnpm && pnpm install | ||
| ``` | ||
|
|
||
| The `dev` script runs all packages and apps in watch mode. The 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`. | ||
| 3. Set up environment variables by running: | ||
|
|
||
| | Process | URL with port | | ||
| |:--------|:--------------| | ||
| | Core Catalyst storefront | http://localhost:3000 | | ||
| | Components Storybook | http://localhost:6006 | | ||
| ```bash | ||
| cp .env.example .env.local | ||
| ``` | ||
|
|
||
| Happy developing! Let us know how things are going in the dedicated Slack channel. | ||
| You can find documentation for each field in the `.env.local` file in [.env.example](.env.example). | ||
|
|
||
| ## Deploy using Vercel | ||
| 4. If you use VS Code, use the following command to configure VSCode with the project-specific settings the Catalyst team has created: | ||
|
|
||
| One common way to deploy a Next.js app is to use the [Vercel Platform (vercel.com)](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme). Consult the [Next.js deployment documentation (next.js)](https://nextjs.org/docs/app/building-your-application/deploying) for more details. | ||
| ```bash | ||
| cp .vscode/settings.example.json .vscode/settings.json | ||
| ``` | ||
|
|
||
| ## Resources | ||
| 5. Start the Catalyst development server! | ||
|
|
||
| ```bash | ||
| pnpm run dev | ||
| ``` | ||
|
|
||
| ### Next.js | ||
| The `dev` script runs all packages and apps in watch mode. | ||
| The 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 | | ||
| | Components Storybook | http://localhost:6006 | | ||
|
|
||
| - [Next.js documentation (nextjs.org)](https://nextjs.org/docs) | ||
| - [Interactive Next.js tutorial (nextjs.org)](https://nextjs.org/learn) | ||
| - [Next.js repository (GitHub)](https://github.com/vercel/next.js/) | ||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.