Deployment - Spree Commerce documentation

Environment Variables

Set these variables in your hosting platform’s dashboard or .env file.

Required

Variable	Description
`SPREE_API_URL`	Your Spree API endpoint (e.g., `https://api.mystore.com`)
`SPREE_PUBLISHABLE_KEY`	Publishable API key from your Spree admin

These are server-side only variables — no NEXT_PUBLIC_ prefix needed since all API calls happen in Server Actions.

Optional

Variable	Description	Default
`GTM_ID`	Google Tag Manager container ID	(disabled)
`SENTRY_DSN`	Sentry DSN for error tracking	(disabled)
`SENTRY_ORG`	Sentry organization slug	(none)
`SENTRY_PROJECT`	Sentry project slug	(none)
`SENTRY_AUTH_TOKEN`	Sentry auth token (for source maps in CI)	(none)

Production Build

npm run build
npm start

The build output is a standalone Next.js application. The npm start command starts the production server.

Vercel

Vercel is the recommended deployment platform for Next.js applications.

One-Click Deploy

Push your code to GitHub
Go to vercel.com/new and import your repository
Add environment variables (SPREE_API_URL, SPREE_PUBLISHABLE_KEY)
Click Deploy

Vercel automatically detects the Next.js framework and configures the build settings.

Vercel CLI

npm i -g vercel
vercel

Preview Deployments

Every pull request gets a unique preview URL, making it easy to test storefront changes before merging. Add your Spree API environment variables to the Vercel project settings so previews connect to your staging API.

Docker

Create a Dockerfile in your project root:

FROM node:20-alpine AS base

FROM base AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --production=false

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM base AS runner
WORKDIR /app
ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs
EXPOSE 3000
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

CMD ["node", "server.js"]

Enable standalone output in your next.config.ts for Docker deployments:

const nextConfig = {
  output: 'standalone',
}

Build and run:

docker build -t spree-storefront .
docker run -p 3000:3000 \
  -e SPREE_API_URL=https://api.mystore.com \
  -e SPREE_PUBLISHABLE_KEY=your_key \
  spree-storefront

Self-Hosted Node.js

For any platform that supports Node.js (Render, Railway, Fly.io, AWS, etc.):

Install dependencies and build:

npm ci
npm run build

Start the production server:

npm start

The server listens on port 3000 by default. Set the PORT environment variable to change it.

CI/CD

GitHub Actions

name: Deploy Storefront
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run build

      # Add your deployment step here
      # Example for Vercel:
      # - uses: amondnet/vercel-action@v25
      #   with:
      #     vercel-token: ${{ secrets.VERCEL_TOKEN }}
      #     vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
      #     vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
      #     vercel-args: --prod

Performance Checklist

Before going to production, verify:

API URL points to your production Spree instance (not localhost)
HTTPS is enabled on both the storefront and the Spree API
CORS is configured on your Spree API to allow requests from your storefront domain
Sentry is configured for error monitoring (SENTRY_DSN)
GTM/GA4 is set up for analytics (GTM_ID)
Cookie security — the storefront uses secure: true for cookies in production (NODE_ENV=production)
Caching — Next.js cache tags are used for efficient revalidation; review your caching strategy for high-traffic stores

​Environment Variables

​Required

​Optional

​Production Build

​Vercel

​One-Click Deploy

​Vercel CLI

​Preview Deployments

​Docker

​Self-Hosted Node.js

​CI/CD

​GitHub Actions

​Performance Checklist

Environment Variables

Required

Optional

Production Build

Vercel

One-Click Deploy

Vercel CLI

Preview Deployments

Docker

Self-Hosted Node.js

CI/CD

GitHub Actions

Performance Checklist