Skip to content

CLAUDE.md

Latest commit

 

History

History
76 lines (52 loc) · 3.75 KB

CLAUDE.md

File metadata and controls

76 lines (52 loc) · 3.75 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

cdk-nextjs is a JSII-compatible AWS CDK construct library that deploys Next.js apps on AWS. It publishes to npm as cdk-nextjs and is managed by projen via .projenrc.ts.

Commands

# Full build (compile + lint + test + bundle + package)
pnpm build

# Compile JSII (must run before `pnpm build` when generated-structs change)
pnpm compile

# Run all tests
pnpm test

# Run a single test file
pnpm jest src/adapter/cache-handler.test.ts
pnpm jest src/nextjs-cache.test.ts

# Lint
pnpm eslint

# Bundle adapter/lambdas (esbuild)
pnpm bundle

# Regenerate projen-managed files after editing .projenrc.ts
pnpm projen

Important: After modifying .projenrc.ts, run pnpm projen to regenerate managed files. Do not hand-edit projen-managed files (they have a header comment indicating this).

Build Order Quirk

The project uses @mrgrain/jsii-struct-builder to generate "Optional" versions of structs (in src/generated-structs/). This tool reads the .jsii assembly, which means you must run pnpm compile before pnpm build when struct definitions change. CI workflows are patched in .projenrc.ts to insert this compile step.

Architecture

Root Constructs (user-facing entry points)

src/root-constructs/ — the four deployment patterns users choose from:

  • NextjsGlobalFunctions — CloudFront + Lambda
  • NextjsGlobalContainers — CloudFront + Fargate
  • NextjsRegionalContainers — ALB + Fargate (no CloudFront, GovCloud compatible)
  • NextjsRegionalFunctions — Lambda Function URLs (no CloudFront, GovCloud compatible)

Each root construct composes lower-level constructs (NextjsBuild, NextjsFunctions/NextjsContainers, NextjsDistribution, NextjsCache, NextjsStaticAssets, NextjsPostDeploy).

Runtime Code (bundled with esbuild, not compiled by JSII)

  • src/adapter/adapter.mts — Next.js adapter (ESM, runs in Lambda/Fargate at request time)
  • src/adapter/cache-handler.ts — Next.js cache handler orchestrating S3 + DynamoDB + memory cache
  • src/nextjs-build/patch-fetch.js — injected into Next.js build to patch fetch behavior

These are bundled to lib/adapter/*.mjs and lib/nextjs-build/patch-fetch.js. They use devDependencies at build time (AWS SDK, etc.) that are available at runtime in Lambda/Fargate.

Generated Structs

src/generated-structs/ — auto-generated by projen via @mrgrain/jsii-struct-builder. These create "all optional" versions of CDK/construct props for the overrides pattern. Do not hand-edit.

Lambdas

src/lambdas/post-deploy/ — custom resource Lambda for post-deployment tasks (CloudFront invalidation, cache seeding).

Test Files

Tests live alongside source (src/**/*.test.ts) for adapter/cache code. CDK construct snapshot/assertion tests would go in test/.

Key Conventions

  • JSII constraints: Source in src/ must be JSII-compatible TypeScript (no mapped types like Partial<T>, no enums re-export, etc.). Runtime-only code (adapter, cache-handler) is bundled separately and exempt.
  • Overrides pattern: Every construct exposes an overrides prop that passes raw CDK props through, allowing users to customize underlying resources.
  • Conventional commits: PRs require semantic title prefixes: feat, fix, chore, refactor, perf, docs, style, test, build, ci.
  • Releasable commits: Only feat, fix, chore, refactor, perf trigger a release.
  • Package manager: pnpm (v10). Use pnpm dlx projen <task> or the package.json script shortcuts.
  • Node version: 24 (Lambda runtime target).
  • ESLint: import ordering is enforced (builtin → external, alphabetical). Prettier is integrated.