· By John Kavanagh

Checking What a Standalone Next.js Deployment Contains

Photograph of books and magazines stacked beside a wooden shelf and coloured glass panels.
Image by John Salvino, licensed from Unsplash.

A Next.js build can finish successfully without giving you a directory which works when copied somewhere else. That sounds rather unfair until we separate what the build has checked from what we intend to deploy.

The source checkout contains our application, its dependencies, public assets, and probably a few files which sit outside the application's own directory. Running the production server there leaves all of them conveniently within reach. A smaller deployment may have fewer conveniences.

Next's standalone output helps us produce that smaller deployment. I still want to run the result on its own before trusting it. For this example, that means a workshop catalogue which reads shared JSON files at request time, an ordinary public image, and a button which needs browser JavaScript. Each gives us something concrete to lose.


Follow What the Server Actually Reads

In Next 12.3, I enable standalone output with:

module.exports = {
  output: 'standalone',
};

As described in Next's versioned output tracing documentation, Next traces server dependencies during the build, examining imports, require calls, and filesystem access. The resulting .nft.json files list paths relative to each trace file. Standalone output uses those traces to copy the necessary files into .next/standalone, including a generated server.js and selected dependencies.

That isn't the same as copying everything beside the source file. A JSON file imported into a component and a JSON file opened by fs.readFile() during a request can reach the output by different routes.

My catalogue uses getServerSideProps, so a successful build hasn't actually served its request‑time data. As I explain in my comparison of getStaticProps and getServerSideProps, when the data is read changes which failures a build can expose.

The first read has a path the tracer can inspect:

const labels = JSON.parse(
  await readFile(
    path.join(process.cwd(), '../../shared/labels.json'),
    'utf8',
  ),
);

Here process.cwd() is the application directory. That assumption must remain true in the deployment. Copying a file is only useful if the running process looks for it in the right place.


Let the Trace See the Workspace

My small workspace puts the application in apps/web and its data in shared. Dependencies are installed at the workspace root. The default tracing boundary in this version is the application directory, which leaves those neighbouring files outside it.

For Next 12.3, I set the experimental tracing root explicitly:

const path = require('path');

module.exports = {
  output: 'standalone',
  experimental: {
    outputFileTracingRoot: path.resolve(__dirname, '../..'),
  },
};

The wider root allows traced files from the workspace to be included. It doesn't mean "copy this entire workspace". The shared label file is now available to the trace, alongside the dependencies needed by the server.

The output also preserves the relevant directory structure. In this example the generated entry point is beneath apps/web, not at the top of the copied directory. I keep that structure and launch its server.js. Flattening it would break the relative relationships I have just asked Next to preserve.

This is worth checking before adjusting application code. If the deployment cannot load Next itself, changing how the catalogue component renders its heading is unlikely to help.


A Runtime Filename Needs Another Instruction

The catalogue file is selected through an environment variable. The application resolves the supplied path and reads it during the request:

const cataloguePath = process.env.CATALOGUE_PATH;

if (!cataloguePath) {
  throw new Error('CATALOGUE_PATH must name a catalogue');
}

const catalogue = JSON.parse(
  await readFile(path.resolve(process.cwd(), cataloguePath), 'utf8'),
);

That setting can name either the autumn or winter catalogue. Knowing the workspace boundary doesn't tell the build which arbitrary filename a later process might receive.

In this version, the catalogue page can add a narrow include to its trace:

export const config = {
  unstable_includeFiles: ['../../shared/catalogues/*.json'],
};

These patterns are relative to the application root. I include the directory containing the two intended inputs, rather than reaching for a broad pattern covering the whole repository. The latter would be an effective way to turn a small deployment back into a very large one, with less obvious contents.

The include doesn't validate the environment variable or make it appropriate to accept a filesystem path from a visitor. My example supplies a trusted deployment setting. If the real application accepts a catalogue choice from a request, I would map that choice to an allowed filename separately.

After building, I inspect the catalogue's trace and the copied files. Then I run the deployment once for each catalogue. Finding one file is not evidence that the other has been included.


Copy the Assets You Intend This Server to Serve

Standalone output doesn't copy public or .next/static automatically. Those files can be served elsewhere, but my example has no separate asset host. Its generated server needs both directories.

For this workspace layout, the copy step is:

cp -R public .next/standalone/apps/web/public
mkdir -p .next/standalone/apps/web/.next
cp -R .next/static .next/standalone/apps/web/.next/static

I run those commands from apps/web, after the build. The destination follows the generated server's location; an application without the wider workspace layout would use a different destination.

Leaving these directories out gives a particularly unhelpful half‑success. The document can return 200, whilst its image and framework scripts return 404. The button is visible because the server rendered it. Clicking it achieves very little.

This is still a Node server deployment. My article on static generation and server‑side rendering covers the rendering distinction; standalone output changes how we package the server, not whether a request‑time page needs one.


Test the Copy with the Source Out of Reach

I use separate broken copies to check the tracing boundary, the dynamically selected files, and the omitted assets. Keeping those cases separate makes the failure useful: I can see which change restores the missing behaviour.

The final copy must start using its own dependencies, serve both catalogue choices, return its image and scripts, and run the button's click handler. I also follow the catalogue link and refresh the resulting page. A homepage response alone doesn't exercise the filesystem read.

For the isolated check, the original data directory is unavailable and module resolution is checked for attempts to reach outside the copied deployment. Otherwise a test running beneath the original checkout can quietly borrow a dependency from an ancestor's node_modules. That would prove something rather different from what I intended.


Wrapping Up

Standalone output gives me a useful starting point for packaging a Next server. I still need to account for the application's directory layout, runtime‑selected files, and wherever its public assets will be served.

The useful release check is to run the exact copy I intend to ship and request the things which depend on those choices. If it only works beside the source checkout, the packaging work isn't finished.

Postscript

November 2026: I've added my working standalone deployment example, with the Next 12.3.1 configuration above and a Next 16.4.6 version. Current Next uses top‑level outputFileTracingRoot and outputFileTracingIncludes options rather than the historical experimental root and page‑level include. The download runs the copied servers with their original data directory unavailable, checks both catalogue choices, and exercises the missing‑asset case in production. Its lockfiles and test tooling were prepared for this update; they aren't an archived 2022 installation.

Downloadable Resource

  • Next.js Standalone Runtime Files

    Run my copied Next.js standalone servers with missing runtime data or assets, then check both catalogue choices, browser hydration, and the fixed deployment.

    Download ZIP

Untangling a delivery problem?

Send the symptoms, constraints, and affected routes. I'll help identify whether the issue sits in the application, platform, content model, deployment path, or search surface.