CDK Nuxt

Deploy full-stack Nuxt applications on AWS with CI/CD.

AWS resources:

• Server-side rendering (SSR) with Lambda for dynamic content generation
• Fast responses from CloudFront
• Automatic upload of the build files and static assets to S3 with optimized caching rules
• Publicly available by a custom domain (or subdomain) via Route53 and SSL via Certificate Manager
• Build and deploy with Github Actions
• Optional: Use Dockerfile to use container image Lambda

Prerequisites

You need an AWS account to create and deploy the required resources for the site on AWS.

Before you begin, make sure you have the following:

• Node.js and npm: Ensure you have Node.js (v18 or later) and npm installed.

• AWS CLI: Install and configure the AWS Command Line Interface.

• AWS CDK: Install the AWS CDK globally

npm install -g aws-cdk

• Before deploying, bootstrap your AWS environment:

cdk bootstrap aws://your-aws-account-id/us-east-1

This package uses the npm package manager and is an ES6+ Module.

Installation

Navigate to your project directory and install the package and its required dependencies.

Your package.json must also contain the latest tsx and cdk-nuxt:

1npm i tsx @thunderso/cdk-nuxt --save-dev

Configuration

Create the required CDK stack entrypoint at stack/index.ts. You should adapt the file to your project's needs.

[!NOTE] Use different filenames such as production.ts and testing.ts for environments.

1// stack/index.ts
2import { Cdk, NuxtStack, type NuxtProps } from "@thunderso/cdk-nuxt";
3
4const nuxtApp: NuxtProps = {
5  env: {
6    account: 'your-account-id',
7    region: 'us-west-2'
8  },
9  application: 'your-application-id',
10  service: 'your-service-id',
11  environment: 'production',
12
13  rootDir: '', // supports monorepos. e.g. app/
14
15  // ... other props
16};
17
18new NuxtStack(
19    new Cdk.App(), 
20    `${nuxtApp.application}-${nuxtApp.service}-${nuxtApp.environment}-stack`, 
21    nuxtApp
22);

Update your nuxt.config.ts to include the optimal settings for deployment on AWS:

1// nuxt.config.ts
2export default defineNuxtConfig({
3  /// ... other configs
4
5  vite: {
6    vue: {
7      script: {
8        defineModel: true,
9        propsDestructure: true,
10      },
11    },
12    build: {
13        target: 'esnext',
14    }
15  },
16
17  nitro: {
18    preset: 'aws-lambda',
19    esbuild: {
20        options: {
21            target: 'esnext'
22        },
23    },
24    experimental: {
25      wasm: true
26    },
27  },
28});

• Vite is a fast frontend build tool that improves development speed and optimizes builds, especially for frameworks like Vue and Nuxt. The vite options enable advanced Vue features (defineModel, propsDestructure), set the build target to modern JavaScript (esnext),

• Nitro is Nuxt's server engine, responsible for building and deploying server-side code. The nitro options set the deployment target to AWS Lambda (preset: 'aws-lambda') and ensure server code is also built for modern JavaScript (esnext), improving performance and compatibility with AWS environments.

Deploy

Run npm run build before you deploy.

By running the following script, the CDK stack will be deployed to AWS.

1npx cdk deploy --all --app="npx tsx stack/index.ts" 

Destroy the Stack

If you want to destroy the stack and all its resources (including storage, e.g., access logs), run the following script:

1npx cdk destroy --all --app="npx tsx stack/index.ts" 

Deploy using GitHub Actions

In your GitHub repository, add a new workflow file under .github/workflows/deploy.yml with the following content:

1name: Deploy Nuxt to AWS
2
3on:
4  push:
5    branches:
6      - main  # or the branch you want to deploy from
7
8jobs:
9  deploy:
10    runs-on: ubuntu-latest
11    steps:
12      - name: Checkout code
13        uses: actions/checkout@v3
14
15      - name: Install dependencies
16        run: npm ci
17
18      - name: Build application
19        run: npm run build
20
21      - name: Deploy to AWS
22        run: |
23          npx cdk deploy --require-approval never --all --app="npx tsx stack/index.ts"
24        env:
25          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
26          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
27          AWS_DEFAULT_REGION: 'us-east-1'  # or your preferred region

Add AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as repository secrets in GitHub. These should be the access key and secret for an IAM user with permissions to deploy your stack.

Manage Domain with Route53

1. Create a hosted zone in Route53 for the desired domain, if you don't have one yet.

This is required to create DNS records for the domain to make the app publicly available on that domain. On the hosted zone details you should see the Hosted zone ID of the hosted zone.

2. Request a public global certificate in the AWS Certificate Manager (ACM) for the desired domain in us-east-1 (global) and validate it, if you don't have one yet.

This is required to provide the app via HTTPS on the public internet. Take note of the displayed ARN for the certificate.

3. Request a regional certificate in ACM for the same domain in the same region as your CDK stack. This is required for API Gateway.

[!IMPORTANT] The globalCertificateArn certificate must be issued in us-east-1 (global) regardless of the region used for the app itself as it will be attached to the CloudFront distribution which works globally. The regionalCertificateArn certificate must be issued in the same region as your stack.

