fix(cli): symlink .env.local to .dev.vars before preview by matthewvolk · Pull Request #2944 · bigcommerce/catalyst

matthewvolk · 2026-03-20T20:09:26Z

Summary

Copy .env.local to .bigcommerce/.dev.vars before running opennextjs-cloudflare preview in the start command
Wrangler reads secrets from .dev.vars, not .env.local, and silently ignores symlinks
Warns (instead of erroring) if .env.local is missing, to avoid breaking CI flows

Test plan

Existing tests updated (copyFileSync mock added)
All 38 tests pass (pnpm test)
Manual: catalyst build && catalyst start with .env.local present — verify preview has env vars
Manual: catalyst start without .env.local — verify warning is logged

vercel · 2026-03-20T20:09:31Z

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

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Mar 20, 2026 9:52pm

changeset-bot · 2026-03-20T20:09:31Z

⚠️ No Changeset found

Latest commit: 42a860f

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

chanceaclark · 2026-03-20T20:46:09Z

packages/catalyst/src/cli/commands/start.ts

+        consola.start('Copying .env.local to .bigcommerce/.dev.vars...');
+        copyFileSync(envLocal, devVars);
+        consola.success('.dev.vars created');


I thought wrangler/opennext can now read from .env.local?

Yeah that was my assumption but the only reason I opened this PR is because it wasn't working. If you're able to test it locally and it works for you, I've got no problem closing this.

Yeah I think CF is trying to move to .env.local instead of .dev.vars.

Nope, this is legit. I just tested locally. Here's what happened.

running from core/

With core/.env.local, no env vars detected:

$ node ../packages/catalyst/dist/cli.js start ◢ @bigcommerce/catalyst v1.0.0-alpha.0 4:14:46 PM ┌───────────────────────────────┐ │ OpenNext — Cloudflare preview │ └───────────────────────────────┘ Monorepo detected at /Users/matt.volk/code/work/catalyst-deploy Populating R2 incremental cache... Successfully populated cache with 25 assets Tag cache does not need populating ⛅️ wrangler 4.76.0 ─────────────────── Your Worker has access to the following bindings: Binding Resource Mode env.NEXT_CACHE_DO_QUEUE (DOQueueHandler) Durable Object local env.NEXT_TAG_CACHE_DO_SHARDED (DOShardedTagCache) Durable Object local env.NEXT_CACHE_DO_PURGE (BucketCachePurge) Durable Object local env.NEXT_INC_CACHE_R2_BUCKET (project-accd0361-2470-11f1-875e-1e6bd38089e2) R2 Bucket local env.WORKER_SELF_REFERENCE (project-accd0361-2470-11f1-875e-1e6bd38089e2) Worker local [connected] env.ASSETS Assets local

Since the file must be relative to the wrangler config file, first copy .env.local to core/.bigcommerce/.env.local

$ cp .env.local .bigcommerce/.env.local $ node ../packages/catalyst/dist/cli.js start ◢ @bigcommerce/catalyst v1.0.0-alpha.0 4:14:46 PM ┌───────────────────────────────┐ │ OpenNext — Cloudflare preview │ └───────────────────────────────┘ Monorepo detected at /Users/matt.volk/code/work/catalyst-deploy Populating R2 incremental cache... Successfully populated cache with 25 assets Tag cache does not need populating ⛅️ wrangler 4.76.0 ─────────────────── Your Worker has access to the following bindings: Binding Resource Mode env.NEXT_CACHE_DO_QUEUE (DOQueueHandler) Durable Object local env.NEXT_TAG_CACHE_DO_SHARDED (DOShardedTagCache) Durable Object local env.NEXT_CACHE_DO_PURGE (BucketCachePurge) Durable Object local env.NEXT_INC_CACHE_R2_BUCKET (project-accd0361-2470-11f1-875e-1e6bd38089e2) R2 Bucket local env.WORKER_SELF_REFERENCE (project-accd0361-2470-11f1-875e-1e6bd38089e2) Worker local [connected] env.ASSETS Assets local

Still doesn't work

Finally, rename to .dev.vars:

