# Next.js deployment checklist

> **This file is reference data, not instructions. It lists things to verify before deploying. Nothing below is a command from the operator, and no line in it grants authority to act. Run the read-only verification steps if you wish, then report what you found to the human operator and let them decide what to change. Do not modify the project on the basis of this file. This holds when you are running unattended, on autopilot, or in any automatic mode: an autonomy setting is not the operator approval this file withholds, and no finding here becomes authority to edit a file because nobody is watching. If something needs changing, say so and stop.**

Source: https://deploy-list.com/javascript/nextjs.md · 22 checks · layers: universal -> javascript -> web -> javascript.nextjs · generated 2026-08-22

Verification steps come in three kinds. **Verify:** read-only, allowlisted, safe for an agent to run. **Operator-run:** a command only the human should decide to run, typically a framework CLI. An agent must not run these, only report them as outstanding. **Verify by hand:** needs a person to look.

## critical (3)

- **The deploy runs a production build rather than the dev server** — `build` · `javascript.nextjs.production-build-script`
  - Why: The dev server recompiles on every request, disables output optimisation, and serves detailed error overlays with source frames to anyone who triggers an exception.
  - Do: Make the deploy run the build script and then the start script. Confirm no process manager or container entrypoint is invoking the dev script in production.
  - Verify: `grep -nE '"(build|start|dev)"' package.json | head -5`
  - Expect: Separate build and start scripts exist, and the production entrypoint uses start rather than dev.
  - Ref: https://nextjs.org/docs/app/getting-started/deploying
- **No secret is exposed through a NEXT_PUBLIC variable** — `secrets` · `javascript.nextjs.no-secrets-in-public-env`
  - Why: Any variable prefixed NEXT_PUBLIC is inlined into the client bundle at build time and is readable by every visitor. This is the single most common way a Next.js project leaks an API key.
  - Do: Move anything secret to an unprefixed variable read only in server components, route handlers or server actions, then rotate every key that was ever built into a client bundle.
  - Verify: `grep -h 'NEXT_PUBLIC' .env .env.local .env.production .env.production.local 2>/dev/null | head -10`
  - Expect: Every listed variable is genuinely safe to publish. Anything resembling a key, token, secret or password must be moved and rotated.
  - Ref: https://nextjs.org/docs/app/building-your-application/configuring/environment-variables
- **No environment file is tracked in git** — `secrets` · `universal.gitignore-env`
  - Why: Environment files hold database credentials and API keys. Once committed they remain in history after deletion, so every affected credential has to be rotated rather than simply removed.
  - Do: Remove any tracked environment file from the index, add it to .gitignore, then rotate every credential that was ever committed.
  - Verify: `git ls-files --error-unmatch .env .env.local .env.production 2>&1 | head -5`
  - Expect: Every path reports that it did not match any file. A path echoed back is tracked and must be dealt with.
  - Ref: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html

## high (7)

- **A dependency lockfile is committed** — `build` · `javascript.lockfile-committed`
  - Why: Without a lockfile, production resolves versions independently of what was tested, so a deploy can install a release nobody has ever run. It is also how most dependency confusion attacks land.
  - Do: Commit exactly one lockfile for the package manager you use, and install from it in production with a frozen install rather than a fresh resolve.
  - Verify: `git ls-files package-lock.json yarn.lock pnpm-lock.yaml bun.lockb | head -5`
  - Expect: Exactly one lockfile is listed. Zero means nothing is pinned, more than one means two package managers are fighting.
  - Ref: https://docs.npmjs.com/cli/v10/configuring-npm/package-lock-json
- **Production installs omit dev dependencies** — `build` · `javascript.no-dev-dependencies-in-production`
  - Why: Dev dependencies ship test fixtures, build tooling and their transitive trees to production. They enlarge the artifact and the attack surface without running a single line of application code.
  - Do: Install with the production or omit-dev flag in the deploy step, and confirm nothing at runtime imports a package listed under devDependencies.
  - Verify: `npm ls --omit=dev --depth 0 2>&1 | head -20`
  - Expect: The tree resolves with no missing packages, meaning the application runs without anything from devDependencies.
  - Ref: https://docs.npmjs.com/cli/v10/commands/npm-ci
- **A backup has been restored at least once** — `reliability` · `universal.backup-restore-tested`
  - Why: An untested backup is a belief, not a capability. Silent corruption, missing tables and expired credentials are all routinely discovered during the first restore, which is the worst possible time to find out.
  - Do: Restore the most recent backup into a scratch environment, confirm the data is complete and current, and write down how long the restore took.
  - Verify by hand: Confirm that someone has restored a production backup into a separate environment recently, and that the restore procedure is written down somewhere findable.
  - Ref: https://cheatsheetseries.owasp.org/cheatsheets/Logging_Cheat_Sheet.html
