The @bigcommerce/stencil-cli package shipped version 9.0.1 on April 1, 2026 and supports Node.js 20.x and 22.x. The bigcommerce/catalyst repository runs from the canary branch with Next.js 16.1, React 19.1, and Node.js 24.0 or higher. Those two sentences contain the core operational fact that most Stencil-versus-headless articles skip. Teams that run both are running two different Node runtimes, two different build toolchains, two different deployment targets, and two different on-call surfaces. That choice has downstream cost and staffing implications before a single feature difference is discussed.
This page exists because too many architecture decisions between Stencil and Catalyst get made on vibes. The broader BigCommerce development guide references the question. This page answers it with specifics. Catalyst is the right call for some stores. Stencil is the right call for more of them than the vendor marketing suggests.
What Stencil actually is
Stencil is BigCommerce's theme framework, not a frontend framework in the modern React sense. A Stencil theme compiles Handlebars templates, SCSS stylesheets, and a YAML config file into a bundle that the BigCommerce control panel serves directly from the platform. Developers work locally using the Stencil CLI against a local copy of a theme like Cornerstone, the open-source reference theme BigCommerce maintains at github.com/bigcommerce/cornerstone. The CLI commands any team running Stencil has to know are stencil init to pair a local project with a store, stencil start to boot a local preview against live store data, stencil bundle to produce the deployable zip, stencil push to upload it, and stencil release to publish a new version to the storefront.
The tradeoff of Stencil is that the platform handles a lot of the hosting, security, and scaling surface area. BigCommerce reports 100 percent uptime across every Cyber Week since 2016 on its managed infrastructure, and Stencil themes ride on that. The cost of the managed infrastructure is flexibility. A Stencil theme cannot run arbitrary server-side code at render time. Custom business logic that needs to execute on every page load lives in the Script Manager, in Widgets API injections, or in external services called via client-side JavaScript. None of those match the developer experience of writing a Next.js API route.
Stencil themes integrate with the Widgets API for Page Builder drag-and-drop regions and with the Checkout SDK if the team needs to customize the native Optimized One-Page Checkout experience. Most DTC stores under $50 million in annual revenue do not have requirements that exceed what a well-built Stencil theme can deliver.
What Catalyst is and where headless fits
Catalyst is BigCommerce's reference implementation for headless storefronts. The project README currently states that as of January 6, 2025 the main branch is frozen and the default branch is canary, which is where active development happens. Scaffolding a new Catalyst project uses npm create @bigcommerce/catalyst@latest. The current canary core package depends on Next.js 16.1, React 19.1, and requires Node.js 24 or higher per its engines field. Data fetching runs through the GraphQL Storefront API with gql.tada for type-safe GraphQL, which is a meaningful quality-of-life upgrade over untyped REST calls.
Headless on BigCommerce does not mean replacing the checkout. The storefront web APIs that would make that possible do not currently support CORS, so most headless sites keep the native Optimized One-Page Checkout and embed it into the Catalyst storefront using the Checkout SDK's embedded-checkout module. A fully custom checkout flow requires operating against the Storefront Checkout API from a server that acts as a proxy, which adds complexity the storefront team has to own indefinitely.
Visual editing for headless storefronts commonly layers in through Makeswift, which integrates with Catalyst to give marketers a drag-and-drop surface on top of the Next.js app. The tradeoff is another service in the stack with its own billing, rate limits, and release cadence.
Headless is an answer to a frontend problem. If the frontend problem does not exist, headless is an expensive answer to a question nobody asked.
The Node and Next.js version split
The fact that Stencil CLI 9 supports Node 20 and 22 while Catalyst requires Node 24 is a real operational problem for teams running both on the same laptop. Most engineers solve it with nvm or Volta. CI pipelines need two runner images. Docker base images diverge. Security patching cadences split because Node release cycles do not line up cleanly across those versions. None of this is a reason to avoid either stack. All of it is a reason to plan the developer environment before the first line of code ships.
The Next.js version is the less obvious issue. Next.js 16 introduced changes around caching, turbopack defaults, and React Server Components that are still being absorbed into production apps across the ecosystem. Catalyst on the canary branch follows upstream Next.js closely, which means breaking changes land in the storefront template faster than many teams are comfortable with. A Catalyst storefront that was built on the January 2026 state of the canary branch is not identical to one built on the April 2026 state. Teams that do not track upstream closely discover the drift during an unrelated upgrade and lose a sprint absorbing it.
Performance and operational tradeoffs
Performance is the pitch for headless and it is not as clean a pitch as it used to be. Stencil on BigCommerce's managed infrastructure typically hits Lighthouse mobile scores in the 70 to 85 range on Cornerstone-based themes without custom work, and the recent Optimized One-Page Checkout transition ships with a roughly one-second faster first-interaction handoff compared to the older flow, with no configuration required. Catalyst can hit 90 plus on Lighthouse, but only if the Vercel or other hosting tier is sized correctly, the GraphQL queries are trimmed, and the Next.js cache configuration is tuned. A badly configured Catalyst deployment can perform worse than a well-tuned Stencil theme.
Operational cost is the gap agencies rarely price honestly. A Stencil storefront needs theme maintenance and occasional widget updates. A Catalyst storefront needs hosting (Vercel Pro at minimum for production at $20 per seat per month plus bandwidth), monitoring (Sentry or Datadog), deployment pipelines, and a rotation of engineers who can absorb the upstream Next.js and Catalyst canary changes as they land. Budget a minimum of $3,000 to $8,000 per month in operational cost on top of the build. Cross-check with the full cost breakdown.
Cost comparison with real numbers
BigCommerce's own headless FAQ quotes a mid-market headless implementation at $50,000 to $150,000 and enterprise headless at over $250,000. Those numbers are consistent with what specialist agencies quote and inconsistent with generalist quotes that land below $50,000 for enterprise work. A Stencil build for the same business requirements typically runs 40 to 70 percent less, largely because the managed platform absorbs frontend infrastructure decisions the Catalyst team has to make explicit.
| Dimension | Stencil | Catalyst (headless) |
|---|---|---|
| Initial build | $15,000 to $60,000 | $45,000 to $150,000 |
| Monthly operational cost beyond BigCommerce plan | $0 to $500 | $3,000 to $8,000 |
| Node runtime | 20.x or 22.x | 24.0 or higher |
| Frontend stack | Handlebars plus SCSS | Next.js 16, React 19, GraphQL |
| Content editing for marketers | Page Builder native | Makeswift or custom CMS layer |
| Upstream change cadence | Stencil CLI minor releases quarterly | Catalyst canary plus Next.js 16 weekly surface |
| Checkout options | Native OOPC with theme customization | Embedded OOPC via SDK or proxied custom flow |
When not to go headless
Five scenarios argue against a Catalyst rebuild even when the engineering team is excited about it. The first is a store under roughly $20 million in revenue where frontend performance is inside acceptable bounds. The Catalyst rebuild does not pay back. The second is a marketing-heavy site where Page Builder is already in daily use. Rebuilding that content model on a headless CMS costs months and sometimes breaks marketing velocity through the transition. The third is a B2B store running the B2B Edition buyer portal heavily, because the buyer portal integration on Catalyst is less mature than on Stencil and often requires custom work to replicate.
The fourth is a team without a DevOps function. Catalyst in production needs someone who owns the deployment pipeline, rollback strategy, and incident response. Outsourcing that responsibility to the build agency works during the build and breaks six months after launch. The fifth is any project where the business sponsor cannot articulate a specific frontend requirement that Stencil cannot meet. "Modern stack" is not a requirement. "We need Spanish and French storefronts with different product catalogs sharing one checkout" is a requirement, and even that can be solved with multi-storefront on Stencil in many cases.
Decision framework
Three questions usually settle the architecture decision honestly. The first is what specific customer-facing outcome requires headless that Stencil cannot deliver. Name the feature and show the Stencil constraint. If the answer is vague, pick Stencil. The second is whether the team can absorb a Next.js upgrade every quarter for the next three years without stalling the roadmap. If the answer is no, pick Stencil or plan to outsource the upgrades to an agency on retainer. The third is whether the build budget plus three years of operational cost on the headless path is justified by measurable revenue impact. A 1 percent conversion lift on a $30 million store is $300,000 per year. A 1 percent lift on a $3 million store is $30,000 per year, which does not cover the Catalyst operational overhead.
Selection criteria feed back into the agency evaluation covered in the agency selection guide. The architecture choice also shapes ongoing cost, which the customization cost breakdown models across multiple project types.