Catalyst 1744 refactor configuration variables by jamesqquick · Pull Request #2866 · bigcommerce/catalyst

jamesqquick · 2026-02-06T21:27:53Z

What/Why?

Refactor config variables:

Rename environment variables from `BIGCOMMERCE_` prefix to `CATALYST_` prefix

BIGCOMMERCE_STORE_HASH -> CATALYST_STORE_HASH

BIGCOMMERCE_PROJECT_UUID -> CATALYST_PROJECT_UUID

BIGCOMMERCE_FRAMEWORK -> CATALYST_FRAMEWORK

BIGCOMMERCE_ACCESS_TOKEN - > CATALYST_ACCESS_TOKEN

Implement new priority for config variables

Individual parameter flags (e.g. --store-hash)
--env-file flag
process.env
.bigcommerce/project.json

Add --env-file flag

This allows the user to specify a environment variable file to load variables from

Remove default environment variable file

Remove the reading of default environment variable files. This requires the user to pass --file-env if they want variables to be read from a file.

Expand project.json

Write additional config variables to project.json file.

projectUuid
framework
storeHash
accessToken

Improved logging

Update logs to details which variables are required and how/where to set them

Testing

Tests have been added to test basic functionality. One thing the tests do not cover is when the user is passing the --env-file flag to specify an environment variable file to read from. For testing,

rename environment variables to match CATALYST_ prefix
run CLI command (ex. project list) without passing any flags. It should fail since no env file is being picked up automatically
run catalyst project create command to generate a new project and verify the correct properties are set in project.json
catalyst project list - should now work by reading variables from project.json
run catalyst project list --access-token dummy-token and pass dummy variable for access token via --access-token flag. This should fail since the explicitly passed access token isn't valid
create .env.test with invalid access token. Then, run catalyst project list --env-file .env.test and show that the command fails since it picked up the invalid access token
test other combinations of variable configurations to confirm priority order is respected

Migration

vercel · 2026-02-06T21:27:59Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Feb 11, 2026 11:23am

changeset-bot · 2026-02-06T21:27:59Z

⚠️ No Changeset found

Latest commit: 6091753

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

…list)

Co-authored-by: Chancellor Clark <chancellor.clark@bigcommerce.com>

…and define priority for config variables

… and read all variables from config file

matthewvolk

⚠️ I just realized now that we're storing access token in .bigcommerce/, the root .gitignore contains a line to ignore .bigcommerce but the core/.gitignore does not. Since eventually, core/.gitignore will be the ignore file shipped to customers, and they won't have the root ignore file, can we please add .bigcommerce to core/.gitignore?

matthewvolk · 2026-02-10T22:20:54Z

packages/catalyst/src/cli/index.ts

+const envFileIndex = process.argv.findIndex(
+  (arg) => arg === '--env-file' || arg.startsWith('--env-file='),
+);


This works but I think it's fragile... I'm not sure it'll handle edge cases like --env-file being passed after -- (which Commander uses to stop option parsing).

If we're ok with that, that's fine. We can always merge and re-evaluate if it starts behaving undesirably.

matthewvolk · 2026-02-10T22:27:06Z

packages/catalyst/src/cli/commands/link.spec.ts