1// stack/index.ts
2const nuxtApp: NuxtProps = {
3  // ... other props
4
5  // Domain settings
6  // - create a hosted zone for your domain in Route53
7  // - issue a global TLS certificate in us-east-1 in AWS ACM
8  // - issue a regional TLS certificate in the same region as your stack
9  domain: 'sub.example.com',
10  hostedZoneId: 'XXXXXXXXXXXXXXX',
11  globalCertificateArn: 'arn:aws:acm:us-east-1:123456789012:certificate/abcd1234-abcd-1234-abcd-1234abcd1234', // must be in us-east-1
12  regionalCertificateArn: 'arn:aws:acm:us-west-2:123456789012:certificate/efgh5678-efgh-5678-efgh-5678efgh5678', // must match your stack's region
13};

Configure the Lambda

Each configuration property provides a means to fine-tune your function’s performance and operational characteristics.

1// stack/index.ts
2import { Runtime, Architecture } from 'aws-cdk-lib/aws-lambda';
3
4const nuxtApp: NuxtProps = {
5  // ... other props
6  
7  serverProps: {
8    runtime: Runtime.NODEJS_20_X,
9    architecture: Architecture.ARM_64,
10    memorySize: 1792,
11    timeout: 10,
12    tracing: false,
13    exclude: ['**/*.ts', '**/*.map'],
14    keepWarm: true,
15  },
16};
17

runtime

Specifies the runtime environment for the Lambda function, determining which Lambda runtime API versions are available to the function.

• Type: Runtime
• Examples: Runtime.NODEJS_20_X, Runtime.NODEJS_22_X
• Default: The runtime defaults to Runtime.NODEJS_20_X.

architecture

Defines the instruction set architecture that the Lambda function supports.

• Type: Architecture
• Examples: Architecture.ARM_64, Architecture.X86_64
• Default: The architecture defaults to Architecture.ARM_64.

memorySize

The amount of memory, in MB, allocated to the Lambda function.

• Type: number
• Usage Example: memorySize: 512
• Default: 1792 MB

timeout

The function execution time (in seconds) after which Lambda will terminate the running function.

• Type: number
• Usage Example: timeout: 15
• Default: 10 seconds

tracing

Enables or disables AWS X-Ray tracing for the Lambda function.

• Type: boolean
• Usage Example: tracing: true
• Default: false

exclude

Lists the file patterns that should be excluded from the Lambda deployment package.

• Type: string[]
• Usage Example: exclude: ['*.test.js', 'README.md']
• Default: []

keepWarm

Enables an EventBridge rule to invoke the Lambda function every 5 minutes, helping to prevent cold starts by keeping the function warm.

• Type: boolean
• Default: false
• Usage Example: keepWarm: true

Environment variables

Pass environment variables to your lambda function by:

1. variables: Array of key-value pairs for plain environment variables.

2. secrets: Array of objects with key and resource (Secrets Manager ARN). The library automatically adds permissions for Lambda to read these secrets.

To create a plaintext secret in AWS Secrets Manager using the AWS CLI:

1aws secretsmanager create-secret --name "your-secret-name" --secret-string "your-secret-value"

1// stack/index.ts
2const nuxtApp: NuxtProps = {
3  // ... other props
4
5  serverProps: {
6    // ...other server props
7
8    variables: [
9      { NUXT_API_URL: 'https://api.example.com' },
10      { NUXT_PUBLIC_ANALYTICS_ID: 'UA-XXXXXX' }
11    ],
12
13    secrets: [
14      { 
15        key: 'API_URL', 
16        resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/my-app/API_URL-abc123' 
17      },
18      { 
19        key: 'API_KEY', 
20        resource: 'arn:aws:secretsmanager:us-east-1:123456789012:secret:/my-app/API_KEY-def456' 
21      },
22    ],
23  },
24};

Scaling Properties

When configuring AWS Lambda functions, understanding scaling properties is essential for efficient resource management and cost optimization. The two primary scaling properties you can configure are reservedConcurrency and provisionedConcurrency.

1// stack/index.ts
2const nuxtApp: NuxtProps = {
3  // ... other props
4  
5  serverProps: {
6    // ... other props
7    reservedConcurrency: 5,
8    provisionedConcurrency: 10,
9  },
10
11};

reservedConcurrency

Reserved concurrency sets a limit on the number of instances of the function that can run simultaneously. It ensures that your function has access to a specified amount of concurrent executions, preventing it from being throttled if account-level concurrency limits are reached.

• Use Case: This is useful when you want to have predictable execution patterns or ensure other functions don't consume all available concurrency.
• Example: reservedConcurrency: 5

provisionedConcurrency

Provisioned concurrency keeps a set of pre-initialized environments ready to respond immediately to incoming requests. This helps in reducing latency and eliminating cold starts when the function is triggered.

• Use Case: Ideal for latency-sensitive applications where response time is critical.
• Example: provisionedConcurrency: 10

