cdk-nuxt

AWS CDK Nuxt Deployment Stack (Nuxt 3 & Nuxt 4)

Easily deploy Nuxt applications (Nuxt 3 and Nuxt 4) via CDK on AWS, including the following features:

• ⚡ Fast responses via AWS Lambda
• 🌐 Custom domain support via Route53 and CloudFront
• 🔒 Automatic HTTPS with certificate management
• 📦 Optimized static asset delivery via S3
• 🔥 Lambda warming via scheduled EventBridge pings
• 🗑️ Automatic cleanup of outdated assets
• 📊 Access logs analysis via Athena (docs)
• 🛡️ WAF integration for security (docs)
• ⚙️ Flexible caching configuration (docs)

Quick Links

• 📚 Full Configuration Reference
• 🚀 Deployment Guide
• 🛡️ WAF Documentation
• 📊 Access Logs Analysis
• 🔄 Caching Configuration

Table of Contents

• Compatibility
• Quick Start
• AWS Resources Created
• Documentation

Compatibility

• ✅ Nuxt 3 (latest stable)
• ✅ Nuxt 4 (RC and stable)

Quick Start

1. Installation

Install the package and its peer dependencies:

# Using pnpm (recommended)
pnpm add -D cdk-nuxt aws-cdk@^2.1110.0 aws-cdk-lib@^2.241.0 constructs@^10.5.0 typescript ts-node

# Using npm
npm install --save-dev cdk-nuxt aws-cdk@^2.1110.0 aws-cdk-lib@^2.241.0 constructs@^10.5.0 typescript ts-node

# Using yarn
yarn add -D cdk-nuxt aws-cdk@^2.1110.0 aws-cdk-lib@^2.241.0 constructs@^10.5.0 typescript ts-node

The AWS CDK CLI must be at least 2.1107.0 (check with pnpm cdk --version).

Optional: If you plan to enable Access Logs Analysis:

pnpm add -D @aws-cdk/aws-glue-alpha@2.241.0-alpha.0

2. Configure Nuxt

Set the Nitro preset in your nuxt.config.ts:

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

Important: Remove "type": "module" from your package.json if present (why?).

3. AWS Prerequisites

Before deployment, you need:

1. AWS Account - Create one if you don't have one
2. Route53 Hosted Zone - For your domain (guide)
3. SSL Certificates - Two certificates for HTTPS:
   • Global certificate (us-east-1) for CloudFront (request)
   • Regional certificate (your region) for API Gateway (request)

4. Initialize CDK Stack

Generate the CDK stack configuration:

node_modules/.bin/cdk-nuxt-init-server

This creates stack/index.ts with a complete template including all available configuration options with sensible defaults.

Update the following required values:

• env.account and env.region - Your AWS account and region
• project, service, environment - Identifiers for your app
• domain - Your custom domain
• hostedZoneId - Your Route53 hosted zone ID
• globalTlsCertificateArn - Certificate in us-east-1 for CloudFront
• regionalTlsCertificateArn - Certificate in your region for API Gateway

The full template can also be viewed here: lib/templates/stack-index-server.ts

For a complete list of all configuration options, see the Configuration Reference.

💡 Tip: Use environment variables or a .env file to store sensitive values like certificate ARNs and AWS account IDs.

5. Bootstrap and Deploy

First-time setup (once per AWS account/region):

cdk bootstrap aws://YOUR_ACCOUNT_ID/YOUR_REGION

When using the WAF via CloudFrontWafStack and using a different region than us-east-1, you also need to bootstrap us-east-1 for the WAF resources:

cdk bootstrap aws://YOUR_ACCOUNT_ID/us-east-1

Deploy your app:

node_modules/.bin/cdk-nuxt-deploy-server

That's it! Your Nuxt app is now live on AWS. 🎉

For detailed deployment options and CI/CD setup, see the Deployment Guide.

AWS Resources Created

When you deploy your Nuxt app, the following AWS resources are automatically created:

• Lambda Functions:

  • Main SSR function for rendering your Nuxt app
  • Lambda Layer for node_modules
  • Cleanup function for outdated assets

• S3 Buckets:

  • Static assets bucket (.nuxt/dist/client)
  • Access logs bucket (if enabled)

• CloudFront:

  • Global CDN distribution with HTTPS
  • Optimized cache behaviors for static and dynamic content

• API Gateway:

  • HTTP API for Lambda function access
  • Custom domain configuration

• Route53:

  • DNS records (A and AAAA) for your domain

• EventBridge Rules:

  • Lambda warming (every 5 minutes)
  • Asset cleanup (weekly, Tuesdays at 03:30 GMT)

• Athena (optional):

  • Database and tables for access log analysis
  • Automatic log partitioning

• WAF (optional):

  • Web Application Firewall for CloudFront distribution
  • Protection against common web exploits, bots, and DDoS attacks
  • Configurable managed rules and rate limiting

For more details on each resource and their configuration, see the Deployment Guide.

Documentation

Getting Started

• Quick Start - Get up and running quickly
• Deployment Guide - Detailed deployment instructions, CI/CD setup
• Configuration Reference - Complete list of all configuration options

Features

• WAF Integration - Protect your app with AWS WAF
• Access Logs Analysis - Analyze traffic with Athena
• Caching Configuration - Optimize performance with CloudFront caching

Advanced

• Destroy the Stack - Clean up resources

Destroy the Stack

To completely remove all AWS resources created by this package:

node_modules/.bin/cdk-nuxt-destroy-server

⚠️ Warning: This permanently deletes all resources including S3 buckets and logs. This action cannot be undone.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions