diff --git a/.env.example b/.env.example index 9c28c2ca..bfb92306 100644 --- a/.env.example +++ b/.env.example @@ -3,7 +3,7 @@ BIGCOMMERCE_STORE_HASH= # The access token from a store-level API account. The only scope required to run Catalyst is Carts `read-only`. -# See https://developer.bigcommerce.com/api-docs/getting-started/api-accounts#store-level-api-accounts +# See https://developer.bigcommerce.com/docs/start/authentication/api-accounts#store-level-api-accounts BIGCOMMERCE_ACCESS_TOKEN= # A bearer token that authorizes server-to-server requests to the GraphQL Storefront API @@ -18,5 +18,10 @@ BIGCOMMERCE_CHANNEL_ID=1 # You may also delete /admin/route.ts if you wish. ENABLE_ADMIN_ROUTE=true -# Used by NextAuth, can be generated by running `openssl rand -hex 32` in your terminal. +# Used by NextAuth. To generate, run `openssl rand -hex 32` in your terminal. AUTH_SECRET= + +# Recommended so that you can use Turborepo's Remote Cache feature with signed artifacts +# https://turbo.build/repo/docs/core-concepts/remote-caching#artifact-integrity-and-authenticity-verification +# This can also be generated with `openssl rand -hex 32`, but do not re-use the value from AUTH_SECRET +TURBO_REMOTE_CACHE_SIGNATURE_KEY= diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..eaea5b59 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1 @@ +* @bigcommerce/team-catalyst diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 724791c2..86c1f373 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -1,7 +1,7 @@ blank_issues_enabled: false contact_links: - name: Have questions? - url: https://catalyst.dev/docs + url: https://github.com/bigcommerce/catalyst/blob/main/README.md about: Explore the Catalyst Docs. - name: Need help with Catalyst? url: https://github.com/bigcommerce/catalyst/discussions/new?category=q-a diff --git a/.github/workflows/basic.yml b/.github/workflows/basic.yml index e7c21adc..9fd01c1a 100644 --- a/.github/workflows/basic.yml +++ b/.github/workflows/basic.yml @@ -17,6 +17,7 @@ jobs: env: TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} TURBO_TEAM: ${{ vars.TURBO_TEAM }} + TURBO_REMOTE_CACHE_SIGNATURE_KEY: ${{ secrets.TURBO_REMOTE_CACHE_SIGNATURE_KEY }} BIGCOMMERCE_STORE_HASH: ${{ secrets.BIGCOMMERCE_STORE_HASH }} BIGCOMMERCE_CUSTOMER_IMPERSONATION_TOKEN: ${{ secrets.BIGCOMMERCE_CUSTOMER_IMPERSONATION_TOKEN }} diff --git a/.github/workflows/lighthouse.yml b/.github/workflows/lighthouse.yml index 4bd1de37..b1d9f1b9 100644 --- a/.github/workflows/lighthouse.yml +++ b/.github/workflows/lighthouse.yml @@ -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/gh-find-current-pr@v1.3.3 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 }} diff --git a/.github/workflows/lighthouseCommentMaker.js b/.github/workflows/lighthouseCommentMaker.js index f7e56eea..e09989b3 100644 --- a/.github/workflows/lighthouseCommentMaker.js +++ b/.github/workflows/lighthouseCommentMaker.js @@ -37,7 +37,7 @@ const scoreRow = ( * @param {LighthouseOutputs} lighthouseOutputs */ function makeComment(lighthouseOutputs) { - const { summary } = lighthouseOutputs.manifest[0]; + const { summary } = lighthouseOutputs.manifest[2]; const [[testedUrl, reportUrl]] = Object.entries(lighthouseOutputs.links); const comment = `## ⚡️🏠 Lighthouse report diff --git a/README.md b/README.md index 08ff8524..f297e373 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,161 @@ -# Catalyst + + Catalyst for Composable Commerce Image Banner + -> [!WARNING] -> - Catalyst is in development and should not be used in production environments. +
+
-**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. +
-The Catalyst monorepo contains the following: +[![MIT License](https://img.shields.io/github/license/bigcommerce/catalyst)](LICENSE.md) +[![Lighthouse Report](https://github.com/bigcommerce/catalyst/actions/workflows/lighthouse.yml/badge.svg)](https://github.com/bigcommerce/catalyst/actions/workflows/lighthouse.yml) [![Lint, Typecheck, GraphQL Codegen](https://github.com/bigcommerce/catalyst/actions/workflows/basic.yml/badge.svg)](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). +
-## 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 +![-----------------------------------------------------](https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_hr.png) -Use Node.js 18+. +

+ 🚀 catalyst.dev • + 🤗 BigCommerce Developer Community • + 💬 GitHub Discussions +

-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. +![-----------------------------------------------------](https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_hr.png) -### 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: +
+ Deploy with Vercel +
-```shell -git clone git@github.com: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.* +![-----------------------------------------------------](https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_hr.png) -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 +![-----------------------------------------------------](https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_hr.png) + +### Requirements to use the monorepo + +- Node.js 18+ +- Corepack-managed `pnpm` + +![-----------------------------------------------------](https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_hr.png) + +### Getting started + +1. Clone the project to your local environment: + +```bash +git clone git@github.com: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/) +![-----------------------------------------------------](https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_hr.png) diff --git a/apps/core/.eslintrc.cjs b/apps/core/.eslintrc.cjs index d0a7c7bf..73f10fa2 100644 --- a/apps/core/.eslintrc.cjs +++ b/apps/core/.eslintrc.cjs @@ -25,9 +25,14 @@ const config = { ], }, ], - 'check-file/filename-naming-convention': 'off', - 'check-file/folder-naming-convention': 'off', + 'check-file/folder-naming-convention': [ + 'error', + { + '**': 'NEXT_JS_APP_ROUTER_CASE', + }, + ], }, + ignorePatterns: ['client/generated/**/*.ts'], }; module.exports = config; diff --git a/apps/core/README.md b/apps/core/README.md index 0e9c1e68..41b7563d 100644 --- a/apps/core/README.md +++ b/apps/core/README.md @@ -1,86 +1,59 @@ -# Catalyst + + Catalyst for Composable Commerce Image Banner + -Catalyst is the next generation of storefronts at BigCommerce. It aims to be composable and powerful to meet the needs of our enterprise customers, exceeding performance of Stencil and Blueprint themes. Catalyst is built with [Next.js](https://nextjs.org/) using our React.js storefront component library. +
-## Getting Started +**Catalyst** is the composable, fully customizable headless ecommerce storefront 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). -1. Install project dependencies: +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. -```bash -corepack enable pnpm -pnpm install -``` +
-2. Setup environment variables: +![-----------------------------------------------------](https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_hr.png) -```bash - cp .env.example .env.local -``` +
-Update `.env.local` with your access-token, store-hash and channel-id. - -For a list of recommended scopes to use for your access token, please expand the table below. - -
- Expand - -| Scope | Permission Level | -| -------------------------------------------- | ---------------- | -| Content | `read-only` | -| Checkout Content | `None` | -| Customers | `read-only` | -| Customers Login | `login` | -| Information & Settings | `read-only` | -| Marketing | `read-only` | -| Orders | `read-only` | -| Order Transactions | `read-only` | -| Create Payments | `None` | -| Get Payment Methods | `read-only` | -| Stored Payment Instruments | `read-only` | -| Products | `read-only` | -| Themes | `read-only` | -| Carts | `read-only` | -| Checkouts | `read-only` | -| Sites & Routes | `read-only` | -| Channel Settings | `None` | -| Channel Listings | `None` | -| Storefront API Tokens | `None` | -| Storefront API Customer Impersonation Tokens | `manage` | -| Store Logs | `None` | -| Store Locations | `read-only` | -| Store Inventory | `read-only` | -| Fulfillment Methods | `None` | -| Order Fulfillment | `None` | - -
- -3. Run the development server: - -```bash -pnpm run dev -``` +

