feat: adds experimental serverOnlyDependencies property

docs/02-app/02-api-reference/05-next-config-js/serverOnlyDependencies.mdx

@@ -0,0 +1,23 @@
+---
+title: serverOnlyDependencies
+description: Mark certain imports as server-only to disable the addition of any subsequent, undesired client-side JS to the client-side bundle.
+---
+
+Next.js automatically tree-shakes client dependencies from server components, but there are cases where bundler tree-shaking is not smart enough to solely rely on. For example, tree-shaking works by determining if a dependency is referenced. If a client dependency is referenced (via adding to an object property, logging it, or similar) it will not be tree-shaken and will appear in the resulting client-side bundle.
+
+This is an escape hatch that can be used to mark certain dependencies as server-only, in which case, no subsequent client dependencies will be added to the resulting client-side JS.
+
+```js filename="next.config.js"
+const path = require('path')
+
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  experimental: {
+    serverOnlyDependencies: [path.resolve(__dirname, './app/my-server-dep.js')],
+  },
+}
+
+module.exports = nextConfig
+```
+
+In most cases, you should not need to use this property - but it can be helpful to library authors building on Next.js.

packages/next/src/build/webpack-config.ts

@@ -1876,6 +1876,7 @@ export default async function getBaseWebpackConfig(
             })
           : new FlightClientEntryPlugin({
               appDir,
+              ignore: config.experimental.serverOnlyDependencies ?? [],
               dev,
               isEdgeServer,
               encryptionKey,

packages/next/src/build/webpack/plugins/flight-client-entry-plugin.ts

@@ -47,6 +47,7 @@ import { getAssumedSourceType } from '../loaders/next-flight-loader'
 interface Options {
   dev: boolean
   appDir: string
+  ignore: string[]
   isEdgeServer: boolean
   encryptionKey: string
 }
@@ -171,10 +172,12 @@ export class FlightClientEntryPlugin {
   encryptionKey: string
   isEdgeServer: boolean
   assetPrefix: string
+  ignore: string[]
 
   constructor(options: Options) {
     this.dev = options.dev
     this.appDir = options.appDir
+    this.ignore = options.ignore
     this.isEdgeServer = options.isEdgeServer
     this.assetPrefix = !this.dev && !this.isEdgeServer ? '../' : ''
     this.encryptionKey = options.encryptionKey
@@ -660,7 +663,9 @@ export class FlightClientEntryPlugin {
         modRequest = mod.matchResource + ':' + modRequest
       }
 
-      if (!modRequest) return
+      // If there is no modRequest, or it's explicitly ignored by `serverOnlyDependencies`,
+      // we can skip everything from here on for this import
+      if (!modRequest || this.ignore.includes(modRequest)) return
       if (visited.has(modRequest)) {
         if (clientComponentImports[modRequest]) {
           addClientImport(

packages/next/src/server/config-schema.ts

@@ -321,6 +321,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
         taint: z.boolean().optional(),
         prerenderEarlyExit: z.boolean().optional(),
         proxyTimeout: z.number().gte(0).optional(),
+        serverOnlyDependencies: z.array(z.string()).optional(),
         scrollRestoration: z.boolean().optional(),
         sri: z
           .object({

packages/next/src/server/config-shared.ts

@@ -286,6 +286,10 @@ export interface ExperimentalConfig {
   }
   adjustFontFallbacks?: boolean
   adjustFontFallbacksWithSizeAdjust?: boolean
+  /**
+   * A list of imports that should completely disable any client dependencies from being added to generated client JS.
+   */
+  serverOnlyDependencies?: string[]
 
   webVitalsAttribution?: Array<(typeof WEB_VITALS)[number]>
 

test/production/app-dir/client-components-tree-shaking/app/server-only-dep/client.js

@@ -0,0 +1,5 @@
+'use client'
+
+export const UnusedClientComponent = () => {
+  return <p>better not include me!</p>
+}

test/production/app-dir/client-components-tree-shaking/app/server-only-dep/page.js

@@ -0,0 +1,6 @@
+import { serverOnlyObject } from './server-only'
+
+export default function Page() {
+  console.log(serverOnlyObject)
+  return <p>server only</p>
+}

test/production/app-dir/client-components-tree-shaking/app/server-only-dep/server-only.js

@@ -0,0 +1,5 @@
+import { UnusedClientComponent } from './client'
+
+export const serverOnlyObject = {
+  client: UnusedClientComponent,
+}

test/production/app-dir/client-components-tree-shaking/index.test.ts

@@ -9,6 +9,31 @@ describe('app-dir client-components-tree-shaking', () => {
   })
   if (skipped) return
 
+  it('should not add any client dependencies resulting from modules defined in experimental.serverOnlyDependencies', async () => {
+    const clientChunksDir = join(
+      next.testDir,
+      '.next',
+      'static',
+      'chunks',
+      'app',
+      'server-only-dep'
+    )
+    const staticChunksDirents = fs.readdirSync(clientChunksDir, {
+      withFileTypes: true,
+    })
+    const chunkContents = staticChunksDirents
+      .filter((dirent) => dirent.isFile())
+      .map((chunkDirent) =>
+        fs.readFileSync(join(chunkDirent.path, chunkDirent.name), 'utf8')
+      )
+
+    expect(
+      chunkContents.every((content) => {
+        return !content.includes('better not include me!')
+      })
+    ).toBe(true)
+  })
+
   it('should only include imported components 3rd party package in browser bundle with direct imports', async () => {
     const clientChunksDir = join(
       next.testDir,

test/production/app-dir/client-components-tree-shaking/next.config.js

@@ -0,0 +1,9 @@
+const path = require('path')
+
+module.exports = {
+  experimental: {
+    serverOnlyDependencies: [
+      path.resolve(__dirname, './app/server-only-dep/server-only.js'),
+    ],
+  },
+}