A Next.js 14 and App Router-ready ecommerce template featuring:
- Next.js App Router
- Optimized for SEO using Next.js's Metadata
- React Server Components (RSCs) and Suspense
- Server Actions for mutations
- Edge Runtime
- New fetching and caching paradigms
- Dynamic OG images
- Styling with Tailwind CSS
- Checkout and payments with Swell
- Automatic light/dark mode based on system settings
Next.js Commerce utilizes the Swell Frontend API to provide client-safe access to your store's data. The Frontend API has read-only permissions for most models including products, categories, navigation menus, pages, and more. With the addition of a session token, cart management, checkout, and account editing flows scoped to each customer are also available.
Note: Looking for Next.js Commerce v1? View the code, demo, and release notes
To connect Next.js Commerce to a Swell store, you will need to set the environment variables defined in .env.example
. Using Vercel Environment Variables for this is recommended, but a .env
file is all that is necessary.
Note: If using an
.env
file, you should not commit this to your repository as it may expose secrets that allow others to access your store.
To use Vercel Environment Variables:
- Install Vercel CLI:
npm i -g vercel
- Link a Vercel project:
vercel link
(this creates a.vercel
directory) - Download your environment variables:
vercel env pull
Expand if you work at Vercel and want to run locally and/or contribute
- Run
vc link
. - Select the
Vercel Solutions
scope. - Connect to the existing
commerce-swell
project. - Run
vc env pull
to get environment variables. - Run
pnpm dev
to ensure everything is working correctly.
-
Create a
SWELL_STORE_ID
environment variable and use your Swell store ID as the the value. When logged in to the Swell admin dashboard, the current store's ID is visible in the URL as the subdomain:https://SWELL_STORE_ID.swell.store/admin/settings/api
-
In order to use the Frontend API, you need to obtain a public key for your Swell Store. In the admin dashboard, go to Developer > API keys to create a new key. Once created, set this as the value of
SWELL_PUBLIC_KEY
in your environment variables.
Expand to view detailed walkthrough
Note: Ensure you are using Node v16 or above before running the install command.
pnpm install
pnpm dev
Your app should now be running on localhost:3000.
Using on-demand revalidation in Next.js is recommended to optimize data fetching and serve requests from cache unless data is changed.
We can do this with Swell's webhooks triggered by certain model events, which can notify your Next.js app when data it depends on has changed.
The following webhook events are pre-configured in /app/api/revalidate/route.ts
and automatically revalidate the Next.js cache.
product.created
product.deleted
product.updated
category.created
category.deleted
category.updated
The above product events are triggered when variants are added, updated, and removed, as well as when stock is updated.
Note: If you add functionality that uses data from other models, you will need to configure the relevant events to listen for in
/app/api/revalidate/route.ts
.
- Create your own secret or generate a random UUID.
- Create an environment variable named
SWELL_REVALIDATION_SECRET
and use the value from step 1.
- Navigate to
https://SWELL_STORE_ID.swell.store/admin/settings/webhooks
. - Add a new webhook pointing to
https://DEPLOYMENT_URL/api/revalidate?secret=SECRET
, whereDEPLOYMENT_URL
is the domain where your app is deployed, and[SECRET]
is the secret you just created. - Select the six product and category events listed above. You can add more sets for other preview urls, environments, or local development.
Expand to view detailed walkthrough
![Swell store webhooks](https://github.com/swellstores/verswell-commerce/assets/9212793/dca90e1c-1802-4d96-925e-582b427e2d5d) ![Swell store add webhook](https://github.com/swellstores/verswell-commerce/assets/9212793/25178bf9-ad68-447e-9f3f-eb613005653e) ![swell-internal-next-marketplace swell store_admin_settings_api (7)](https://github.com/swellstores/verswell-commerce/assets/9212793/a8565675-3cff-4b61-9881-f243ec5e5746)The easiest way to test webhooks while developing locally is to use ngrok.
- Install and configure ngrok (you will need to create an account).
- Run your app locally,
npm run dev
. - In a separate terminal session, run
ngrok http 3000
. - Use the url generated by ngrok and add or update your webhook urls in Swell.
- You can now make changes to your store and your local app should receive updates. You can also use the
Send test notification
button to trigger a generic webhook test.