Next.js

Next.js is the framework Nitroship supports natively (managed). With no adapter to configure, static pages, prerendering and ISR, server routes, API routes, middleware, and image optimization all work. You do not need output: 'standalone' either.

RequirementsCopy Anchor Link

• Next.js 16.2 or later. package.json at the deployment root must depend on next; the remote builder installs dependencies and then checks the version actually installed.
• A compute region. This is where your server runs. There is no default, so pick one under Configuration below.

DeployCopy Anchor Link

curl -fsSL https://nitroship.co/install.sh | bash
ntro login

ntro apps create my-next-app
ntro deploy . --prod

The remote builder installs dependencies, runs next build, and deploys static files and server code separately. To build on your own machine instead, install dependencies first and add --local:

ntro deploy . --prod --local

When it finishes, open a static page and a server route at the URL the CLI printed. The repository's examples/hello-next has SSG, SSR, ISR, and API route examples in one app.

ConfigurationCopy Anchor Link

Set the server region and size in whichever place you prefer:

• App Settings > Compute in the console
• nitroship.json at the deployment root

{
  "compute": {
    "regions": ["kr-icn"],
    "tier": "standard"
  }
}

When both are set, nitroship.json wins field by field. For example, if the file sets only regions, the region comes from the file and the tier from the console. All fields and defaults are listed under CLI configuration > Compute settings.

To change the build command, use build.command. build.outputDirectory is ignored for Next.js.

Public SSR response cachingCopy Anchor Link

For public dynamic routes, set CDN-Cache-Control with next.config's headers() or middleware rather than relying on Next.js's generated Cache-Control. The optional Edge response cache is separate from prerender/ISR and requires operator enablement. Do not cache personalized responses; Set-Cookie, private in the chosen policy, and Vary: Cookie prevent storage. See Cache invalidation for header precedence, limits, tags, and invalidate versus delete. The repository's examples/hello-ssr-cache demonstrates render timestamps and host-specific cached output.

The Edge forwards these evaluated configuration headers to compute even though Next.js runs in minimal mode. A function's policy header replaces the configured value for the same header name; Vary and cache tags are combined instead. A configured Vary: Cookie therefore still prevents caching when Next.js adds its own Vary fields. The 128-tag limit applies to the combined tags. The selected configuration headers have an 8 KiB encoded transport limit; oversized configuration is ignored and logged, so do not rely on it to define a cache policy.

Good to knowCopy Anchor Link

• Images: the default Next.js image loader configuration is picked up automatically. Tune image options only in next.config; do not add an images block to nitroship.json.
• Locale domains: i18n.domains (one domain per language) is not supported. Use locale paths such as /ko and /en.

Advanced: readiness checks and warm-upCopy Anchor Link

You can skip this in everyday use. Read it if your app does work at startup or you want to tune cold starts.

Background: seed snapshotsCopy Anchor Link

To start new instances quickly when traffic grows, Nitroship boots your app once, saves that running state as a snapshot (seed), and restores from it. A warm-up request renders your home page once before the snapshot.

The health check confirms the app can take requests. It runs on a fresh start (cold start), when creating a seed, when reviving a paused instance (checkpoint restore), and when a restore fails and the instance starts fresh instead. Restoring an existing seed only quickly checks that the port accepts connections.

Health check: /__nitroship/healthCopy Anchor Link

Newly built Next.js apps get a /__nitroship/health route added by Nitroship, and the health check uses it. Nothing to configure.

• It returns 503 until the Next.js server is prepared (NextServer.prepare()) and route preloading has finished, then 200. Both responses have an empty body.
• Preloading only imports each route file. It does not render pages or run route handlers or middleware.

Turn preloading off: for comparison or troubleshooting, set the environment variable NITROSHIP_NEXT_PRELOAD=0 and deploy again. The health check then waits only for prepare(). 1 or no value keeps it on.

Use your own endpoint: to check a route of your own, set it in nitroship.json. You must implement that route yourself; /__nitroship/health stays reserved after the change.

{"compute": {"healthPath": "/api/healthz"}}

Whichever path is used, the health check sends it a GET request:

• 2xx, 3xx, and 404 responses count as ready.
• Each attempt waits up to 2 seconds for response headers and is retried until it passes. The overall limit is 30 seconds.

Warm-up request: GET /Copy Anchor Link

When creating a seed snapshot, Nitroship sends a single GET / request to your app right after the health check passes. This runs your home page's rendering code once ahead of time. Nitroship reads the whole response before taking the snapshot.

• The request carries User-Agent: nitroship-seed-warmup and x-nitroship-warmup: 1.
• Unlike the health check, it really renders the page and runs middleware. If that code has side effects, such as recording analytics, filter this request out using the headers above.
• It is best effort within a time limit; errors or timeouts never fail the deployment.
• It is not sent on snapshot restore or for real visitor requests. Changing compute.healthPath does not change the warm-up path; it stays /.

Existing deployments are not affectedCopy Anchor Link

The health path and warm-up are recorded in the deployment at build time. Deployments built before these features keep their original health path (usually /) and get no warm-up. Redeploy, Apply now, promote, and rollback all keep the recorded values, so you need to rebuild to get the new behavior. Apps other than Next.js never receive the warm-up request.

Related guidesCopy Anchor Link

Image optimization · Cache invalidation · Environment variables · Migrate from Vercel