Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
116 changes: 108 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,10 +1,110 @@
# catalyst-commerce

[Vercel's Catalyst by BigCommerce](https://github.com/bigcommerce/catalyst) on
**Cloudflare Workers**, deployed by [Orun](https://github.com/sourceplane/orun) to stage
and prod on every merge, and then packaged as an Orun baseline.

This commit is the repository's frame: `intent.yaml` (with the placeholder
workspace `ws_CHANGE_ME`, so CI plans nothing until it is linked), the Orun
CI workflow, the shared TypeScript and ESLint configuration, and the spec
index. The work is tracked as an epic under [`specs/epics`](specs/epics/README.md).
[BigCommerce's Catalyst](https://github.com/bigcommerce/catalyst) (MIT, the
storefront Vercel lists as Catalyst by BigCommerce) — home, categories,
brands, faceted search, product pages with options and variants, a cart,
the store's checkout, accounts, orders and wish lists, a blog and gift
certificates, in several languages, every BigCommerce read cached in Next's
data cache — running on **Cloudflare Workers + Static Assets** through
[`@opennextjs/cloudflare`](https://opennext.js.org/cloudflare), with the data
cache in an **R2 bucket** and its route lookups in a **KV namespace**, both
provisioned by Terraform through [Orun](https://github.com/sourceplane/orun),
and the tag cache and revalidation queue in **Durable Objects** the Worker
itself exports, deployed by
[Orun](https://github.com/sourceplane/orun) to stage and prod on every merge.
Packaging it as an Orun baseline is the next milestone (CA2).

A fresh build needs no BigCommerce store: until its owner connects one, `/`
says "Connect your BigCommerce store" and every other page goes there —
never a 500. The owner connects a store by setting its hash and a storefront
token (and channel) as Orun secrets and redeploying. The account must be on **Workers Paid** (the Worker
is about 3.4 MiB gzipped). See
[`specs/epics/catalyst-commerce`](specs/epics/catalyst-commerce/README.md) for the design, the
milestones and the as-built status.

## What is here (the product)

| Surface | Where |
|---|---|
| The storefront's routes: `/[locale]/…`, `/api/auth`, `/api/health`, `/sitemap.xml`, `/robots.txt` | `apps/web/app` |
| The store's fallback name | `apps/web/lib/site.ts` (`SITE_NAME`) |
| Whether a store is connected; the page that says how to connect one | `apps/web/lib/bigcommerce-connection.ts`, `apps/web/app/connect-store`, `apps/web/proxy.ts` |
| The GraphQL client and the queries | `packages/client`, `apps/web/client` |
| BigCommerce's Storefront schema the types are generated from | `apps/web/bigcommerce.graphql` |
| The Worker entry and the generated session key | `apps/web/worker.ts`, `apps/web/lib/auth-secret.ts` |
| Workers build, cache bindings and deploy contract | `apps/web/next.config.ts`, `open-next.config.ts`, `wrangler.template.jsonc` + `wiring.fixture.json` (→ the committed `wrangler.jsonc`), `component.yaml` |
| The R2 bucket and the KV namespace (stage, prod) | `infra/terraform/cloudflare-r2`, `infra/terraform/cloudflare-kv` |
| The wrangler renderer and the Worker-secrets step | `tooling/wire` |
| Tests | `apps/web` (upstream's 286-test vitest suite), `tests/web` (the port's seams) |

## Getting started

```bash
pnpm install
pnpm run wire:fixture # render apps/web/wrangler.jsonc from the offline fixture
pnpm typecheck
pnpm lint
pnpm test
pnpm build # GraphQL types + next build --webpack + opennextjs-cloudflare build → apps/web/.open-next
```

```bash
pnpm --filter @app/web dev # http://localhost:3000, Next's dev server (Node 24: URLPattern)
pnpm --filter @app/web preview # wrangler dev over the built Worker: local R2, KV and Durable Objects
```

With no store hash and token both serve the "connect your BigCommerce store"
page. To run against a store, put `BIGCOMMERCE_STORE_HASH` and
`BIGCOMMERCE_STOREFRONT_TOKEN` in the shell you build from and in
`apps/web/.dev.vars`. Offline, the e2e's stand-in answers every query from
the schema:
`node testing/lib/fake-bigcommerce.mjs --schema apps/web/bigcommerce.graphql --graphql apps/web --port 4010`,
with `BIGCOMMERCE_GRAPHQL_API_ORIGIN=http://127.0.0.1:4010` beside the store's settings.

## How it maps to Vercel

| Vercel | Here |
|---|---|
| Next.js hosting (SSR, server actions, route handlers, the proxy) | One Cloudflare Worker (`worker.ts` over `.open-next/worker.js`) + Static Assets (`ASSETS`) |
| Data Cache entries | The R2 bucket bound as `NEXT_INC_CACHE_R2_BUCKET` |
| `revalidateTag` | A sharded Durable Object tag cache (`NEXT_TAG_CACHE_DO_SHARDED`) consulted on every cache read |
| Stale-while-revalidate | A Durable Object queue (`NEXT_CACHE_DO_QUEUE`) that re-reads stale entries through the Worker's `WORKER_SELF_REFERENCE` binding |
| Vercel Runtime Cache (route lookups) | Catalyst's own KV adapter, the namespace bound as `CATALYST_ROUTES_KV` |
| `AUTH_SECRET` | Generated by the Worker and kept in KV; the Orun secret `AUTH_SECRET` wins |
| `BIGCOMMERCE_STORE_HASH`, `BIGCOMMERCE_STOREFRONT_TOKEN`, `BIGCOMMERCE_CHANNEL_ID` | Optional Orun secrets, read by the build and set as Worker secrets by the deploy — and, unset, the "connect your BigCommerce store" page instead of a failed build |
| The GraphQL schema generated from the live store | BigCommerce's published Storefront schema, committed (`apps/web/bigcommerce.graphql`) |
| `NEXTAUTH_URL` | Each environment's `SITE_URL`, else its workers.dev URL, set by the build |
| Vercel Web Analytics, Speed Insights | Off unless the build runs on Vercel |
| Deploy on push | Orun applies the bucket and the namespace and deploys `<repo>-web-{stage,prod}` on merge to `main` (`apps/web/component.yaml`) |
| "Deploy with Vercel" (clone the template) | `orun new --blueprint repo-blueprint.yaml` — a new repository, branded, deployed |

Partial prerendering is off: `@opennextjs/cloudflare` 1.20 cannot run Next 16's
Cache Components on workerd yet (a Cache Components page answers 500 and then
hangs — opennextjs-cloudflare#1450), so the storefront keeps upstream's
`"use cache"` reads through `experimental.useCache` and renders every route at
request time. The epic's [IMPLEMENTATION-STATUS](specs/epics/catalyst-commerce/IMPLEMENTATION-STATUS.md)
has the evidence.

## How the bucket reaches the Worker

```
infra/terraform/cloudflare-r2 ──apply (r2-data token)──► orun secret WIRING_CLOUDFLARE_R2 (stage, prod)
│ (each deploy resolves it as it starts;
│ a missing one fails the lane)
▼
apps/web dependsOn cloudflare-r2 (enforced on main) · secretEnv WIRING_CLOUDFLARE_R2_<ENV>
build: tooling/wire/live.mjs → wrangler.jsonc with the environment's bucket name
(dev, verify-only, renders the fixture) → next build → opennextjs-cloudflare
deploy: workers-deploy token → <repo>-web-<env>, its Durable Objects migrated on first deploy
```

`wrangler.jsonc` is committed as the fixture render of
`wrangler.template.jsonc`, because the deploy lane's `verify-app-structure`
step checks the config exists before it builds; `testing/e2e.test.sh` fails
if the two disagree.

## CI

| Workflow | What it runs | Ships to a product |
|---|---|---|
| `ci.yml` | the Orun pipeline, and the only workflow a product carries: `orun plan --changed`, then one job per lane. A pull request runs the verify lanes (the R2 and KV roots planned for stage and prod, the storefront built and dry-deployed per environment; they neither lint nor run the tests, which `baseline.yml`'s e2e tier runs before every tag), except the bootstrap's own landings (`orun/BASE-*`), where `plan` alone runs and nothing waits for it (the landing checked its commit in the box); a merge applies the R2 bucket, then deploys stage → prod. It plans nothing while `intent.yaml` names the placeholder workspace `ws_CHANGE_ME`, as this repository does. A manual run (Orunbase's Deploy button, or Run workflow on `main`) plans the environment and components it names under the push-to-main trigger, so they deploy as a merge deploys them | yes |
50 changes: 50 additions & 0 deletions apps/web/.env.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,50 @@
# 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_STORE_HASH=

# A JWT Token for accessing the Storefront API. Enables server-to-server requests if allowed_cors_origins is omitted.
# See https://developer.bigcommerce.com/docs/rest-authentication/tokens#storefront-tokens
BIGCOMMERCE_STOREFRONT_TOKEN=
BIGCOMMERCE_STOREFRONT_UNAUTHENTICATED_TOKEN=

# The Channel ID for the selling channel being serviced by this Catalyst storefront.
# Channel ID 1 will allow you to load the same data being used on the default Stencil storefront on your store,
# but it is strongly recommended to create a new channel instead for production.
# The CLI can do this for you.
BIGCOMMERCE_CHANNEL_ID=1

# Set to true to allow the /admin route to redirect to the BigCommerce control panel.
# `false` is recommended for production. Defaults to false when not specified.
# You may also delete /admin/route.ts if you wish.
ENABLE_ADMIN_ROUTE=true

# Used by Auth.js, formerly 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=

# NextJS will persists cached queries in Data Cache
# The time persisted is not defined
# https://nextjs.org/docs/app/building-your-application/caching#data-cache
# This sets a sensible revalidation target for cached requests
DEFAULT_REVALIDATE_TARGET=3600

# OpenTelemetry Configuration (Optional)
# See OPENTELEMETRY.md for detailed setup and usage instructions
# See https://nextjs.org/docs/app/guides/open-telemetry for Next.js guide

# Set a custom service name for your traces (defaults to 'next-app')
# OTEL_SERVICE_NAME=catalyst-storefront

# Enable verbose tracing to see all spans (useful for debugging, increases data volume)
# NEXT_OTEL_VERBOSE=1

# Disable automatic fetch instrumentation (not recommended unless using custom instrumentation)
# NEXT_OTEL_FETCH_DISABLED=1

# Checkout SDK loader URL used in local development for wallet buttons.
# In non-development environments the production CDN loader is always used.
NEXT_PUBLIC_CHECKOUT_SDK_DEV_URL=
58 changes: 58 additions & 0 deletions apps/web/.env.test.example
Original file line number Diff line number Diff line change
@@ -0,0 +1,58 @@
# This file should hold any environment variables specific to test execution.
# Any overlapping variables in here will overwrite variables from the other .env files.
# For example, if BIGCOMMERCE_CHANNEL_ID=1 in .env.local, but BIGCOMMERCE_CHANNEL_ID=5 in this file, the test environment will use BIGCOMMERCE_CHANNEL_ID=5

# Access token client ID and client secret are required for JWT login tests. If not provided, tests that require these will be skipped.
# If provided, ensure the API account associated with this client ID/secret pair has the following scope:
# - Customers login: login
BIGCOMMERCE_CLIENT_ID=
BIGCOMMERCE_CLIENT_SECRET=

# Base URL for all tests. This should always be set. It is recommended to run tests against a production build.
# If not set or undefined, it will default to 'http://localhost:3000'
PLAYWRIGHT_TEST_BASE_URL=http://localhost:3000

# If true, no tests will execute that require modifying/deleting any data on your store.
# This is particularly useful if you want to run the tests against a live store and avoid test data being visible to any customers.
# If this is false, you should only run tests against a staging store where test data is okay.
TESTS_READ_ONLY=false

# Locale to use during test execution
TESTS_LOCALE=en

# The fallback locale to use in the occurence of missing translation keys in the selected TESTS_LOCALE
# This should match the default locale you have set for your storefront
TESTS_FALLBACK_LOCALE=en

# An existing customer account to use for all tests - use this if you don't want tests to create a new customer account.
# If TESTS_READ_ONLY is `true`, then any test requiring a customer will be skipped if these values are not set.
TEST_CUSTOMER_ID=1
TEST_CUSTOMER_EMAIL=example@test.com
TEST_CUSTOMER_PASSWORD=Password1

# Used to create/update/delete store data for testing purposes
# Some tests will not pass without a BIGCOMMERCE_ACCESS_TOKEN, even with TESTS_READ_ONLY set to true
# This is due to the test API client sending GET (read-only) API requests
# Create a token with the following scopes:
# - Content: read-only
# - Products: read-only
# - Channel listings: read-only
# - Channel settings: read-only
# - Information & settings: read-only
# - Customers: read-only
# - Orders: read-only
# When TESTS_READ_ONLY is false, you'll need additional scopes:
# - Products: modify
# - Content: modify
# - Customers: modify
# - Marketing: modify
# - Orders: modify
BIGCOMMERCE_ACCESS_TOKEN=

# The default product ID to use for tests. This needs to be a product without variants (simple)
# This is optional, but recommended. If left empty, tests that require a product will be skipped if TESTS_READ_ONLY is true
DEFAULT_PRODUCT_ID=

# The default product ID to use for tests that require a complex product. This product must have at least 1 variant.
# This is optional, but recommended. If left empty, tests that require a complex product will be skipped if TESTS_READ_ONLY is true
DEFAULT_COMPLEX_PRODUCT_ID=
27 changes: 27 additions & 0 deletions apps/web/.eslintignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# Dependencies
node_modules/

# Build outputs
.next/
.wrangler/
.open-next/
out/
dist/
build/

# Generated files
.turbo/
messages/*.d.json.ts
next-env.d.ts
*-graphql.d.ts

# Test outputs
playwright-report/
test-results/
.tests/

# Cache
.eslintcache

# The Worker entry wraps the build output (see its header)
worker.ts
88 changes: 88 additions & 0 deletions apps/web/.eslintrc.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
// @ts-check

require('@bigcommerce/eslint-config/patch');

/** @type {import('eslint').Linter.LegacyConfig} */
const config = {
root: true,
extends: [
'@bigcommerce/catalyst/base',
'@bigcommerce/catalyst/react',
'@bigcommerce/catalyst/next',
'@bigcommerce/catalyst/prettier',
],
rules: {
'@typescript-eslint/naming-convention': 'off',
'@next/next/no-html-link-for-pages': 'off',
'import/dynamic-import-chunkname': 'off',
'no-underscore-dangle': ['error', { allow: ['__typename'] }],
'@typescript-eslint/prefer-nullish-coalescing': 'off',
'@typescript-eslint/no-unsafe-enum-comparison': 'off',
'@typescript-eslint/no-restricted-imports': [
'error',
{
paths: [
{
name: 'next/link',
message: "Please import 'Link' from '~/components/Link' instead.",
},
{
name: 'next/image',
importNames: ['default'],
message:
"Please import 'Image' from '~/components/image' instead. This component handles CDN and static image optimization.",
},
{
name: '~/i18n/routing',
importNames: ['Link'],
message: "Please import 'Link' from '~/components/Link' instead.",
},
{
name: 'next/router',
importNames: ['useRouter'],
message: 'Please import from `~/i18n/routing` instead.',
},
{
name: 'next/navigation',
importNames: ['redirect', 'permanentRedirect', 'useRouter', 'usePathname'],
message:
'Please import `useRouter`/`usePathname` from `~/i18n/routing`, and `redirect`/`permanentRedirect` from `~/i18n/navigation-server`, so that merchant-configured locale subfolders are applied.',
},
{
name: '@playwright/test',
importNames: ['expect', 'test'],
message: 'Please import from `~/tests/fixtures` instead.',
},
],
},
],
'check-file/folder-naming-convention': [
'error',
{
'**': 'NEXT_JS_APP_ROUTER_CASE',
},
],
},
overrides: [
{
files: ['**/*.spec.ts', '**/*.test.ts'],
rules: {
'@typescript-eslint/no-restricted-imports': [
'error',
{
paths: [
{
name: 'next-intl/server',
importNames: ['getTranslations', 'getFormatter'],
message:
'Please import `getTranslations` from `~/tests/lib/i18n` and `getFormatter` from `~/tests/lib/formatter` instead.',
},
],
},
],
},
},
],
};

module.exports = config;
Loading
Loading