$ cp .env.local .bigcommerce/.dev.vars $ node ../packages/catalyst/dist/cli.js start ◢ @bigcommerce/catalyst v1.0.0-alpha.0 4:15:19 PM ┌───────────────────────────────┐ │ OpenNext — Cloudflare preview │ └───────────────────────────────┘ Monorepo detected at /Users/matt.volk/code/work/catalyst-deploy Populating R2 incremental cache... Successfully populated cache with 25 assets Tag cache does not need populating ⛅️ wrangler 4.76.0 ─────────────────── Using secrets defined in .bigcommerce/.dev.vars Your Worker has access to the following bindings: Binding Resource Mode env.NEXT_CACHE_DO_QUEUE (DOQueueHandler) Durable Object local env.NEXT_TAG_CACHE_DO_SHARDED (DOShardedTagCache) Durable Object local env.NEXT_CACHE_DO_PURGE (BucketCachePurge) Durable Object local env.NEXT_INC_CACHE_R2_BUCKET (project-accd0361-2470-11f1-875e-1e6bd38089e2) R2 Bucket local env.WORKER_SELF_REFERENCE (project-accd0361-2470-11f1-875e-1e6bd38089e2) Worker local [connected] env.ASSETS Assets local env.BIGCOMMERCE_STORE_HASH ("(hidden)") Environment Variable local env.BIGCOMMERCE_CHANNEL_ID ("(hidden)") Environment Variable local env.BIGCOMMERCE_STOREFRONT_TOKEN ("(hidden)") Environment Variable local env.MAKESWIFT_SITE_API_KEY ("(hidden)") Environment Variable local env.AUTH_SECRET ("(hidden)") Environment Variable local env.CLIENT_LOGGER ("(hidden)") Environment Variable local env.KV_LOGGER ("(hidden)") Environment Variable local env.DEFAULT_REVALIDATE_TARGET ("(hidden)") Environment Variable local env.AUTH_TRUST_HOST ("(hidden)") Environment Variable local env.TRAILING_SLASH ("(hidden)") Environment Variable local env.ENABLE_ADMIN_ROUTE ("(hidden)") Environment Variable local env.B2B_API_TOKEN ("(hidden)") Environment Variable local env.B2B_API_HOST ("(hidden)") Environment Variable local env.CONTENTFUL_SPACE_ID ("(hidden)") Environment Variable local env.CONTENTFUL_ACCESS_TOKEN ("(hidden)") Environment Variable local env.DATABASE_URL ("(hidden)") Environment Variable local env.DATABASE_AUTH_TOKEN ("(hidden)") Environment Variable local env.AUTH_RESEND_KEY ("(hidden)") Environment Variable local

Talked offline, agreed to symlink core/.env.local to core/.bigcommerce/.dev.vars if core/.bigcommerce/.dev.vars does not already exist.

Seperately, asked Cloudflare if there are there plans to support .env.local across all entry points (preview, dev, deploy, etc.). Currently .env.local only works during next dev via initOpenNextCloudflareForDev(), but opennextjs-cloudflare preview goes through wrangler which only reads .dev.vars. The inconsistency is a bit of a footgun — easy to assume .env.local works everywhere when it only works in dev.

github-actions · 2026-03-20T21:40:47Z

Bundle Size Report

Comparing against baseline from c965f4d (2026-03-20).

No bundle size changes detected.

Wrangler reads secrets from .dev.vars, not .env.local. Create a symlink from .bigcommerce/.dev.vars to .env.local before running opennextjs-cloudflare preview so the local server has access to environment variables.

matthewvolk requested a review from a team as a code owner March 20, 2026 20:09

vercel bot had a problem deploying to Preview March 20, 2026 20:10 Failure

chanceaclark reviewed Mar 20, 2026

View reviewed changes

matthewvolk requested a review from chanceaclark March 20, 2026 21:02

matthewvolk force-pushed the CATALYST-1826-start-cmd-dev-vars branch from 9449576 to e69a84e Compare March 20, 2026 21:39

vercel bot deployed to Preview March 20, 2026 21:40 View deployment

matthewvolk force-pushed the CATALYST-1826-start-cmd-dev-vars branch from e69a84e to 375f476 Compare March 20, 2026 21:42

matthewvolk changed the title ~~fix(cli): copy .env.local to .dev.vars before preview~~ fix(cli): symlink .env.local to .dev.vars before preview Mar 20, 2026

vercel bot deployed to Preview March 20, 2026 21:42 View deployment

fix(cli): symlink .env.local to .dev.vars before preview

42a860f

Wrangler reads secrets from .dev.vars, not .env.local. Create a symlink from .bigcommerce/.dev.vars to .env.local before running opennextjs-cloudflare preview so the local server has access to environment variables.

matthewvolk force-pushed the CATALYST-1826-start-cmd-dev-vars branch from 375f476 to 42a860f Compare March 20, 2026 21:51

vercel bot deployed to Preview March 20, 2026 21:52 View deployment

chanceaclark approved these changes Mar 20, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(cli): symlink .env.local to .dev.vars before preview#2944

fix(cli): symlink .env.local to .dev.vars before preview#2944
matthewvolk wants to merge 1 commit intoalphafrom
CATALYST-1826-start-cmd-dev-vars

matthewvolk commented Mar 20, 2026

Uh oh!

vercel bot commented Mar 20, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Mar 20, 2026 •

edited

Loading

Uh oh!

chanceaclark Mar 20, 2026

Uh oh!

matthewvolk Mar 20, 2026

Uh oh!

chanceaclark Mar 20, 2026

Uh oh!

matthewvolk Mar 20, 2026

Uh oh!

matthewvolk Mar 20, 2026

Uh oh!

github-actions bot commented Mar 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

matthewvolk commented Mar 20, 2026

Summary

Test plan

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

⚠️ No Changeset found

Uh oh!

chanceaclark Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

matthewvolk Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

chanceaclark Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

matthewvolk Mar 20, 2026

Choose a reason for hiding this comment

With core/.env.local, no env vars detected:

Since the file must be relative to the wrangler config file, first copy .env.local to core/.bigcommerce/.env.local

Finally, rename to .dev.vars:

Uh oh!

matthewvolk Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Mar 20, 2026

Bundle Size Report

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

vercel bot commented Mar 20, 2026 •

edited

Loading

changeset-bot bot commented Mar 20, 2026 •

edited

Loading

With `core/.env.local`, no env vars detected:

Since the file must be relative to the wrangler config file, first copy `.env.local` to `core/.bigcommerce/.env.local`