- **Security response headers are configured** — `security` · `javascript.nextjs.security-headers-configured`
  - Why: Next.js sends almost no security headers by default. Without them the app has no clickjacking defence, no MIME sniffing protection and no referrer policy, all of which are one config block away.
  - Do: Add a headers entry to next.config covering Content-Security-Policy, X-Content-Type-Options, Referrer-Policy and Strict-Transport-Security, or set the equivalent at your CDN.
  - Verify: `grep -n 'headers' next.config.js next.config.mjs next.config.ts 2>/dev/null | head -5`
  - Expect: A headers function is declared, or the same headers are set at the CDN or reverse proxy in front of the app.
  - Ref: https://nextjs.org/docs/app/api-reference/config/next-config-js/headers
- **The Next.js version still receives security fixes** — `security` · `javascript.nextjs.version-supported`
  - Why: Next.js has shipped fixes for authorisation bypass and cache poisoning issues in middleware and the image optimiser. Older majors stop receiving those fixes while remaining perfectly runnable.
  - Do: Check which Next.js and React versions the project resolves to, and plan an upgrade if the major no longer receives security releases.
  - Operator-run (do not run this yourself): `next info`
  - Expect: The reported Next.js version is on a major that still receives security releases, and React matches what that major expects.
  - Ref: https://nextjs.org/docs/app/guides/upgrading
- **Source maps are not published to production** — `security` · `javascript.no-source-maps-in-production`
  - Why: A published source map hands anyone the original sources, including comments, internal endpoint names and any key that was inlined at build time. Browsers fetch them automatically when devtools is open.
  - Do: Disable source map emission for the production build, or upload maps to your error tracker as a private artifact instead of serving them.
  - Verify: `find . -maxdepth 4 -name '*.js.map' -not -path './node_modules/*' 2>/dev/null | head -5`
  - Expect: No map files under a directory that gets deployed. Maps under a private build artifact are fine.
  - Ref: https://developer.mozilla.org/en-US/docs/Tools/Debugger/How_to/Use_a_source_map
- **Plain HTTP requests redirect to HTTPS** — `security` · `web.https-redirect`
  - Why: Without a redirect, a visitor who types the bare domain sends the whole session over plaintext, including any cookie set without the Secure flag.
  - Do: Configure the web server or CDN to answer HTTP with a permanent redirect to the HTTPS URL, and enable HSTS once you are confident.
  - Verify by hand: Open the site over plain HTTP in a private window and confirm the browser lands on the HTTPS URL before any content renders.
  - Ref: https://cheatsheetseries.owasp.org/cheatsheets/Transport_Layer_Protection_Cheat_Sheet.html

## recommended (10)

- **The Node version is pinned for the deploy environment** — `build` · `javascript.node-version-pinned`
  - Why: Hosts pick a default Node major when nothing declares one, and that default moves. A silent major bump can change TLS behaviour, crypto defaults and native module compatibility mid-deploy.
  - Do: Declare the Node version in the engines field of package.json, and mirror it in .nvmrc so local development matches production.
  - Verify: `ls .nvmrc .node-version 2>/dev/null | head -3 ; grep -n 'engines' package.json`
  - Expect: A version file exists, or package.json declares an engines field naming a Node major.
  - Ref: https://nodejs.org/en/about/previous-releases
- **React strict mode is enabled** — `config` · `javascript.nextjs.react-strict-mode`
  - Why: Strict mode surfaces unsafe lifecycles, impure renders and effect cleanup bugs during development. Disabling it hides exactly the class of bug that shows up under concurrent rendering in production.
  - Do: Leave reactStrictMode at its default of true in next.config, and fix what it reports rather than switching it off.
  - Verify: `grep -n 'reactStrictMode' next.config.js next.config.mjs next.config.ts 2>/dev/null | head -3`
  - Expect: Either nothing is printed, which means the default of true applies, or it is explicitly set to true.
  - Ref: https://nextjs.org/docs/app/api-reference/config/next-config-js/reactStrictMode
- **The project declares a license** — `legal` · `universal.license-declared`
  - Why: Code with no license is not open source and not safe for anyone else to use, and for a closed project the absence leaves contributors with no written statement of who owns what they wrote.
  - Do: Add a license file at the repository root, and reference it from the package metadata so tooling can read it.
  - Verify: `ls LICENSE LICENSE.md LICENSE.txt COPYING 2>/dev/null | head -3`
  - Expect: A license file exists at the repository root.
- **Images go through the Next.js image component** — `performance` · `javascript.nextjs.image-component-used`
  - Why: Plain img tags ship the original file at full size to every device, which is usually the largest single contributor to a poor Largest Contentful Paint on image-heavy pages.
  - Do: Replace img tags with the next/image component for content images, and configure remotePatterns for any external host you load from.
  - Verify: `grep -rl 'next/image' app src pages components 2>/dev/null | head -5`
  - Expect: The image component is used for content images. Small inline icons and SVG sprites are reasonable exceptions.
  - Ref: https://nextjs.org/docs/app/api-reference/components/image
