Next.js Swell Commerce

🔴 The repository is currently a Work in Progress 🔴

The Swell Team is currently working on supporting the Vercel Commerce v2. Updates will be made to this repository. If you'd like to visit the Next.js Commerce v1 Repo with Swell Backend Support, you can do so here.

A Next.js 13 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 Shopify
• Automatic light/dark mode based on system settings

Note: Looking for Next.js Commerce v1? View the code, demo, and release notes

Running locally

You will need to use the environment variables defined in .env.example to run Next.js Commerce. It's recommended you use Vercel Environment Variables for this, but a .env file is all that is necessary.

Note: You should not commit your .env file or it will expose secrets that will allow others to control your Shopify store.

1. Install Vercel CLI: npm i -g vercel
2. Link local instance with Vercel and GitHub accounts (creates .vercel directory): vercel link
3. Download your environment variables: vercel env pull

pnpm install
pnpm dev

Your app should now be running on localhost:3000.

Expand if you work at Vercel and want to run locally and / or contribute

1. Run vc link.
2. Select the Vercel Solutions scope.
3. Connect to the existing commerce-swell project.
4. Run vc env pull to get environment variables.
5. Run pmpm dev to ensure everything is working correctly.

Add Shopify domain to an environment variable

Create a SWELL_STORE_ID environment variable and use your Swell store ID as the the value.

Accessing the Swell Frontend API

Next.js Commerce utilizes Swell's Frontend API to create unique customer experiences. The API offers a full range of commerce options making it possible for customers to control products, collections, menus, pages, cart, checkout, and more.

In order to use the Swell's Frontend API, you need to obtain a public key in your Swell Store.

Once created, you'll need to create a SWELL_STOREFRONT_PUBLIC_KEY environment variable and use the public access token as the value

Expand to view detailed walkthrough

1. Navigate to https://SWELL_STORE_ID.swell.store/admin/settings/api.
2. Click the Add public key button.
3. Add a decription to your public key and press the Create Key button
4. Copy the public key and assign it to the SWELL_STOREFRONT_PUBLIC_KEY environment variable

Configure webhooks for on-demand incremental static regeneration (ISR)

Utilizing Swell's webhooks, and listening for select Swell webhook event topics, we can use Next'js on-demand revalidation to keep data fetches indefinitely cached until certain events in the Shopify store occur.

Next.js is pre-configured to listen for the following Swell webhook events and automatically revalidate fetches.

• category.created
• category.deleted
• category.updated
• product.created
• product.deleted
• product.updated (this also includes when variants are added, updated, and removed as well as when products are purchased so inventory and out of stocks can be updated)

Expand to view detailed walkthrough

Setup secret for secure revalidation

1. Create your own secret or generate a random UUID.
2. Create a Vercel Environment Variable named SHOPIFY_REVALIDATION_SECRET and use the value from above.

Configure Swell webhooks

1. Navigate to https://SWELL_STORE_ID.swell.store/admin/settings/webhooks.
2. Add webhooks for all six event topics listed above. You can add more sets for other preview urls, environments, or local development. Append ?secret=[SECRET] to each url, where [SECRET] is the secret you created above.

Testing webhooks during local development

The easiest way to test webhooks while developing locally is to use ngrok.

1. Install and configure ngrok (you will need to create an account).
2. Run your app locally, npm run dev.
3. In a separate terminal session, run ngrok http 3000.
4. Use the url generated by ngrok and add or update your webhook urls in Swell.
5. 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.