# Bagisto Next.js Commerce: a headless storefront that needs a Bagisto backend first

> Bagisto's Next.js storefront pairs a TypeScript App Router frontend with Bagisto's GraphQL API. It is a good fit if you already run Bagisto, and the wrong tool if you do not.

**bagisto/nextjs-commerce** — Open source headless commerce that’s fast, flexible, and built to scale,launch stunning storefronts that convert and grow your business without limits.

- Repository: https://github.com/bagisto/nextjs-commerce
- Website: https://bagisto-headless.vercel.app/
- Stars: 6,408 · Forks: 115
- Language: TypeScript
- License: MIT
- Published: 2026-09-22 · Updated: 2026-09-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/bagisto-nextjs-commerce

## What Bagisto Next.js Commerce actually is

This repository is not a shop. It is the customer-facing half of one. The README describes it as a headless eCommerce framework built with Next.js and powered by Bagisto, and the installation steps make the dependency explicit: step one is installing Bagisto, step two is installing the Bagisto Headless Extension, and only then do you scaffold the frontend. Everything a shopper sees (product pages, categories, cart, account) is rendered by this Next.js app, while prices, stock, orders and customers stay in the Bagisto backend and reach the frontend through GraphQL.

That split is the whole point. If you want to replace Bagisto's server-rendered Blade theme with something you can restyle freely, or put a CDN in front of your catalogue, this is the intended path. If you have no Bagisto install and no intention of running one, the project has nothing to show you. The README's own prerequisites list Node.js 20+ and npm, plus a link to Bagisto's backend requirements, which is a fair summary of the work involved: the frontend is the easy half.

## How the storefront talks to Bagisto: GraphQL, caching and ISR

The mechanism is a GraphQL client talking to the Bagisto API. The dependency list includes @apollo/client and graphql, so the storefront queries the backend through Apollo rather than through REST endpoints or a bespoke fetch layer. Authentication runs through NextAuth.js, which is why the environment file carries NEXTAUTH_URL and NEXTAUTH_SECRET alongside the Bagisto endpoint.

On top of that sits the rendering strategy the README emphasises most: layered caching for API responses and page rendering, plus Incremental Static Regeneration with revalidation. In practice this means product and category pages are generated as static output and refreshed on a revalidation schedule rather than fetched per request. That is what produces the performance profile the project advertises; the README claims a 100/100 Core Web Vitals score and shows a screenshot of it. Treat that number as the project's own claim about its reference deployment, not a guarantee about yours. Cache behaviour depends on your revalidation settings and on how quickly Bagisto invalidates the underlying data, and the README does not document a cache-invalidation contract between the two systems. If your catalogue changes minute to minute, that gap is the first thing you will feel.

## Installing it and getting a product page on screen

The scaffold is a single command. The README shows it as follows, and it creates a storefront directory named after the argument you pass.

```bash
npx -y @bagisto-headless/create your-storefront
```

Before that command is useful you need two things from the backend: a running Bagisto instance and the Bagisto Headless Extension, which the README points to at github.com/bagisto/bagisto-api. The storefront is documented against Bagisto v2.4.x and Bagisto API v1.0.3.

Next, create .env.local. The README's table lists five variables, and the repository ships a matching .env.example. The two that matter most are the endpoint and the storefront key; the README's example key begins with pk_storefront_.

```bash
# .env.local
NEXT_PUBLIC_BAGISTO_ENDPOINT=https://your-bagisto-instance.com
NEXT_PUBLIC_BAGISTO_STOREFRONT_KEY=your_storefront_key_here
NEXTAUTH_URL=http://localhost:3000
NEXTAUTH_SECRET=your_next_auth_secret_here
COMPANY_NAME=Your Company Name
```

The README suggests generating the NextAuth secret with openssl rand -base64 32, and warns against committing the file. Then install and start:

```bash
npm install
npm run dev
```

The README says the store should be reachable at http://localhost:3000. What you should see is your own catalogue, not a demo one: the product list comes from the endpoint you configured, so if the page is empty the problem is almost always the storefront key or the extension, not the frontend. For a production build the README gives npm run build followed by npm run start. There is also a Vercel path (npm i -g vercel, vercel link, vercel env pull) and a Netlify deploy button, and the README notes that Vercel environment variables are the recommended route while a local .env file is sufficient for development.

## The backend is not optional, and that is the main constraint

The most common way to waste an afternoon with this repository is to clone it and expect a working shop. It will not be one. The README's installation section assumes an existing Bagisto deployment, and the storefront key it asks for is issued by that deployment. There is no bundled mock API, no seed catalogue and no fallback data path documented in the README. A frontend with a placeholder key will build and start and then render nothing useful, which is a confusing failure mode because nothing in the Next.js console says the backend is the problem.

