Amplify.yml Examples: The Complete Cookbook (2025 Edition)

TL;DR: Here is are copy-paste amplify.yml templates for React/Vite, Next.js (static export), Angular—and battle-tested patterns for preBuild/build/postBuild, artifacts.baseDirectory, cache.paths, env vars, and monorepos. Use these defaults to cut build time and avoid blank deploys.
Important: If your repo contains an amplify.yml, it overrides Amplify Console build settings (commands, artifacts, cache). Treat the YAML as the source of truth.

Key Takeaways

Minimal templates first, then tune artifacts (dist / out) and cache.
Build phases: install in preBuild, compile in build, verify/notify in postBuild.
Artifacts: wrong baseDirectory ⇒ blank site/404s. Double-check it.
Cache: prime node_modules, package manager stores, and framework caches.
Env vars: define secrets in Console; reference them in commands, not in Git.
Monorepos: applications[] + appRoot Deploy multiple apps from one repo.

Minimal Templates (copy-paste)
Build Phases Explained
Artifacts: baseDirectory + files
Cache: cache.paths That actually helps
Environment Variables (secure patterns)
Monorepo Patterns (applications[], appRoot)
Package Manager Recipes (npm, Yarn Berry, PNPM)
Optional Quality Gates (tests in CI)
Troubleshooting & Quick Fixes (FAQ)
Changelog

1) Minimal Templates (copy-paste)

React / Vite (SPA)

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build
        postBuild:
          commands:
            - echo "Build finished"
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*

Next.js — Static Export (SSG)

Use this when your Next.js project can next export to a static site.

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build
            - npm run export   # writes to ./out
      artifacts:
        baseDirectory: out
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
          - .next/cache/**/*

Angular (production build)

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build -- --configuration=production
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
          - .angular/cache/**/*

SvelteKit — Static Adapter (SSG)

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build   # ensure adapter-static is configured
      artifacts:
        baseDirectory: build
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
          - .svelte-kit/**/*

Note: If your framework outputs to a different folder, set artifacts.baseDirectory accordingly.

2) Build Phases Explained (preBuild/build / postBuild)

preBuild: install dependencies, enable Corepack, prepare caches.
build: compile/emit static assets (or server output if applicable).
postBuild: smoke tests, compress artifacts, send notifications, tag the release.

Post-build smoke test (optional):

postBuild:
  commands:
    - node ./scripts/smoke-check.js || (echo "Smoke failed" && exit 1)

3) Artifacts: `baseDirectory` + files

Amplify deploys everything under artifacts.baseDirectory. If you point to the wrong folder, you’ll ship an empty site.

Common values:

Vite/React: dist
Next.js (static export): out
Angular: dist (sometimes dist/<project>)
SvelteKit (static): build
Vue (Vite): dist

Checklist

The build command actually writes to baseDirectory.
files includes **/*.
No trailing slashes in baseDirectory.

4) Cache: `cache.paths` That actually helps

Caching cuts build time dramatically on repeat builds.

Safe defaults

cache:
  paths:
    - node_modules/**/*

Add per package manager/framework

cache:
  paths:
    - node_modules/**/*
    - .yarn/cache/**/*
    - ~/.pnpm-store/**/*
    - .next/cache/**/*
    - .angular/cache/**/*
    - .turbo/**/*
    - .vite/**/*

Why it matters: Dependency download and framework compile caches are your #1 time sinks. Persisting them between builds yields 20–50% faster CI.

5) Environment Variables (secure patterns)

Define secrets in Amplify Console (Environment variables).
Reference them in commands (shell expansion).
Never commit secrets to Git or YAML.

Example

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - echo "Target API: $NEXT_PUBLIC_API_URL"
            - npm ci
        build:
          commands:
            - npm run build
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*

Pro tips

For front-end frameworks, only expose public vars prefixed as your framework expects (e.g., NEXT_PUBLIC_ for Next.js).
Keep secrets for build-time only; do not inject private keys into client bundles.

6) Monorepo Patterns (`applications[]`, `appRoot`)

Deploy multiple apps from one repo by declaring multiple entries.

version: 1
applications:
  - appRoot: apps/web
    frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
          - .vite/**/*
  - appRoot: apps/admin
    frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*