While both reserved and provisioned concurrency deal with execution limits, they serve different purposes. Reserved concurrency guarantees a portion of the total function pool across your AWS account, while provisioned concurrency is specifically about warming up a set number of function instances to achieve low-latency execution.

Controlling S3 Asset Uploads

You can control which files and folders from your Nuxt build output directory (.output/public) are uploaded to S3 by using the buildProps options. This is useful for optimizing your deployment by only uploading necessary static assets and excluding unnecessary files (such as source maps, test files, or other artifacts).

1// stack/index.ts
2const nuxtApp: NuxtProps = {
3  // ... other props
4
5  buildProps: {
6    // Only include .js, .css, and .html files
7    include: ['**/*.js', '**/*.css', '**/*.html'],
8    // Exclude source maps and test files
9    exclude: ['**/*.map', '**/*.test.js'],
10  },
11};

• include: Lists the file patterns that should be excluded from the S3 deployment package.
• exclude: An array of glob patterns specifying which files to exclude from the upload. Exclusions are applied after inclusions.

Advanced: Configuring CloudFront

Custom Error Page

You can specify a custom error page to handle 404 Not Found errors by setting the errorPagePath property. This path should be relative to your application's output directory.

1const nuxtApp: NuxtProps = {
2  // ... other props
3
4  // Optional: Custom error page
5  errorPagePath: '/404.html', // Relative to the output directory. Defaults to '/index.html'.
6};

Custom Headers

You can add custom HTTP response headers to all responses served by CloudFront by specifying the headers property in your stack configuration. These headers are automatically bound to the CloudFront Response Headers Policy, allowing you to set any custom metadata required by your application.

1// stack/index.ts
2const nuxtApp: NuxtProps = {
3  // ... other props
4
5  headers: {
6    'X-App-Version': '1.0.0',
7    'X-Feature-Flag': 'beta',
8    'X-Request-Id': 'random-id',
9  },
10};

The headers property is an object where each key is the header name and the value is the header value. All custom headers defined here will be included in the CloudFront Response Headers Policy and applied to every response.

[!WARNING] Security-related headers (such as Content-Security-Policy, Strict-Transport-Security, X-Frame-Options, etc.) and CORS headers are managed separately by the library and cannot be overridden using the headers property. Use this property only for custom application headers.

[!NOTE] Custom headers are set at the CDN edge and are included in every response, regardless of whether the content is served from the Lambda origin or S3.

Customize Cache Behavior

You can fine-tune CloudFront's caching behavior by specifying which headers, cookies, and query parameters to include or exclude in the cache key. This allows you to control how CloudFront caches content and forwards requests to the origin, improving cache efficiency and ensuring dynamic content is handled correctly.

1// stack/index.ts
2const nuxtApp: NuxtProps = {
3  // ... other props
4
5  // Customize cache behavior
6  allowHeaders: ['Accept-Language', 'User-Agent'],
7  allowCookies: ['session-*', 'user-preferences'],
8  allowQueryParams: ['lang', 'theme'],
9  // Or, to exclude specific query parameters
10  // denyQueryParams: ['utm_source', 'utm_medium', 'fbclid'],
11};

• allowHeaders: An array of header names to include in the cache key and forward to the origin.
• allowCookies: An array of cookie names to include in the cache key and forward to the origin.
• allowQueryParams: An array of query parameter names to include in the cache key and forward to the origin.
• denyQueryParams: An array of query parameter names to exclude from the cache key and not forward to the origin.

If neither allowQueryParams nor denyQueryParams are specified, all query parameters are ignored in caching and not forwarded to the origin.

[!NOTE] The allowQueryParams and denyQueryParams properties are mutually exclusive. If both are provided, denyQueryParams will be ignored.

Advanced: Using Docker Container

If your Nuxt server bundle exceeds the AWS Lambda deployment package size limit (250 MB unzipped), you can deploy your application as a Lambda function packaged in a Docker container.

Lambda with container images supports up to 10 GB, making it suitable for large Nuxt server bundles and dependencies.

When to use:

• Your .output/server directory or dependencies are too large for a standard Lambda deployment.
• You need custom OS-level dependencies or binaries.
• You want full control over the runtime environment.

Create a Dockerfile in your project directory.

1FROM public.ecr.aws/lambda/nodejs:22
2
3# Set working directory to /var/task/
4WORKDIR ${LAMBDA_TASK_ROOT}
5
6# Copy .output/server directory contents to /var/task/
7COPY ./ ./
8
9# Lambda function handler
10ENV HOST=0.0.0.0
11ENV PORT=3000
12EXPOSE 3000
13
14CMD ["index.handler"]

The .output/server directory is used as the context for the container.

Reference the Dockerfile in your stack configuration:

1// stack/index.ts
2const nuxtApp: NuxtProps = {
3  // ... other props
4  
5  serverProps: {
6    dockerFile: 'Dockerfile'
7
8    // ...other server props
9    // note: runtime will be ignored when using Docker
10  },
11
12};
13

Deploy as usual. CDK will build the Docker image and deploy it to AWS Lambda as a container image.

Troubleshooting

For assistance, consult the AWS documentation or raise an issue in the GitHub repository.