Deploy Next.js on AWS with Thunder

Deploy your Next.js applications to AWS using Thunder patterns. This guide covers both static export deployment and full-stack server-side rendering options.

There are two deployment patterns available for Next.js on AWS:

  1. Static Export (SPA) — Deploy static Next.js sites using S3 and CloudFront with the Static construct
  2. Full Stack — Deploy SSR Next.js applications using ECS Fargate with the Fargate construct

Static Export (SPA) Deployment

Deploy Next.js static export applications to S3 and CloudFront using the Static construct. This pattern is ideal for static sites, blogs, and client-side applications.

Create Project

Terminal window
npm create next-app@latest my-nextjs-app
cd my-nextjs-app

Configure Next.js for Static Export

next.config.mjs
import type { NextConfig } from "next";


const nextConfig: NextConfig = {
  output: "export", // Enable static export
};


export default nextConfig;

In your tsconfig.json, ensure the stack directory is excluded:

tsconfig.json
{
  "compilerOptions": {
    // ... other options
  },
  "exclude": ["node_modules", "stack"]
}

Install Dependencies and Setup Stack

Terminal window
npm i tsx @thunder-so/thunder --save-dev
stack/index.ts
import { Cdk, Static, type StaticProps } from "@thunder-so/thunder";


const myApp: StaticProps = {
  env: {
    account: 'your-account-id',
    region: 'us-east-1'
  },
  application: 'your-application-id',
  service: 'your-service-id',
  environment: 'production',


  rootDir: '', // e.g. 'frontend' for monorepos
  outputDir: 'out',
};


new Static(
  new Cdk.App(),
  `${myApp.application}-${myApp.service}-${myApp.environment}-stack`,
  myApp
);

Deploy

Build and deploy your static site:

Terminal window
npm run build
npx cdk deploy --all --app="npx tsx stack/index.ts"

After deployment, you’ll receive a CloudFront URL to access your static site.

Full Stack Deployment

Deploy server-side rendered Next.js applications using ECS Fargate and Application Load Balancer with the Fargate construct.

Configure Next.js for SSR

next.config.mjs
import type { NextConfig } from "next";


const nextConfig: NextConfig = {
  // Next.js defaults to SSR, no configuration needed
};


export default nextConfig;

Install Dependencies and Setup Stack

Terminal window
npm i tsx @thunder-so/thunder --save-dev
stack/index.ts
import { Cdk, Fargate, type FargateProps } from "@thunder-so/thunder";


const svcProps: FargateProps = {
  env: {
    account: 'your-account-id',
    region: 'us-west-2'
  },
  application: 'your-application-id',
  service: 'your-service-id',
  environment: 'production',


  rootDir: '', // e.g. 'app' for monorepos
};


new Fargate(
  new Cdk.App(),
  `${svcProps.application}-${svcProps.service}-${svcProps.environment}-stack`,
  svcProps
);

Build Settings Using Nixpacks

Configure automatic containerization with Nixpacks:

stack/index.ts
const svcProps: FargateProps = {
  // ... other props


  buildProps: {
    buildSystem: 'Nixpacks',
    installcmd: 'npm install',
    buildcmd: 'npm run build',
    startcmd: 'npm start',
  },
};

Build Settings Using Docker Container

Alternatively, use a custom Dockerfile:

Dockerfile
FROM public.ecr.aws/docker/library/node:20-alpine AS base


FROM base AS builder
WORKDIR /app


COPY package*.json ./
RUN npm ci


COPY . .
RUN npm run build


FROM base AS runner
WORKDIR /app


ENV NODE_ENV=production


COPY --from=builder /app/.next/standalone ./
COPY --from=builder /app/.next/static ./.next/static


EXPOSE 3000


CMD ["node", "server.js"]
stack/index.ts
const svcProps: FargateProps = {
  // ... other props


  serviceProps: {
    dockerFile: 'Dockerfile',
    port: 3000,
  },
};

Environment Variables and Secrets for SSR

Configure runtime environment variables and secrets:

stack/index.ts
const svcProps: FargateProps = {
  // ... other props


  serviceProps: {
    variables: [
      { NODE_ENV: 'production' },
      { NEXT_PUBLIC_API_URL: 'https://api.example.com' }
    ],
    secrets: [
      {
        key: 'DATABASE_URL',
        resource: 'arn:aws:secretsmanager:us-west-2:123456789012:secret:/my-app/DATABASE_URL-abc123'
      },
    ],
  },
};

Deploy

Build and deploy your containerized application:

Terminal window
npm run build
npx cdk deploy --all --app="npx tsx stack/index.ts"

After deployment, you’ll receive an Application Load Balancer URL to access your SSR application.