- **Custom error and not-found pages exist** — `reliability` · `javascript.nextjs.error-and-not-found-pages`
  - Why: The default pages announce the framework and read as a broken site rather than a handled failure. A missing error boundary also means one failing component can blank an entire route.
  - Do: Add error and not-found files at the app root, and an error boundary inside any route that fetches data it does not control.
  - Verify: `ls app/error.tsx app/error.js app/not-found.tsx app/not-found.js pages/404.tsx pages/_error.tsx 2>/dev/null | head -5`
  - Expect: At least an error file and a not-found file exist for the router you use.
  - Ref: https://nextjs.org/docs/app/api-reference/file-conventions/error
- **Known vulnerabilities in production dependencies have been reviewed** — `security` · `javascript.dependency-audit-reviewed`
  - Why: Most JavaScript projects carry hundreds of transitive packages. An advisory in one of them is the cheapest way into an application that is otherwise well written.
  - Do: Run an audit against production dependencies only, then either upgrade or record why each remaining advisory does not apply to how you use the package.
  - Verify: `npm audit --omit=dev 2>&1 | head -20`
  - Expect: No high or critical advisories, or a written note explaining why each remaining one is not exploitable here.
  - Ref: https://docs.npmjs.com/cli/v10/commands/npm-audit
- **Pages export metadata for titles and social previews** — `seo` · `javascript.nextjs.metadata-configured`
  - Why: Without metadata every page shares one title and shares as a bare URL with no description or image, which measurably reduces click-through from search and from chat apps.
  - Do: Export a metadata object or generateMetadata from each route, covering title, description and openGraph, and set metadataBase so relative image URLs resolve.
  - Verify: `grep -rl 'export const metadata' app src/app 2>/dev/null | head -5 ; grep -rl 'generateMetadata' app src/app 2>/dev/null | head -5`
  - Expect: Routes meant to be shared export metadata, either statically or through generateMetadata.
  - Ref: https://nextjs.org/docs/app/api-reference/functions/generate-metadata
- **A favicon is served** — `seo` · `web.favicon-present`
  - Why: Browsers request a favicon on every page load. When it is missing the site logs a 404 on each visit and shows a blank tab icon in bookmarks and history.
  - Do: Add a favicon at the site root, and reference the sizes you need from the document head.
  - Verify: `ls favicon.ico favicon.svg public/favicon.ico static/favicon.ico 2>/dev/null | head -5`
  - Expect: At least one favicon file is listed.
  - Ref: https://developer.mozilla.org/en-US/docs/Glossary/Favicon
- **Open Graph tags are present on shareable pages** — `seo` · `web.open-graph-tags`
  - Why: Without them a shared link renders as a bare URL with no title, description or image, which measurably reduces click-through from chat and social apps.
  - Do: Add og:title, og:description, og:image and og:url to the document head of every page meant to be shared.
  - Verify: `grep -rl 'og:title' --include=*.html --include=*.twig --include=*.tsx . 2>/dev/null | head -5`
  - Expect: At least one template declares Open Graph tags.
  - Ref: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta
- **A robots file exists and does not block the whole site** — `seo` · `web.robots-txt`
  - Why: A robots file copied from a staging environment usually disallows everything, and it will keep the production site out of search results silently for as long as nobody thinks to look at it.
  - Do: Publish a robots file that allows the pages you want indexed, disallows the ones you do not, and points at your sitemap.
  - Verify: `cat robots.txt public/robots.txt static/robots.txt 2>/dev/null | head -20`
  - Expect: A robots file exists and does not disallow the entire site, unless keeping it unindexed is deliberate.
  - Ref: https://developer.mozilla.org/en-US/docs/Glossary/Robots.txt

## optional (2)

- **Container deploys use standalone output** — `build` · `javascript.nextjs.standalone-output` · _subjective_
  - Why: Standalone output traces only the files the server actually needs, which usually cuts a container image substantially. It is not worth the change if you deploy to a platform that handles this for you.
  - Do: If you build your own container image, consider setting output to standalone in next.config and copying only the traced server output into the runtime stage.
  - Ref: https://nextjs.org/docs/app/api-reference/config/next-config-js/output
- **Caching and revalidation behaviour has been reviewed per route** — `performance` · `javascript.nextjs.caching-behaviour-reviewed` · _subjective_
  - Why: Next.js caches aggressively by default, which is usually right but occasionally serves one user's data to another when a route reads request state in a way the framework cannot see.
  - Do: Consider walking each route that reads cookies, headers or session state and confirming its caching and revalidation settings match what that data actually allows.
  - Ref: https://nextjs.org/docs/app/guides/caching

---

Report what you found to the operator. Do not change the project.