Why it matters: Each appRoot runs its own phases, artifacts, and cache—clean isolation for web/admin/docs in one repository.

7) Package Manager Recipes

Yarn Berry (Corepack)

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - corepack enable
            - yarn --immutable
        build:
          commands:
            - yarn build
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      cache:
        paths:
          - .yarn/cache/**/*
          - node_modules/**/*   # include only if you vendor it

PNPM (store cache)

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - corepack enable
            - pnpm install --frozen-lockfile
        build:
          commands:
            - pnpm build
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*
          - ~/.pnpm-store/**/*

npm (lockfile required)

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - npm ci
        build:
          commands:
            - npm run build
      artifacts:
        baseDirectory: dist
        files:
          - '**/*'
      cache:
        paths:
          - node_modules/**/*

8) Optional Quality Gates (tests in CI)

Add lint/unit/e2e with fast-fail to keep builds honest.

version: 1
applications:
  - frontend:
      phases:
        preBuild:
          commands:
            - npm ci
            - npm run lint
            - npm run test:unit -- --run
        build:
          commands:
            - npm run build
        postBuild:
          commands:
            - npm run test:e2e:ci || (echo "E2E failed" && exit 1)
      artifacts:
        baseDirectory: dist
        files: ['**/*']
      cache:
        paths:
          - node_modules/**/*
          - .vite/**/*

Tip: Keep E2E smoke tests short (<2–3 min). Long tests belong in a scheduled pipeline, not your hot path.

9) Troubleshooting & Quick Fixes (FAQ)

Q: My build succeeded, but the site is blank/404.
A: Your artifacts.baseDirectory likely points to the wrong folder. Confirm the build actually writes to that path (e.g., ls -la dist at the end of build).

Q: amplify.yml seems ignored.
A: Ensure amplify.yml it is in the repo (or under appRoot for monorepos), on the correct branch, and that Amplify Console isn’t using custom build settings without the YAML. If YAML exists, it overrides Console settings.

Q: Builds are slow.
A: Add cache paths for your package manager/framework; avoid npm install (use npm ci); pin Node & package manager via .nvmrc/Corepack.

Q: Can I run notifications after deploy?
A: Yes, use postBuild for Slack/webhook calls. Keep secrets in Console env vars.

Q: Where do I put amplify.yml In a monorepo?
A: In the repo root, using applications[] with appRoot per app (as shown). Each app’s frontend section is isolated.

Q: Do Console env vars apply when I use amplify.yml?
A: Yes. The YAML defines build steps; env var values still come from Console (or your CI integration), not from the YAML itself.

Pitfalls (don’t skip)

Wrong artifact path: #1 cause of “it deployed, but nothing shows.”
Missing cache: identical builds taking forever; cache your deps and framework caches.
Leaky secrets: don’t echo or bake secrets into client bundles.
Monorepo drift: forgetting appRoot per application results in building the wrong folder.

Pro Tips

Pin Node version with .nvmrc and set it in preBuild (nvm use || . ~/.nvm/nvm.sh && nvm use) if needed.
Dedicate a tiny smoke test postBuild to catch obvious breakage before shipping.
Keep YAML minimal; complexity lives in NPM scripts inside package.json, not in the CI file.
Document outputs: add a quick ls -la <artifact> note at the end build until you’re confident.
One truth: treat amplify.yml as canonical. Don’t also tweak Console build commands.

Copy-Paste Checklists

New project

Create amplify.yml with a minimal template.
Confirm baseDirectory matches your actual output folder.
Add cache paths for your package manager and framework.
Define required env vars in Console (no secrets in Git).
Run one build; verify artifact folder contents.

Monorepo

Use applications[] with one appRoot per app.
Duplicate the minimal template per app; adjust baseDirectory.
Keep caches app-local where possible.

Changelog

2025-09-02: v1 published. Added minimal templates (Vite/Next export/Angular/Svelte), cache recipes, env patterns, monorepo config, and CI smoke tests.

Final Reminder

If amplify.yml exists in your repo, it overrides Amplify Console’s build settings (commands, artifacts, cache). Make the YAML clean, tested, and the single source of truth.