+  consolaPromptMock.mockRestore();
+});
+
+test('prompts to create a new project', async () => {


I think this test name is a duplicate of the test on line 164 in this same file. I see the following:

line 164: test('prompts to create a new project', ...) - the happy path where the user selects "create" and it succeeds

line ~221: test('prompts to create a new project', ...) - the error path where the API returns a 502

Maybe we rename the second one to "errors when project creation fails" or something?

matthewvolk · 2026-02-10T22:27:53Z

packages/catalyst/src/cli/commands/deploy.spec.ts

-    'BIGCOMMERCE_STORE_HASH=123',
-    'BIGCOMMERCE_STOREFRONT_TOKEN=456',
+    'CATALYST_STORE_HASH=123',
+    'CATALYST_ACCESS_TOKEN=456',


Was this intentional, to rename BIGCOMMERCE_STOREFRONT_TOKEN to CATALYST_ACCESS_TOKEN?

matthewvolk · 2026-02-10T22:28:00Z

packages/catalyst/src/cli/commands/deploy.spec.ts

    {
      type: 'secret',
-      key: 'BIGCOMMERCE_STOREFRONT_TOKEN',
+      key: 'CATALYST_ACCESS_TOKEN',


Was this intentional, to rename BIGCOMMERCE_STOREFRONT_TOKEN to CATALYST_ACCESS_TOKEN?

I actually just realized I made that jump. I think I just had access_token in my mind and put that in the different docs, then copied in. I don't think we made a collective decision on that. I think the correct thing to do would be CATALYST_STOREFRONT_TOKEN. Does you agree with that?

Wait ignore the above lol I get it now. This is supposed to be testing parsing secret runtime variables. Great catch!

chanceaclark

Can we split this up into separate changes for each thing you are doing here?

jamesqquick · 2026-02-11T11:23:02Z

Can we split this up into separate changes for each thing you are doing here?

Into separate PRs you mean? I wondered about it being too much in one. I can do that!

jamesqquick · 2026-02-11T11:54:43Z

Splitting this into separate PRs

vercel bot deployed to Preview February 6, 2026 21:29 View deployment

jamesqquick force-pushed the CATALYST-1744-refactor-configuration-variables branch from fc5af19 to cd4009b Compare February 9, 2026 18:26

vercel bot deployed to Preview February 9, 2026 18:28 View deployment

vercel bot deployed to Preview February 10, 2026 20:17 View deployment

jamesqquick and others added 15 commits February 10, 2026 15:24

create project command with three nested commands (create, link, and …

9fb5729

…list)

fix linting

d2751b8

Update packages/catalyst/src/cli/commands/build.ts

bd5c88e

Co-authored-by: Chancellor Clark <chancellor.clark@bigcommerce.com>

merge link tests into project

b2d95bb

organize tests for project using describe

1f8c78b

remove loading of default env files

075d2ae

rename env variable prefix, write config properties to project.json, …

ff50393

…and define priority for config variables

updated error message logging

7475d6f

update env variable names and log messages

e0734da

fixed testing for console messages

b2e6a61

update logging, rename access token, write properties to config file,…

f90f9f5

… and read all variables from config file

add configuration priority tests

98d634b

rebase on canary

f9027c6

fix linting

5442ed1

fix linting

6091753

jamesqquick force-pushed the CATALYST-1744-refactor-configuration-variables branch from 84dcd1a to 6091753 Compare February 10, 2026 20:25

vercel bot deployed to Preview February 10, 2026 20:27 View deployment

jamesqquick marked this pull request as ready for review February 10, 2026 20:34

jamesqquick requested a review from a team as a code owner February 10, 2026 20:34

matthewvolk requested changes Feb 10, 2026

View reviewed changes

chanceaclark requested changes Feb 11, 2026

View reviewed changes

add .bigcommerce to core gitignore

4671ec0

vercel bot deployed to Preview February 11, 2026 11:23 View deployment

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Catalyst 1744 refactor configuration variables#2866

Catalyst 1744 refactor configuration variables#2866
jamesqquick wants to merge 16 commits intocanaryfrom
CATALYST-1744-refactor-configuration-variables

jamesqquick commented Feb 6, 2026 •

edited

Loading

Uh oh!

vercel bot commented Feb 6, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Feb 6, 2026 •

edited

Loading

Uh oh!

matthewvolk left a comment

Uh oh!

matthewvolk Feb 10, 2026

Uh oh!

matthewvolk Feb 10, 2026

Uh oh!

matthewvolk Feb 10, 2026

Uh oh!

matthewvolk Feb 10, 2026

Uh oh!

jamesqquick Feb 11, 2026

Uh oh!

jamesqquick Feb 11, 2026

Uh oh!

chanceaclark left a comment

Uh oh!

jamesqquick commented Feb 11, 2026

Uh oh!

jamesqquick commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

jamesqquick commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why?

Rename environment variables from BIGCOMMERCE_ prefix to CATALYST_ prefix

Implement new priority for config variables

Add --env-file flag

Remove default environment variable file

Expand project.json

Improved logging

Testing

Migration

Uh oh!

vercel bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Feb 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

matthewvolk left a comment

Choose a reason for hiding this comment

Uh oh!

matthewvolk Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

matthewvolk Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

matthewvolk Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

matthewvolk Feb 10, 2026

Choose a reason for hiding this comment

Uh oh!

jamesqquick Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

jamesqquick Feb 11, 2026

Choose a reason for hiding this comment

Uh oh!

chanceaclark left a comment

Choose a reason for hiding this comment

Uh oh!

jamesqquick commented Feb 11, 2026

Uh oh!

jamesqquick commented Feb 11, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jamesqquick commented Feb 6, 2026 •

edited

Loading

Rename environment variables from `BIGCOMMERCE_` prefix to `CATALYST_` prefix

vercel bot commented Feb 6, 2026 •

edited

Loading

changeset-bot bot commented Feb 6, 2026 •

edited

Loading