Launch your Fourthwall storefront as a high-perfomance, server-rendered Next.js App Router ecommerce application.

⚡️ Live Demo

📚 API docs

There are a few prerequisites to get started with Fourthwall's Storefront API.

1. Set up a store on Fourthwall.

2. Make some products and create a collection.

3. After you have signed up, get a storefront token.

4. Fill out the environment variables below in .env.local.

NEXT_PUBLIC_FW_STOREFRONT_TOKEN="<your storefront token>" # Example: ptkn_...

NEXT_PUBLIC_FW_CHECKOUT="<your store url>" # Example: vercel-shop.fourthwall.com. Used for checkout
NEXT_PUBLIC_VERCEL_URL="<the url of your vercel site>" # Example: fw-commerce.vercel.app. This is used for sitemap.xml + robots.txt.

# Optional
NEXT_PUBLIC_FW_COLLECTION="<the handle of your collection>" # If you want to display a specific collection. See Resources for more details on how to get the collection handle.
FOURTHWALL_WEBHOOK_SECRET="<a secure random string>" # Required for Fourthwall webhook cache invalidation. See ISR section below.

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.local file is all that is necessary.

Note: You should not commit your .env.local file or it will expose secrets that will allow others to use your Fourthwall 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.

After cloning the repo with the Deploy with Vercel button above, you will need to set the environment variables.

git clone _your repo_ # your repo that you set up with Deploy with Vercel

vercel # From your repo directory. Links to your project

vercel # Initializes the project
vercel env add NEXT_PUBLIC_FW_COLLECTION
vercel env add NEXT_PUBLIC_FW_STOREFRONT_TOKEN
vercel env add NEXT_PUBLIC_FW_CHECKOUT
vercel env add NEXT_PUBLIC_VERCEL_URL

vercel --prod # Deploys to production

By default, this template uses Vercel's Image Optimization. To use Fourthwall's built-in image optimization instead, set:

NEXT_PUBLIC_USE_FW_IMAGE_OPTIMIZATION="true"

This template uses ISR to cache pages at the edge for fast load times while keeping content fresh.

• URL structure: Currency is part of the URL path (/USD/product/my-product, /EUR/collections/all) rather than a query parameter. This enables full page caching since each currency variant is a separate cached page.
• Automatic revalidation: Product and collection pages are cached and automatically revalidated every hour (revalidate = 3600).
• Home page: Pre-built at deploy time for USD, EUR, GBP, and CAD currencies.
• Product/Collection pages: Built on-demand on first request, then cached.
• Cart: Fetched client-side to keep product pages fully static.

For automatic cache invalidation when products or collections change in Fourthwall, configure the webhook endpoint.

Setup:

1. Set the FOURTHWALL_WEBHOOK_SECRET environment variable to a secure random string
2. In your Fourthwall dashboard, configure a webhook subscription pointing to:

   https://your-site.com/api/webhooks/fourthwall
   

3. Subscribe to the following events:
   • PRODUCT_CREATED
   • PRODUCT_UPDATED
   • COLLECTION_UPDATED

How it works:

When a product or collection is updated in Fourthwall, a webhook is sent to your endpoint. The endpoint:

1. Verifies the HMAC-SHA256 signature using FOURTHWALL_WEBHOOK_SECRET
2. Extracts the product/collection slug from the payload
3. Calls revalidateTag() with the appropriate tag (product-{slug} or collection-{slug})

Security:

The webhook endpoint uses HMAC-SHA256 signature verification. Fourthwall signs each webhook payload with your secret, and the endpoint verifies this signature before processing. This prevents unauthorized cache invalidation requests.

Response examples:

// Success
{ "revalidated": true, "tags": ["product-my-product"], "timestamp": 1705123456789 }

// Invalid signature
{ "error": "Invalid signature" }

// Missing configuration
{ "error": "Missing webhook secret configuration" }

This template supports multiple analytics platforms via GTM. Analytics configuration is automatically fetched from your Fourthwall store at:

<NEXT_PUBLIC_FW_CHECKOUT>/platform/analytics.json

This means tracking IDs configured in your Fourthwall dashboard are automatically used—no need to duplicate them in environment variables.

1. On page load, the app fetches analytics config from your Fourthwall store
2. The response is cached for 1 hour (ISR)
3. GTM reads the window.* variables to fire the appropriate tracking tags

If the analytics endpoint is unavailable, you can set fallback values via environment variables.

These environment variables are only used if:

• The fetch to /platform/analytics.json fails
• A specific provider returns null in the response

• How to get your collection handle.
• Style your store for the checkout flow.