+ 🚀 catalyst.dev • + 🤗 BigCommerce Developer Community • + 💬 GitHub Discussions +

-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result. +
-You can start editing the page by modifying `pages/index.tsx`. The page auto-updates as you edit the file. +![-----------------------------------------------------](https://storage.googleapis.com/bigcommerce-developers/images/catalyst_readme_hr.png) -[API routes](https://nextjs.org/docs/api-routes/introduction) can be accessed on [http://localhost:3000/api/graphql](http://localhost:3000/api/graphql). This endpoint can be edited in `pages/api/graphql.ts`. +
-The `pages/api` directory is mapped to `/api/*`. Files in this directory are treated as [API routes](https://nextjs.org/docs/api-routes/introduction) instead of React pages. +## Requirements -This project uses [`next/font`](https://nextjs.org/docs/basic-features/font-optimization) to automatically optimize and load Inter, a custom Google Font. +- Node.js 18+ +- `npm` (or `pnpm`/`yarn`) -## Learn More +## Getting started -To learn more about Next.js, take a look at the following resources: +If this installation of Catalyst was created using the `catalyst-storefront` CLI, you should already be connected to a store and can get started immediately by running: -- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API. -- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial. +```shell +npm run dev +``` + +If you want to connect to another store or channel, you can run the setup process again by running: -You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js/) - your feedback and contributions are welcome! +```shell +npx create-catalyst-storefront@latest init +``` -## Deploy on Vercel +Learn more about Catalyst at [catalyst.dev](https://catalyst.dev). -The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js. +## Resources -Check out our [Next.js deployment documentation](https://nextjs.org/docs/deployment) for more details. +- [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) diff --git a/apps/core/app/(default)/(faceted)/_components/breadcrumbs.tsx b/apps/core/app/(default)/(faceted)/_components/breadcrumbs.tsx index a721dab3..c593036a 100644 --- a/apps/core/app/(default)/(faceted)/_components/breadcrumbs.tsx +++ b/apps/core/app/(default)/(faceted)/_components/breadcrumbs.tsx @@ -2,11 +2,11 @@ import { BreadcrumbDivider, BreadcrumbItem, Breadcrumbs as ComponentsBreadcrumbs, -} from '@bigcommerce/components/Breadcrumbs'; +} from '@bigcommerce/components/breadcrumbs'; import { ChevronRight } from 'lucide-react'; import { Fragment } from 'react'; -import { Link } from '~/components/Link'; +import { Link } from '~/components/link'; interface Props { breadcrumbs: Array<{ @@ -22,7 +22,7 @@ export const Breadcrumbs = ({ breadcrumbs, category }: Props) => ( {breadcrumbs.map(({ name, entityId, path }, index) => { if (!path || breadcrumbs.length - 1 === index) { return ( - + {name} ); diff --git a/apps/core/app/(default)/(faceted)/_components/facets.tsx b/apps/core/app/(default)/(faceted)/_components/facets.tsx index 02dc8b98..adb0cead 100644 --- a/apps/core/app/(default)/(faceted)/_components/facets.tsx +++ b/apps/core/app/(default)/(faceted)/_components/facets.tsx @@ -5,17 +5,17 @@ import { AccordionContent, AccordionItem, AccordionTrigger, -} from '@bigcommerce/components/Accordion'; -import { Button } from '@bigcommerce/components/Button'; -import { Checkbox } from '@bigcommerce/components/Checkbox'; -import { Input } from '@bigcommerce/components/Input'; -import { Label } from '@bigcommerce/components/Label'; -import { Rating } from '@bigcommerce/components/Rating'; +} from '@bigcommerce/components/accordion'; +import { Button } from '@bigcommerce/components/button'; +import { Checkbox } from '@bigcommerce/components/checkbox'; +import { Input } from '@bigcommerce/components/input'; +import { Label } from '@bigcommerce/components/label'; +import { Rating } from '@bigcommerce/components/rating'; import { usePathname, useRouter, useSearchParams } from 'next/navigation'; import { FormEvent, useRef } from 'react'; import { RatingSearchFilterItem } from '~/client/generated/graphql'; -import { Link } from '~/components/Link'; +import { Link } from '~/components/link'; import { cn } from '~/lib/utils'; import type { Facet, PageType } from '../types'; @@ -115,7 +115,11 @@ export const Facets = ({ facets, pageType }: Props) => { onCheckedChange={submitForm} value={brand.entityId} /> -