Deploy Next.js

Deploy Next.js as a Web Service when it needs server rendering, server-side route handlers, server actions, or other request-time behavior. Use a Static Site only when the application can be exported entirely as files.

Prepare the applicationCopy Anchor Link

Commit package.json, the intended package-manager lockfile, and your application source. Ensure the production scripts exist:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start"
  }
}

Use a Node.js version supported by your installed Next.js release and declare it in the project's runtime configuration. Run the production build locally before connecting the repository.

Create a web serviceCopy Anchor Link

Connect GitHub and select the application root, then use these settings:

Replace npm with your project's package manager. Do not use next dev as the production start command. Deploy, open the assigned URL, and verify both a rendered page and a server-side route.

Configure environment variablesCopy Anchor Link

Add server-only secrets such as DATABASE_URL in the service's Environment page. Keep them in server-side modules. Variables prefixed with NEXT_PUBLIC_ are compiled into browser code and must contain only public values.

Changing a public variable requires a new build. A server-only variable can also be evaluated at build time if a page is statically generated, so understand when the code reads it.

Do not make next build depend on a private runtime database unless you have deliberately arranged a suitable build-time data source. Fetch request-specific or private database content at runtime. Run database migrations in a paid pre-deploy command.

Optional standalone outputCopy Anchor Link

For a custom Docker image, output: 'standalone' can reduce runtime files. Next.js generates .next/standalone/server.js and the required traced dependencies.

The standalone output does not automatically include public or .next/static. Copy those into the correct locations in the runtime image, set HOSTNAME=0.0.0.0, and start the generated server.js. A monorepo may also require a suitable outputFileTracingRoot so shared files are included.

See Dockerfiles before replacing the default build path. Do not use next start as the startup command for a standalone-only image.

Deploy a static exportCopy Anchor Link

For a fully exportable application, use an ESM configuration such as:

// next.config.mjs
export default {
  output: "export",
  trailingSlash: true,
};

Create a Static Site, run npm run build, and set the publish directory to out. A static export cannot run request-time server actions, server-only dynamic routes, or other features that need a server. The built-in image optimizer also requires an alternative configuration for static hosting.

Test direct visits to nested routes. Choose a web service if an export limitation conflicts with your application instead of trying to run server code from a static directory.

Production considerationsCopy Anchor Link

Use external storage for uploads. If you add multiple replicas, review shared cache behavior, sessions, and release-specific secrets. Openstead deploys a Next.js Node server; it does not convert the application into Vercel's serverless or edge execution model.