There is a second constraint worth naming. Bagisto's own repository is a PHP/Laravel application, and the README links to its server configuration requirements rather than restating them. So the real adoption cost is two stacks: a PHP host for Bagisto, and a Node host for the storefront, plus the network path between them. Teams that picked this project precisely to avoid PHP will still be running PHP.

Finally, the README is thin on operational detail. It documents installation, environment variables, scripts and the product and category surfaces, and it does not document rollback, cache invalidation between the two systems, or how storefront keys are rotated. Those are questions for Bagisto's own documentation and forums, which the README links to.

## Bagisto Next.js Commerce compared with Vercel's Next.js Commerce

The obvious alternative is Vercel's own Next.js Commerce, which shares the same React and Next.js foundation but takes a different approach to the backend. Vercel's template is built around pluggable commerce providers, so the storefront can be pointed at Shopify or another hosted platform without you running that platform yourself. Bagisto Next.js Commerce makes the opposite bet: it is wired to one backend, Bagisto, through Bagisto's GraphQL API.

That difference decides most adoption questions. If you want a hosted commerce backend and no server to operate, the provider-based template is the shorter route. If you already run Bagisto, or you want the catalogue and order data on infrastructure you control, the Bagisto storefront is the one that fits, and the provider-based template would mean running Bagisto's data through an adapter that does not exist. Note also that the two projects share a name pattern and nothing else; the Bagisto README does not compare itself to Vercel's template, and the dependency lists have no overlap beyond Next.js and React themselves.

## Licence, versions and what upgrading costs

The repository is MIT licensed, and the README carries a Packagist licence badge that resolves to the same. MIT is permissive: you can use the storefront in a commercial deployment, modify it and redistribute it, provided the licence and copyright notice travel with it. That covers this frontend only. Bagisto itself is a separate repository with its own licence, so check that one independently before you assume the whole stack is MIT. None of this is legal advice; read license.md in the repository root.

The version picture is split in a way that matters for upgrades. The package.json names the package bagisto-headless-v3 at version 0.1.0, while the releases list shows v3.1.0 from 2026-03-20, v3.0.0 from 2026-01-06 and v2.2.1 from 2026-01-02. The README pins the integration to Bagisto v2.4.x and Bagisto API v1.0.3. So there are three version numbers to keep aligned: the storefront release, the Bagisto core version and the API extension version. Upgrading one without the others is the upgrade cost. The last push to the repository was on 2026-09-14, and package.json includes a package-version script that runs npm-check-updates, which suggests dependency bumps are a routine part of maintenance rather than a rare event. Budget for them: the dependency list carries Next.js 16, React 19, Apollo Client 4, Tailwind 4 and TypeScript 6, and major bumps in any of those can touch the whole src/ tree.

## Conclusion

Adopt it if you already run Bagisto v2.4.x with the Headless Extension installed and want a TypeScript storefront instead of Bagisto's own Blade theme. Do not adopt it as a standalone shop: without a Bagisto instance and a pk_storefront_ key it has nothing to render. Before committing, verify that the storefront key your Bagisto install issues actually works against the API version the scaffold targets, and check whether the storefront flows you depend on are covered by the extension rather than assumed.

## FAQ

### What is Bagisto Next.js Commerce?

It is a headless storefront built with Next.js that renders a Bagisto shop through Bagisto's GraphQL APIs. The README describes it as a headless eCommerce framework built with Next.js and powered by Bagisto, and it requires an existing Bagisto installation plus the Bagisto Headless Extension.

### What do I need installed before running Bagisto Next.js Commerce?

The README lists Node.js 20+ and npm as the frontend prerequisites, and its installation steps require Bagisto itself plus the Bagisto Headless Extension to expose the APIs. You also need a storefront key from that Bagisto instance for NEXT_PUBLIC_BAGISTO_STOREFRONT_KEY.

### How do I start the Bagisto Next.js Commerce storefront locally?

The README scaffolds it with npx -y @bagisto-headless/create your-storefront, then you fill in .env.local, run npm install and npm run dev, and open http://localhost:3000. The product data on that page comes from the Bagisto endpoint you configured, so an empty page points at the backend configuration.

### Which Bagisto version does Bagisto Next.js Commerce work with?

The README states Bagisto Version v2.4.x and Bagisto API v1.0.3. The repository's own releases are numbered separately, with v3.1.0 published on 2026-03-20.

### What licence does Bagisto Next.js Commerce use?

The repository is MIT licensed, and license.md sits in the repository root. Bagisto itself is a separate project with its own licence, so verify that one separately if you plan to deploy the full stack.

## Sources

- [bagisto/nextjs-commerce on GitHub](https://github.com/bagisto/nextjs-commerce)
- [License: MIT](https://github.com/bagisto/nextjs-commerce/blob/main/LICENSE)
- [Project website](https://bagisto-headless.vercel.app/)
- [README](https://github.com/bagisto/nextjs-commerce/blob/main/README.md)
- [Releases](https://github.com/bagisto/nextjs-commerce/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bagisto-nextjs-commerce