Deploy Next.js to Quant

Quick start with the wizard

The Quant deployment wizard auto-detects Next.js projects and generates the correct build configuration. Start from a Next.js template or import your existing repo.

Next.js is a popular React framework with excellent support for both static generation and server-side rendering. This guide covers deploying Next.js applications to Quant.

Deployment options

Approach	Best for	Platform
Static Export	Marketing sites, blogs, documentation	Quant Static
Server-side Rendering	Dynamic apps, authenticated content, API routes	Quant Cloud

Static Export

For sites that can be fully pre-rendered, static export gives you the fastest performance with global CDN delivery.

Step 1: Configure Next.js for static export

Update your next.config.js:

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
  // Optional: Add trailing slashes
  trailingSlash: true,
  // Optional: Disable image optimisation (not supported in static export)
  images: {
    unoptimized: true,
  },
};

module.exports = nextConfig;

Step 2: Build and export

npm run build

This creates an out/ directory with your static site.

Step 3: Deploy with CLI

npm install -g @quantcdn/quant-cli

# Initialise
quant init
# Set directory to: out

# Deploy
quant deploy

Step 4: GitHub Actions workflow

Create .github/workflows/deploy.yml:

name: Deploy Next.js to Quant

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'

      - name: Install dependencies
        run: npm ci

      - name: Restore revision log
        uses: actions/cache@v5
        with:
          path: .quant-revision
          key: quant-revision-${{ github.ref }}-${{ github.run_id }}
          restore-keys: |
            quant-revision-${{ github.ref }}-

      - name: Build Next.js
        run: npm run build

      - name: Deploy to Quant
        uses: quantcdn/deploy-action@v6
        with:
          customer: ${{ secrets.QUANT_CUSTOMER }}
          project: ${{ secrets.QUANT_PROJECT }}
          token: ${{ secrets.QUANT_TOKEN }}
          dir: out
          revision-log: .quant-revision
          skip-purge: true

      - name: Purge cache
        uses: quantcdn/purge-action@v6
        with:
          customer: ${{ secrets.QUANT_CUSTOMER }}
          project: ${{ secrets.QUANT_PROJECT }}
          token: ${{ secrets.QUANT_TOKEN }}
          url_pattern: "/*"

Static export limitations

Static export doesn’t support:

• Server Components that fetch data at request time
• API Routes
• Middleware
• Draft Mode
• Incremental Static Regeneration (ISR)

If you need these features, use Quant Cloud for server-side rendering.

Server-side Rendering with Quant Cloud

For full Next.js functionality including API routes, server components, and dynamic rendering, deploy to Quant Cloud.

Step 1: Configure Next.js

For App Router (recommended):

/** @type {import('next').NextConfig} */
const nextConfig = {
  // Use standalone output for containerised deployment
  output: 'standalone',
};

module.exports = nextConfig;

Step 2: Create a Dockerfile

Create a Dockerfile in your project root:

FROM node:20-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json package-lock.json* ./
RUN npm ci

# Rebuild the source code only when needed
FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

ENV NEXT_TELEMETRY_DISABLED=1

RUN npm run build

# Production image
FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
ENV PORT=3000
ENV HOSTNAME="0.0.0.0"

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

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

Step 3: Create a Quant Cloud application

1. Go to the Quant Dashboard
2. Navigate to Cloud Applications → New Application
3. Configure your application and environment

Step 4: Deploy with GitHub Actions

Create .github/workflows/deploy-cloud.yml:

name: Deploy Next.js to Quant Cloud

on:
  push:
    branches: [main]

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

      - name: Initialise Quant Cloud
        uses: quantcdn/quant-cloud-init-action@v1
        id: init
        with:
          quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
          quant_api_key: ${{ secrets.QUANT_API_KEY }}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push image
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/arm64
          push: true
          tags: ${{ steps.init.outputs.stripped_endpoint }}/${{ secrets.QUANT_ORGANIZATION }}/my-nextjs-app:web${{ steps.init.outputs.image_suffix }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Deploy environment
        uses: quantcdn/quant-cloud-environment-action@v1
        with:
          quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
          quant_api_key: ${{ secrets.QUANT_API_KEY }}
          application: my-nextjs-app
          environment: production
          operation: update

Environment variables

Build-time variables

For static export, set environment variables in your CI workflow:

- name: Build Next.js
  run: npm run build
  env:
    NEXT_PUBLIC_API_URL: https://api.example.com

Runtime variables (Quant Cloud)

Configure in the dashboard under Environment Variables, or use the GitHub Action:

- name: Set environment variables
  uses: quantcdn/quant-cloud-environment-var-action@v1
  with:
    quant_organization: ${{ secrets.QUANT_ORGANIZATION }}
    quant_api_key: ${{ secrets.QUANT_API_KEY }}
    application: my-nextjs-app
    environment: production
    variables: |
      DATABASE_URL=${{ secrets.DATABASE_URL }}
      API_SECRET=${{ secrets.API_SECRET }}

Hybrid approach

For the best of both worlds, you can:

1. Static pages → Deploy to Quant Static for fastest delivery
2. Dynamic routes → Deploy to Quant Cloud
3. Use Page Rules → Route traffic appropriately

Example: Serve marketing pages statically, route /app/* to your Cloud instance.

App Router vs Pages Router

Both routers work with Quant:

Router	Static Export	Quant Cloud
App Router	✅ Full support	✅ Full support
Pages Router	✅ Full support	✅ Full support

For new projects, the App Router is recommended for its improved features and performance.

Performance tips

1. Use static generation where possible — Pre-render pages at build time for best performance
2. Enable image optimisation — In Quant dashboard settings for static exports
3. Leverage ISR on Quant Cloud — Incremental Static Regeneration works with server deployment
4. Cache API responses — Use appropriate cache headers for API routes

Troubleshooting

”Image Optimization API is required” error

For static export, disable the Image Optimization API:

next.config.js

module.exports = {
  output: 'export',
  images: {
    unoptimized: true,
  },
};

Alternatively, use Quant’s built-in image optimisation by enabling it in the dashboard.

Dynamic routes returning 404

For static export, ensure all dynamic routes are generated at build time:

app/posts/[slug]/page.js

export async function generateStaticParams() {
  const posts = await getPosts();
  return posts.map((post) => ({ slug: post.slug }));
}

API routes not working

API routes require server-side rendering. For static export, move API logic to:

• External API services
• Serverless functions
• Quant Cloud deployment

Container health check failing

Ensure your application:

1. Listens on the correct port (default: 3000)
2. Responds to health check requests
3. Binds to 0.0.0.0, not localhost

next.config.js

module.exports = {
  output: 'standalone',
  experimental: {
    // Ensure proper hostname binding
  },
};

Next steps

• Add a custom domain — Point your domain to Quant
• Configure WAF — Protect your application
• Set up Quant Cloud — Full container hosting documentation