Deploy Nuxt on AWS

Deploy your Nuxt applications to AWS using Thunder. Choose the pattern that fits your app’s needs.

Available Patterns

Prerequisites

Getting Started

Create Project

Scaffold a new Nuxt project using your preferred package manager. This sets up the project structure, installs dependencies, and prepares you for development.

bunx nuxi@latest init my-nuxt-app
cd my-nuxt-app
bun install

npx nuxi@latest init my-nuxt-app
cd my-nuxt-app
npm install

pnpm dlx nuxi@latest init my-nuxt-app
cd my-nuxt-app
pnpm install

Install Thunder

Add Thunder as a development dependency. It provides the CDK constructs you’ll use to define your AWS infrastructure.

bun add @thunder-so/thunder --development

npm install @thunder-so/thunder --save-dev

pnpm add -D @thunder-so/thunder

Nuxt Static Site Deployment

Deploy a client-side rendered Nuxt app to S3 with CloudFront as the CDN. In this mode, Nuxt disables server-side rendering and outputs a fully client-rendered SPA — no server required.

Configure

Disable SSR in your Nuxt config to switch to client-side rendering mode. The build output will be placed in .output/public/.

export default defineNuxtConfig({
  ssr: false,
})

Stack

The Static construct provisions an S3 bucket, a CloudFront distribution, and optionally a Route53 DNS record.

import { Cdk, Static, type StaticProps } from '@thunder-so/thunder';

const config: StaticProps = {
  env: { account: 'YOUR_ACCOUNT_ID', region: 'us-east-1' },
  application: 'myapp',
  service: 'web',
  environment: 'prod',
  rootDir: '.',
  outputDir: '.output/public',
};

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

Deploy

Build your Nuxt app first, then deploy with CDK. CDK uploads the static files to S3 and provisions the CloudFront distribution.

bun run build
npx cdk deploy --app "bunx tsx stack/prod.ts" --profile default

npm run build
npx cdk deploy --app "npx tsx stack/prod.ts" --profile default

pnpm run build
pnpm exec cdk deploy --app "pnpm exec tsx stack/prod.ts" --profile default

After deployment, CDK outputs a CloudFront URL where your app is live.

Nuxt Containerized Deployment with Fargate

Run your Nuxt app as a Node.js server inside a Docker container on ECS Fargate. Traffic is routed through an Application Load Balancer. This pattern supports full SSR, API routes, and any server-side logic.

Configure for Node Server

Nuxt’s default build output (.output/) is already compatible with a Node.js server — no additional adapter is needed. Just ensure your nuxt.config.ts does not have ssr: false.

Stack

The Fargate construct creates an ECS cluster, a Fargate task definition, and an Application Load Balancer.

import { Cdk, Fargate, type FargateProps } from '@thunder-so/thunder';

const config: FargateProps = {
  env: { account: 'YOUR_ACCOUNT_ID', region: 'us-east-1' },
  application: 'myapp',
  service: 'web',
  environment: 'prod',
  rootDir: '.',
  serviceProps: {
    dockerFile: 'Dockerfile',
    architecture: Cdk.aws_ecs.CpuArchitecture.ARM64,
    cpu: 512,
    memorySize: 1024,
    port: 3000,
    desiredCount: 1,
    healthCheckPath: '/',
  },
};

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

Dockerfile

Create a Dockerfile in your project root. The multi-stage build keeps the final image lean by separating the build environment from the runtime.

FROM oven/bun:latest AS builder
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --frozen-lockfile
COPY . .
RUN bun run build

FROM oven/bun:latest AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV HOST=0.0.0.0
ENV PORT=3000
COPY --from=builder /app/.output ./
EXPOSE 3000
CMD ["bun", "run", "server/index.mjs"]

Environment Variables and Secrets

Runtime environment variables are injected into the Fargate task at deploy time. For sensitive values, store them in AWS Secrets Manager and reference them by ARN — Thunder fetches and injects them automatically.

const config: FargateProps = {
  // ...
  serviceProps: {
    // ...
    variables: [
      { NODE_ENV: 'production' },
    ],
    secrets: [
      {
        key: 'DATABASE_URL',
        resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/DATABASE_URL-abc123',
      },
    ],
  },
};

Deploy

CDK builds the Docker image, pushes it to ECR, and deploys it to Fargate. No manual Docker commands needed.

npx cdk deploy --app "bunx tsx stack/prod.ts" --profile default

npx cdk deploy --app "npx tsx stack/prod.ts" --profile default

pnpm exec cdk deploy --app "pnpm exec tsx stack/prod.ts" --profile default

After deployment, CDK outputs the Load Balancer DNS for your application.

Nuxt Serverless Fullstack Deployment

Deploy Nuxt with SSR using AWS Lambda for server-side rendering, S3 for static assets, and CloudFront to unify both behind a single domain. This pattern scales to zero and charges only for actual requests.

Configure Nuxt for AWS Lambda

Nuxt uses Nitro as its server engine. Set the aws-lambda preset to tell Nitro to output a Lambda-compatible handler instead of a Node.js HTTP server. You can set this via an environment variable or directly in your config.

NITRO_PRESET=aws-lambda

export default defineNuxtConfig({
  nitro: {
    preset: 'aws-lambda',
  },
})

The build will produce .output/server/ (Lambda handler) and .output/public/ (static assets for S3).

Stack (Zip mode)

The Nuxt construct wires up Lambda, API Gateway, S3, and CloudFront automatically. By default, Thunder packages your Lambda handler as a Zip deployment — the fastest option for most apps.

import { Cdk, Nuxt, type NuxtProps } from '@thunder-so/thunder';

const config: NuxtProps = {
  env: { account: 'YOUR_ACCOUNT_ID', region: 'us-east-1' },
  application: 'myapp',
  service: 'web',
  environment: 'prod',
  rootDir: '.',
};

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

Container Mode

Zip deployments have a 250 MB unzipped size limit. If your app has large dependencies — native modules, ML libraries, or heavy assets — switch to container mode. Thunder builds a Docker image, pushes it to ECR, and deploys it as a container Lambda, which supports up to 10 GB.

Stack (Container mode)

Add dockerFile to serverProps to enable container mode.

const config: NuxtProps = {
  // ...
  serverProps: {
    dockerFile: 'Dockerfile',
    memorySize: 2048,
  },
};

Dockerfile

FROM public.ecr.aws/lambda/nodejs:22

# Copy all lambda files
COPY . ./

CMD ["index.handler"]

Environment Variables and Secrets

Runtime environment variables are injected into the Lambda function at deploy time. For sensitive values, store them in AWS Secrets Manager and reference them by ARN — Thunder fetches and injects them automatically.

const config: NuxtProps = {
  // ...
  serverProps: {
    variables: [
      { NODE_ENV: 'production' },
    ],
    secrets: [
      {
        key: 'DATABASE_URL',
        resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/myapp/DATABASE_URL-abc123',
      },
    ],
  },
};

Deploy

Build your Nuxt app first to generate the Lambda handler and static assets, then deploy with CDK.

bun run build
npx cdk deploy --app "bunx tsx stack/prod.ts" --profile default

npm run build
npx cdk deploy --app "npx tsx stack/prod.ts" --profile default

pnpm run build
pnpm exec cdk deploy --app "pnpm exec tsx stack/prod.ts" --profile default

After deployment, CDK outputs a CloudFront URL that serves both your SSR responses and static assets.