TRAC-137: Add native hosting option to create-catalyst

[jordanarldt]

Jira: TRAC-137

What/Why?

Adds a --hosting flag and prompt to create-catalyst so merchants can scaffold a project pre-wired for Commerce Hosting in one step instead of running catalyst project create / link themselves.

The hosting prompt is gated on GET /v3/infrastructure/projects (200 → prompt, 403 → silent self-hosted default, other failures → warn and fall back). When Commerce Hosting is selected, the user can pick an existing Commerce Hosting project or create a new one; the resulting UUID is wired into the scaffold automatically. New-project names are checked against existing projects on the store (case-insensitive, matching API behavior) before submission so name collisions surface as a friendly validator error instead of a server roundtrip.

--hosting accepts:

• self-hosted — Next.js (default if omitted)
• commerce — Commerce Hosting (Native)

--project-name <name>, when passed alongside --hosting commerce, skips the Commerce Hosting project selection prompts and auto-creates a project with that name. If a project with that name already exists on the store, the user is asked Yes/No whether to reuse it (in non-interactive environments / with --use-existing, the answer is automatic).

--use-existing — only used with --hosting commerce and --project-name. When the named project already exists on the store, reuse it instead of prompting. Has no effect without --hosting commerce (a warning is logged if it's set in another mode).

Native-mode post-clone mutations (setupCommerceHosting):

• core/package.json: next build → catalyst build, add deploy, drop start, add @bigcommerce/catalyst@1.0.0-alpha.3 + @opennextjs/cloudflare@1.17.3 (per the Native Hosting docs)
• core/.bigcommerce/project.json: written with projectUuid, framework, plus storeHash / accessToken when available
• core/.env.local: symlinked to ../.env.local (warns and continues if symlinks aren't permitted; tagged with TODO(LTRAC-409): remove this symlink)
• core/proxy.ts → core/middleware.ts with the edge runtime injection (Next.js 16 migration note)

Versions are pinned exactly — these need a deliberate bump alongside @bigcommerce/catalyst releases.

User-facing terminology

To keep the two "project" concepts distinct, the CLI distinguishes:

• Project directory — the local folder being scaffolded. Controlled by --project-name / --project-dir; the interactive prompt is "What is the name of your project directory?".
• Commerce Hosting project — the remote record on Commerce that hosts the storefront. Created or selected during the hosting flow.

Files and functions touching the user-facing flow were renamed to match:

• setup-native-hosting.ts → setup-commerce-hosting.ts (setupNativeHosting → setupCommerceHosting)
• prompt-infrastructure-project.ts → prompt-commerce-hosting-project.ts (promptForInfrastructureProject → promptForCommerceHostingProject)
• API-client identifiers (listInfrastructureProjects, createInfrastructureProject, InfrastructureProjectValidationError) keep the "infrastructure" name since they map directly to /v3/infrastructure/projects.

Error handling

API methods now wrap fetch / parse / non-OK-status failures in a single friendly Error (Could not load Commerce Hosting projects: ..., Could not create Commerce Hosting project: ...) with the original error preserved as cause. InfrastructureProjectValidationError is intentionally re-thrown unwrapped so consumer instanceof checks still work.

Rollout/Rollback

Behind the existing Infrastructure Projects API feature flag — merchants without access keep the current self-hosted scaffold unchanged. Rollback is a code revert; no migrations or runtime changes.

Testing

71 unit tests across the API client, hosting-mode resolution, the prompt + retry / auto-create / collision flow, the --use-existing flag (TTY and non-TTY paths), and the file mutations.

Manual end-to-end:

cd packages/create-catalyst && pnpm build
node bin/index.cjs --project-name test --hosting commerce
# verify core/package.json scripts, core/.bigcommerce/project.json, core/.env.local symlink

Scaffolding works end-to-end against a store with infrastructure access. pnpm build / pnpm deploy on the resulting project are blocked on a separate downstream issue, out of scope for this PR.

Proof of life

Screen.Recording.2026-04-29.at.4.55.12.PM.mov

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
catalyst	Ready	Preview, Comment	Apr 29, 2026 10:09pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: f69ce47

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

[github-actions]

Bundle Size Report

Comparing against baseline from 9f11983 (2026-04-29).

No bundle size changes detected.

[github-actions]

Unlighthouse Performance Comparison — Vercel

Comparing PR preview deployment Unlighthouse scores vs production Unlighthouse scores.

Summary Score

Aggregate score across all categories as reported by Unlighthouse.

	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Score	90	92	91	95

Category Scores

Category	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
Performance	74	89	78	90
Accessibility	95	95	95	98
Best Practices	100	100	95	100
SEO	88	88	100	100

Core Web Vitals

Metric	Prod Desktop	Prod Mobile	Preview Desktop	Preview Mobile
LCP	3.5 s	3.7 s	3.2 s	3.6 s
CLS	0.05	0	0.001	0
FCP	1.2 s	1.2 s	1.2 s	1.2 s
TBT	10 ms	0 ms	10 ms	20 ms
Max Potential FID	60 ms	40 ms	70 ms	80 ms
Time to Interactive	3.6 s	3.7 s	4.1 s	4.0 s

Full Unlighthouse report →

[chanceaclark]

Overall LGTM. I'd let a second opinion from @bigcommerce/team-trac have some input before merging though.

[parthshahp]

⛏️ I'd like to think a bit more about these hosting flags, same with the help message.

Is the logic here: "self-hosted" == Vercel right now, but in theory can be any hosting provider (including self-hosted), and "commerce" == Native Hosting on CF?

I guess my question here is: why not put "vercel" and "commerce" as the options?

[jordanarldt]

@parthshahp I think self-hosted makes the most sense, because it doesn't necessarily mean Vercel. When not using Native Hosting, the consumer can host their NextJS app anywhere that supports hosting NextJS (heroku, vercel, google cloud, etc)

[parthshahp]

That makes sense. I think the message "self-hosted" for Next.js is a bit confusing here, because technically it's Next.js either way, right? If I saw this message, I would think:

If "self-hosted" is how I use Next.js, what framework is "commerce"?

[jordanarldt]

@parthshahp Yeah good point, let me fix that!

[chanceaclark]

I think that self-hosted here means that it's hosted elsewhere. We have merchants hosting on Vercel, but also in AWS or other hosting providers right now. The point of self-hosted here is more on the path that we ship default Next.js commands, not our Native Hosting specific setup. self-hosted also opens up the door that we can support aws as an option and tweak what the command ships to be aligned with AWS.

I'm not married to the name, but we should probably avoid "framework" here. I think of "framework" as Next.js, Vue, or React, but not a "hosting framework". If we wanted to remove self-hosted we could say the flag follows this logic:

• Only provide commerce (or whatever we want to name it) as the only option.
• If --hosting commerce is provided, ship with Native Hosting augments
• If no flag is provided or option selected, ship with default Next.js
• If invalid flag name, error.

I really want Catalyst to lean into this "composability" aspect, and this flag is probably one of those design choices. I want developers to have the option of taking a base output and being able to change what they need to fit their needs. If they want to ship it to AWS, they can; Vercel, easy; etc....

[linear-code]

LTRAC-137 Add hosting selection to create-catalyst CLI

[migueloller]

I feel like we're mixing concerns here. I'm not sure that we should have this option on the create-catalyst CLI, it feels like this logic should live in the catalyst CLI as part of the deploy command. In particular, after running create-catalyst, if I run catalyst deploy we should be smart and take the user through all these steps.

We're adding a ton of logic to create-catalyst to set up hosting configuration. create-catalyst should be just about scaffolding a Catalyst codebase, and should delegate to catalyst init probably. It feels like a lot of what we're doing here is the concern of the Catalyst CLI and we'd want that to happen at deploy time.

An example of where decoupling create-catalyst from catalyst deploy helps: a user already has an existing Catalyst site and they want to use Commerce Hosting for Catalyst. They're not going to run create-catalyst, they already have an app. Instead, what they're going to do is reach for catalyst deploy. But since we've put all this logic here, then now they don't get this nice experience.