From 1a6a1e5fdfcc6c9d829d89b337852a55f7e72960 Mon Sep 17 00:00:00 2001
From: JJ Kasper <jj@jjsweb.site>
Date: Tue, 7 Dec 2021 17:22:21 -0600
Subject: [PATCH] Add docs for leveraging outputStandalone config (#32255)

This adds documentation to explain how the `outputStandalone` config can be leveraged to reduce production deployment size and leverage the output file traces.  This also adds a note for the `outputFileTracingRoot` config as it may be needed in some monorepo setups.

A follow-up PR will update our Docker example to leverage this config as well.

## Documentation / Examples

- [x] Make sure the linting passes by running `yarn lint`

x-ref: https://github.com/vercel/next.js/pull/31003
x-ref: https://github.com/vercel/next.js/issues/32252
Closes: https://github.com/vercel/next.js/issues/30822
---
 docs/advanced-features/output-file-tracing.md | 30 +++++++++++++++++++
 packages/next/server/config.ts                | 21 ++++++++++++-
 2 files changed, 50 insertions(+), 1 deletion(-)

diff --git a/docs/advanced-features/output-file-tracing.md b/docs/advanced-features/output-file-tracing.md
index b5ba359591af6cd..1f8ca2c7f48522e 100644
--- a/docs/advanced-features/output-file-tracing.md
+++ b/docs/advanced-features/output-file-tracing.md
@@ -18,7 +18,37 @@ Next.js' production server is also traced for its needed files and output at `.n
 
 To leverage the `.nft.json` files emitted to the `.next` output directory, you can read the list of files in each trace which are relative to the `.nft.json` file and then copy them to your deployment location.
 
+## Automatically Copying Traced Files (experimental)
+
+Next.js can automatically create a `standalone` folder which copies only the necessary files for a production deployment including select files in `node_modules`.
+
+To leverage this automatic copying you can enable it in your `next.config.js`:
+
+```js
+module.exports = {
+  experimental: {
+    outputStandalone: true,
+  },
+}
+```
+
+This will create a folder at `.next/standalone` which can then be deployed on it's own without installing `node_modules`.
+
+Additionally, a minimal `server.js` file is also output which can be used instead of `next start`. This minimal server does not handle serving the `static` directory as this should be handled by a CDN instead.
+
 ## Caveats
 
+- While tracing in monorepo setups, the project directory is used for tracing by default. For `next build packages/web-app`, `packages/web-app` would be the tracing root and any files outside of that folder will not be included. To include files outside of this folder you can set `experimental.outputFileTracingRoot` in your `next.config.js`.
+
+```js
+// packages/web-app/next.config.js
+module.exports = {
+  experimental: {
+    // this includes files from the monorepo base two directories up
+    outputFileTracingRoot: path.join(__dirname, '../../'),
+  },
+}
+```
+
 - There are some cases that Next.js might fail to include required files, or might incorrectly include unused files. In those cases, you can export page configs props `unstable_includeFiles` and `unstable_excludeFiles` respectively. Each prop accepts an array of [globs](<https://en.wikipedia.org/wiki/Glob_(programming)>) relative to the project's root to either include or exclude in the trace.
 - Currently, Next.js does not do anything with the emitted `.nft.json` files. The files must be read by your deployment platform, for example [Vercel](https://vercel.com), to create a minimal deployment. In a future release, a new command is planned to utilize these `.nft.json` files.
diff --git a/packages/next/server/config.ts b/packages/next/server/config.ts
index 1c3b00312fd9790..ac8e04f34a13742 100644
--- a/packages/next/server/config.ts
+++ b/packages/next/server/config.ts
@@ -1,6 +1,6 @@
 import chalk from 'chalk'
 import findUp from 'next/dist/compiled/find-up'
-import { basename, extname, relative } from 'path'
+import { basename, extname, relative, isAbsolute, resolve } from 'path'
 import { pathToFileURL } from 'url'
 import { Agent as HttpAgent } from 'http'
 import { Agent as HttpsAgent } from 'https'
@@ -371,6 +371,25 @@ function assignDefaults(userConfig: { [key: string]: any }) {
     )
   }
 
+  if (
+    result.experimental?.outputFileTracingRoot &&
+    !isAbsolute(result.experimental.outputFileTracingRoot)
+  ) {
+    result.experimental.outputFileTracingRoot = resolve(
+      result.experimental.outputFileTracingRoot
+    )
+    Log.warn(
+      `experimental.outputFileTracingRoot should be absolute, using: ${result.experimental.outputFileTracingRoot}`
+    )
+  }
+
+  if (result.experimental?.outputStandalone && !result.outputFileTracing) {
+    Log.warn(
+      `experimental.outputStandalone requires outputFileTracing not be disabled please enable it to leverage the standalone build`
+    )
+    result.experimental.outputStandalone = false
+  }
+
   // TODO: Change defaultConfig type to NextConfigComplete
   // so we don't need "!" here.
   setHttpAgentOptions(