Next.js static export or SSR: choose before deploying

Choose by what the page needs when a visitor arrives

Start with the feature that changes per request. A public page generated from a known list of content can be built ahead of time. A page that reads an incoming private session cookie to render personalized HTML needs a runtime. A static frontend may call an existing external API from the browser, but that API must handle authorization and private operations itself.

Do not downgrade a working application just to match a hosting label without reviewing its dependencies, security updates and behavior. Either produce a legitimate static export or use a host that supports the runtime your app needs. For supported SSR, validate the exact adapter limits in the product docs before changing the project.

Check the features that can prevent export

This is a decision checklist, not a complete compatibility matrix for all Next versions. The current official static-export guide documents unsupported features. The example below pins the version it actually ran rather than silently tracking latest.

Build a complete small export

Download the Next.js static-export fixture, extract it and open shipvela-next-export-fixture. It contains a home page and one known note route. The recorded local test used Next.js 16.3.7, React 19.3.0, Node 22.20.0 and npm 10.9.3. These versions describe the local compiler, not Shipvela SSR compatibility. Use a currently supported Node release that satisfies your own project’s engines.

cd shipvela-next-export-fixture
npm ci --ignore-scripts
npm run build

The build script is next build --webpack. The fixture disables persistent webpack caching to keep the local lab small; that is not a hosting requirement. It uses no remote fonts, external data fetching, database or secret values. Its important configuration is:

export default {
  output: 'export',
  trailingSlash: true,
  images: { unoptimized: true },
};

output: export requests a static artifact. trailingSlash emits nested index.html files that a conventional static server can address. images.unoptimized avoids assuming a running image-optimization endpoint; you still need sensible image dimensions and file sizes. Do not add these settings to a large application without auditing its server-dependent features.

export function generateStaticParams() {
  return [{ slug: 'welcome' }];
}
export const dynamicParams = false;

export default async function Note({ params }) {
  const { slug } = await params;
  return <main><h1>Note: {slug}</h1></main>;
}

Only welcome is included in the route list. That is intentional: a route pattern in source does not create HTML for every possible slug. For a real content collection, derive the list from approved build-time data and confirm that every intended page appears in the artifact.

Inspect the artifact before publishing

node -e "const fs=require('node:fs'); for(const p of ['out/index.html','out/notes/welcome/index.html','out/404.html']) console.log(p, fs.existsSync(p));"

The recorded build produced all three files. The nested page already contained its Note: welcome heading before client JavaScript ran. The out directory also contained _next assets and navigation payloads. Keep those generated files together. Uploading .next, the source app folder or only the HTML pages omits part of the static output.

Do not use --spa for this example: replacing every route request with the home document discards the distinction between separately generated pages. The lab’s server resolves a directory to its index.html and returns 404 for a missing route. A local result does not prove the production host’s slash redirects or custom 404 presentation.

Test direct requests as well as links

node scripts/serve.mjs out strict 4176

Open http://127.0.0.1:4176, follow Read the welcome note and refresh the note URL. Then paste /notes/welcome/ into a fresh tab. All should show the same page. The fixture includes the same small static test server used by the runtime lab; it starts no Next server and executes no server-side application code.

curl -i http://127.0.0.1:4176/notes/welcome/
curl -i http://127.0.0.1:4176/notes/unlisted/

A useful acceptance test also disables JavaScript and inspects the exported page’s meaningful content. Client-side interactivity will naturally stop, but the heading and text should still exist for this example. If a real page renders only an empty shell, investigate its rendering design rather than assuming every static export contains all useful content.

The automated local check verifies route files, HTTP responses and the request-dependent failure below. It does not certify Shipvela CDN behavior, external API authorization, all browsers or a real cloud deployment.

Observe a request-only feature fail the static build

A small negative test helps distinguish “can compile React” from “can export this application.” The test temporarily adds a page that reads an incoming cookie and then runs the same export build. That requires information which does not exist for a future visitor at build time.

import { cookies } from 'next/headers';
export default async function Account() {
  const store = await cookies();
  return <p>{store.get('demo_session')?.value || 'No session'}</p>;
}

The test expects a non-zero build result. A successful export must not pretend to personalize this HTML for an incoming user. The test removes the temporary account page and rebuilds the original fixture. It does not create a real session or inspect anyone’s cookies. Consult Next.js cookies when designing a runtime page.

For an app that already has a secure external API, a browser may request authenticated data after load. That is a separate architecture with its own loading, error, authorization and SEO implications. Moving code into a Client Component does not make private keys safe or replace server authorization.

Publish the generated folder through the static path

Once the local checks pass, use the existing CLI setup and login instructions. Check whether shipvela.json already links the directory to a project. For a new static-upload project, the publishing procedure is:

npm run build
shipvela publish out --name field-notes --json

For later updates to that linked project, use shipvela publish out --json. The CLI uploads the prebuilt archive; it does not run Next.js for visitors. Wait for the specific job’s success, then test the returned URL, the nested route and an unknown URL before connecting a domain.

Do not substitute a GitHub import of this Next 16 fixture and expect the same path. Current Shipvela GitHub Next SSR admission is bounded to Next 12–15 on paid plans. This example uses local compilation followed by static file upload. It neither changes pricing nor expands runtime support.

Recover from common export failures

Keep the complete source and lockfile so the export can be rebuilt. A successful static build is the start of release acceptance; use the launch checklist for content, domain, accessibility and operational checks before sharing the final URL.