Skip to content

Commit a484789

Browse files
jamesqquickjamesqquick
authored
doc(catalyst): Add native hosting docs, CLI reference, and reorganize deployment (#1278)
Jira: [CATALYST-1807](https://bigcommercecloud.atlassian.net/browse/CATALYST-1807) ## What/Why? - Moves `getting-started/deploying/` to a top-level `catalyst/deployment/` directory and updates all internal links - Adds **Native Hosting** docs under `deployment/native-hosting/` (overview and getting-started) - Adds **Catalyst CLI** reference page under `reference/cli` - Adds a closed alpha callout with a link to the [Native Hosting interest form](https://docs.google.com/forms/d/e/1FAIpQLSfDepq3qRtEtavb1wQvSvdK21pwr_kNsYQbH2B7JjWYyptUSA/viewform?usp=header) on all three new docs - Fixes Google Docs `?tab=t.` links in the native hosting/CLI content, replacing them with proper `/docs/` paths ### Nav/URL config (companion change needed) The nav/URL structure repo needs corresponding updates: | Old path | New path | |---|---| | `storefront/catalyst/getting-started/deploying/overview` | `storefront/catalyst/deployment/overview` | | `storefront/catalyst/getting-started/deploying/vercel` | `storefront/catalyst/deployment/vercel` | | _(new)_ | `storefront/catalyst/deployment/native-hosting/overview` | | _(new)_ | `storefront/catalyst/deployment/native-hosting/getting-started` | | _(new)_ | `storefront/catalyst/reference/cli` | ## Test plan - [ ] Verify the moved deployment docs render correctly at their new URLs - [ ] Confirm native hosting overview and getting-started pages render with the closed alpha callout - [ ] Confirm the CLI reference page renders with the closed alpha callout - [ ] Verify all internal cross-links resolve correctly - [ ] Coordinate companion nav/URL config change in the other repo Made with [Cursor](https://cursor.com) [CATALYST-1807]: https://bigcommercecloud.atlassian.net/browse/CATALYST-1807?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
1 parent 64625a1 commit a484789

9 files changed

Lines changed: 443 additions & 5 deletions

File tree

‎docs/storefront/catalyst/deployment/native-hosting/getting-started.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
# Getting Started
2+
3+
<Callout type="warning">
4+
The Catalyst CLI and Native Hosting are currently in closed alpha. There may be breaking changes as we finalize the API. To express interest in gaining access, fill out the [Native Hosting Closed Alpha Interest Form](https://docs.google.com/forms/d/e/1FAIpQLSfDepq3qRtEtavb1wQvSvdK21pwr_kNsYQbH2B7JjWYyptUSA/viewform?usp=header).
5+
</Callout>
6+
7+
Below, you’ll find the steps for using the Catalyst CLI to deploy your Catalyst application. Make sure to read the [Overview](/docs/storefront/catalyst/deployment/native-hosting/overview) documentation for an overview of BigCommerce’s hosting infrastructure, how configuration variables work, etc.
8+
9+
## Prerequisites
10+
11+
1. **Local Catalyst repository** \- This can be created either via the [One-Click Catalyst app](https://developer.bigcommerce.com/docs/storefront/catalyst/getting-started/local-development) or [manually](https://developer.bigcommerce.com/docs/storefront/catalyst/development/manual-installation).
12+
2. **The Native Hosting feature flag enabled \-** This flag enables the core hosting APIs and allows you to create an API Account with the correct permissions. While Native Hosting is in closed Alpha, you must be approved to have this flag turned on.
13+
3. Configuration variables \- Refer to the [Overview](/docs/storefront/catalyst/deployment/native-hosting/overview) documentation for which variables are needed and where they are read from
14+
4. Your store user account must have "high-risk user permissions" to create [**Store-level API Accounts**](https://support.bigcommerce.com/s/article/Store-API-Accounts).
15+
16+
## Installation
17+
18+
Install the Catalyst CLI and the OpenNext Cloudflare adapter in the `core` directory of your Catalyst project.
19+
20+
```shell
21+
cd core
22+
pnpm add @bigcommerce/catalyst@alpha @opennextjs/cloudflare
23+
```
24+
25+
In the `scripts` section of your `core/package.json` file, replace `next build` with `catalyst build` in the `build` script. Then, add a new script for deploying: `"deploy": "catalyst deploy"`. The `dev` and `start` scripts remain unchanged and continue to use `next dev` and `next start` directly.
26+
27+
The final result will look like this.
28+
29+
```json
30+
{
31+
"build": "npm run generate && catalyst build",
32+
//...leave the other scripts as-is
33+
"deploy": "catalyst deploy", // This is the only new script
34+
}
35+
```
36+
37+
For running Catalyst locally, you will still use the same terminal command you used in the past, `pnpm dev`.
38+
39+
## Usage
40+
41+
The Catalyst CLI provides several commands for deploying a Catalyst storefront application to BigCommerce’s infrastructure. See the [CLI Reference](/docs/storefront/catalyst/reference/cli) for a full list of commands and details.
42+
43+
### Authenticate
44+
45+
Before running any commands that interact with the BigCommerce API, you need to provide your store credentials. How you do this depends on your environment:
46+
47+
**Local development (interactive)**: Run `pnpm catalyst auth login` to authenticate via your browser. The CLI will walk you through an OAuth flow and store your credentials locally in `.bigcommerce/project.json`.
48+
49+
```
50+
pnpm catalyst auth login
51+
```
52+
53+
After logging in, you can omit the `--store-hash` and `--access-token` flags from all subsequent commands — the CLI will read them from `project.json` automatically.
54+
55+
**CI/CD (non-interactive)** — In environments like GitHub Actions where a browser is not available, provide credentials via environment variables (`CATALYST_STORE_HASH`, `CATALYST_ACCESS_TOKEN`) or pass them directly as flags (`--store-hash` and `--access-token`) on each command. See the [Overview](/docs/storefront/catalyst/deployment/native-hosting/overview) documentation for the full configuration priority order.
56+
57+
### Create a project
58+
59+
Run the `project create` command to create a new BigCommerce infrastructure project.
60+
61+
```
62+
pnpm catalyst project create
63+
```
64+
65+
Alternatively, if you’ve already created a project, you can link to an existing one if you know the project’s uuid using the `project link` command.
66+
67+
```
68+
pnpm catalyst project link --project-uuid <PROJECT_UUID>
69+
```
70+
71+
After creating a new project or linking to an existing one, a `.bigcommerce/project.json` file should have been created for you. This file will store the necessary configuration variables such as your store hash, access token, etc. **Since this file includes an access token, it should not be checked into source control**.
72+
73+
### Deploy your Catalyst project
74+
75+
When you’re ready, run the `deploy` command to build your Catalyst project and deploy those build assets to BigCommerce’s hosting infrastructure.
76+
77+
In addition to the `deploy` command depending on the configuration variables mentioned in the creation step, you’ll also need to include the runtime variables necessary for Catalyst. See the [Environment Variables](https://developer.bigcommerce.com/docs/storefront/catalyst/development/environment-variables) documentation for a full list of required variables.
78+
79+
You’ll need to pass each of your runtime variables into the `deploy` command as a secret by using the `--secret` flag. The `--secret` flag ensures that each of your variables is encrypted and is not human readable after creation.
80+
81+
For example, to pass the `BIGCOMMERCE_STORE_HASH` and `BIGCOMMERCE_STOREFRONT_TOKEN` variables, the command would look like this:
82+
83+
```
84+
pnpm catalyst deploy --secret BIGCOMMERCE_STORE_HASH=<YOUR_STORE_HASH> --secret BIGCOMMERCE_STOREFRONT_TOKEN=<YOUR_STOREFRONT_TOKEN>
85+
```
86+
87+
Again, make sure to pass all necessary runtime variables.

‎docs/storefront/catalyst/deployment/native-hosting/overview.mdx‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Native Hosting Overview
2+
3+
<Callout type="warning">
4+
The Catalyst CLI and Native Hosting are currently in closed alpha. There may be breaking changes as we finalize the API. To express interest in gaining access, fill out the [Native Hosting Closed Alpha Interest Form](https://docs.google.com/forms/d/e/1FAIpQLSfDepq3qRtEtavb1wQvSvdK21pwr_kNsYQbH2B7JjWYyptUSA/viewform?usp=header).
5+
</Callout>
6+
7+
BigCommerce provides hosting for your Catalyst projects, allowing you to fully deploy your Catalyst storefront without having to depend on an external hosting provider.
8+
9+
To get started using the Catalyst CLI to deploy your Catalyst project, refer to the [Getting Started docs](/docs/storefront/catalyst/deployment/native-hosting/getting-started).
10+
11+
12+
## Core Concepts
13+
14+
To understand BigCommerce’s Native Hosting for Catalyst, here are a few concepts you need to know.
15+
16+
### Project
17+
18+
A project is the top-level infrastructure container for your application. You create a project once, then use it as the target for future deployments of that storefront.
19+
20+
### Deployment
21+
22+
A deployment is a specific version of your project that has been built and released. Each deployment reflects the state of the code at a point in time (when it was built and successfully deployed).
23+
24+
### OpenNext
25+
26+
[OpenNext](https://opennext.js.org/) is an open source project that strives to support Next.js being hosted across different platforms while maintaining feature parity with Vercel. OpenNext provides adapters for deploying to different hosting providers like Cloudflare, Netlify, AWS, etc. For deploying to BigCommerce’s hosting infrastructure, you will need to install the OpenNext Cloudflare adapter in your repository as defined in the **Installation** section below.
27+
28+
See the [OpenNext Cloudflare documentation](https://opennext.js.org/cloudflare) for more details.
29+
30+
## Authentication
31+
32+
The Catalyst CLI supports two ways to authenticate, depending on where it's running:
33+
34+
- **Interactive (local development)** — Run `catalyst auth login` to authenticate via your browser using OAuth. After logging in, your store hash and access token are stored locally in `.bigcommerce/project.json` for use by other CLI commands. Use `catalyst auth logout` to remove stored credentials, and `catalyst auth whoami` to verify your current session.
35+
- **Non-interactive (CI/CD)** — In environments like GitHub Actions or CircleCI where a browser is not available, provide your store hash and access token directly via CLI flags (`--store-hash`, `--access-token`), environment variables (`CATALYST_STORE_HASH`, `CATALYST_ACCESS_TOKEN`), or an env file. See the [Configuration](#configuration) section below for the full priority order.
36+
37+
See the [CLI Reference](/docs/storefront/catalyst/reference/cli) for full details on the auth commands.
38+
39+
## Configuration
40+
41+
The Catalyst CLI depends on several configuration variables:
42+
43+
- `CATALYST_STORE_HASH` \- the hash of your Catalyst store
44+
- `CATALYST_PROJECT_UUID` \- the unique identifier for the BigCommerce infrastructure project
45+
- `CATALYST_FRAMEWORK` \- the framework to target (`nextjs` | `catalyst`) to run when building and deploying
46+
- `CATALYST_ACCESS_TOKEN` \- the Access Token that has **modify** permissions on **Infrastructure Projects and Infrastructure Deployments** as well as **read-only** permissions on **Infrastructure Logs**
47+
- `CATALYST_TELEMETRY_DISABLED` \- whether or not telemetry is disabled
48+
49+
When looking for configuration variables, the Catalyst CLI will search in the following places in order of priority:
50+
51+
- Individual parameter flags
52+
- This allows you to manually pass individual configuration parameters in the CLI command.
53+
- Ex. `catalyst deploy --store-hash <CATALYST_STORE_HASH> --access-token <CATALYST_ACCESS_TOKEN>`
54+
- Environment variable file flag
55+
- This allows you to pass the relative path to an environment variable file to load variables from.
56+
- Ex. `catalyst deploy --env-file .env.prod`
57+
- `process.env`
58+
- These are environment variables you have already set. They may be applied through your hosting platform, a UI, etc.
59+
- Ex. setting secret credentials in Github actions
60+
- `.bigcommerce/project.json`
61+
- This is the local configuration file that is generated after creating or linking a project that includes your store hash, project uuid, access token, etc.
62+
63+
### `project.json` Configuration File
64+
65+
The configuration for the BigCommerce infrastructure project that your repository is connected to is defined in the `.bigcommerce/project.json` file. The configuration file is generated when running the `link` command to create a new project or connect to an existing one.
66+
67+
```
68+
{
69+
"framework": "catalyst", // nextjs | catalyst
70+
"projectUuid": "<PROJECT-UUID>"
71+
"accessToken": "<ACCESS_TOKEN>"
72+
"storeHash": "<STORE_HASH>
73+
}
74+
```
75+
76+
The configuration file contains the following properties:
77+
78+
- `projectUuid` \- the unique identifier of the connected BigCommerce project
79+
- `storeHash` \- the hash of the BigCommerce store associated with the `accessToken`
80+
- `framework (catalyst | nextjs)` \- the framework to target when building
81+
- `accessToken` \- the Access Token that has **modify** permissions on **Infrastructure Projects and Infrastructure Deployments** as well as **read-only** permissions on **Infrastructure Logs**
82+
83+
As described above, the values in the `project.json` file have the lowest priority and will be used if none of the other options have been used.
84+
85+
You can remove the `.bigcommerce/` folder to reset your project’s configuration, but this action will require re-running the `pnpm catalyst create` or `pnpm catalyst link` command to re-connect to your project.
86+

docs/storefront/catalyst/getting-started/deploying/overview.mdx renamed to docs/storefront/catalyst/deployment/overview.mdx

File renamed without changes.

docs/storefront/catalyst/getting-started/deploying/vercel.mdx renamed to docs/storefront/catalyst/deployment/vercel.mdx

File renamed without changes.

‎docs/storefront/catalyst/features/features.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,7 @@ Below is a list of major BigCommerce platform features, detailing what support e
4646
| Session Syncing | 🟡 | Session can be synced from a headless storefront to a Stencil checkout. For example: you log in/out in headless then redirect to checkout. Session cannot be synced from a Stencil checkout to a headless storefront. For example: you log in/out in Stencil then redirect back. For more details, refer to the [Session Sync documentation](/docs/storefront/catalyst/development/session-sync). |
4747
| [Script Manager](https://support.bigcommerce.com/s/article/Using-Script-Manager) | 🟡 | Although we don't think frontend script injection is the right way for most solutions to integrate into Catalyst - we think most people would be better served by writing Server Components - we have added Scripts into GraphQL Storefront API so they can be rendered in Catalyst when it does make sense, such as for analytics pixels. It's important to note that scripts with handlebar expressions built for Stencil will not work in Catalyst.|
4848
| [Banners](https://support.bigcommerce.com/s/article/Creating-Editing-Banners) | 🔴 | Use [Makeswift](https://www.makeswift.com) (or an alternative) instead. |
49-
| Hosting by BigCommerce | 🔴 | Requires hosting on your own provider (ex. Vercel, AWS, Cloudflare, etc.). See the [Deploying a Catalyst storefront guide](/docs/storefront/catalyst/getting-started/deploying/overview) for more information. |
49+
| Hosting by BigCommerce | 🔴 | Requires hosting on your own provider (ex. Vercel, AWS, Cloudflare, etc.). See the [Deploying a Catalyst storefront guide](/docs/storefront/catalyst/deployment/overview) for more information. |
5050
| [Meta Pixel](https://support.bigcommerce.com/s/article/Meta-Pixel) | 🔴 | |
5151
| [Draft Orders](https://support.bigcommerce.com/s/article/Creating-a-Draft-Order) | 🔴 | Specifically, the ability for Catalyst to take a customer-facing Draft Order URL and apply it to the Catalyst session is not supported. |
5252
| [Order Messages](https://support.bigcommerce.com/s/article/Communicating-with-Customers#Messages) | 🔴 | Specfically, the ability for a customer to add additional messages on the order details page after checkout is not supported. |

‎docs/storefront/catalyst/getting-started/getting-started.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -117,4 +117,4 @@ After exploring your site in Makeswift, there are two primary next steps:
117117

118118
Running locally to do custom development is not required but it does enable full customization and control over your storefront. If you're interested in this, you can follow our [Local development](/docs/storefront/catalyst/getting-started/local-development) documentation to get started.
119119

120-
If you're not interested in doing any custom development and are happy with what's provided out of the box, you can go directly to our [Deploying](/docs/storefront/catalyst/getting-started/deploying/vercel) guide for next steps.
120+
If you're not interested in doing any custom development and are happy with what's provided out of the box, you can go directly to our [Deploying](/docs/storefront/catalyst/deployment/vercel) guide for next steps.

‎docs/storefront/catalyst/getting-started/local-development.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,4 +89,4 @@ Then, you can push your changes to the remote repository by running:
8989

9090
## Next Steps
9191

92-
You now have your own GitHub repository that you can continue to iterate on. When you're ready to publish your site, refer to our [Deploying docs](/docs/storefront/catalyst/getting-started/deploying/vercel) for next steps.
92+
You now have your own GitHub repository that you can continue to iterate on. When you're ready to publish your site, refer to our [Deploying docs](/docs/storefront/catalyst/deployment/vercel) for next steps.

‎docs/storefront/catalyst/getting-started/workflows/one-click-catalyst.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ This code-free starting point allows marketers and content authors to explore Ca
1414
<Callout type="warning">
1515
Note that the automatically deployed storefront is only intended to be used
1616
for previewing your storefront, so you’ll need to follow our
17-
[deploying](/docs/storefront/catalyst/getting-started/deploying/vercel) documentation to take your storefront to production.
17+
[deploying](/docs/storefront/catalyst/deployment/vercel) documentation to take your storefront to production.
1818
</Callout>
1919

2020
After completing the initial One-click Catalyst setup in the BigCommerce dashboard you will have:
@@ -31,5 +31,5 @@ Additionally, here are a few more documents that might be helpful.
3131
<Cards>
3232
<Cards.Card title="How to Developer Locally" href="/docs/storefront/catalyst/getting-started/local-development" />
3333
<Cards.Card title="Versioning in Catalyst" href="/docs/storefront/catalyst/getting-started/versioning" />
34-
<Cards.Card title="How to Deploy Catalyst" href="/docs/storefront/catalyst/getting-started/deploying/vercel" />
34+
<Cards.Card title="How to Deploy Catalyst" href="/docs/storefront/catalyst/deployment/vercel" />
3535
</Cards>

0 commit comments

Comments
 (0)