vercel · lforst · Oct 24, 2024 · Oct 24, 2024
diff --git a/docs/02-app/02-api-reference/05-next-config-js/turbo.mdx b/docs/02-app/02-api-reference/05-next-config-js/turbo.mdx
@@ -54,6 +54,7 @@ The following options are available for the `turbo` configuration:
 | `useSwcCss`         | Use `swc_css` instead of `lightningcss` for Turbopack                     |
 | `treeshaking`       | Enable tree shaking for the turbopack dev server and build.               |
 | `memoryLimit`       | A target memory limit for turbo, in bytes.                                |
+| `define`            | Replace variables in your code during the build.                          |
 
 ### Supported loaders
 
@@ -168,6 +169,24 @@ module.exports = {
 }
 ```
 
+### Replacing variables during build
+
+The `define` option allows you to statically replace variables in your code at build-time.
+The option takes an object as key-value pairs, where the keys are the variables that should be replaced with the corresponding values.
+
+Use the `define` field in `next.config.js`:
+
+```js filename="next.config.js"
+module.exports = {
+  experimental: {
+    turbo: {
+      MY_STRING_VARIABLE: JSON.stringify('my-string'),
+      MY_NUMBER_VARIABLE: '42',
+    },
+  },
+}
+```
+
 ## Version History
 
 | Version  | Changes                          |

diff --git a/packages/next/src/build/webpack/plugins/define-env-plugin.ts b/packages/next/src/build/webpack/plugins/define-env-plugin.ts
@@ -288,6 +288,17 @@ export function getDefineEnv({
         }
       : undefined),
   }
+
+  const userDefines = isTurbopack ? config.experimental.turbo?.define : {}
+  for (const key in userDefines) {
+    if (defineEnv.hasOwnProperty(key)) {
+      throw new Error(
+        `The \`turbo.define\` option is configured to replace the \`${key}\` variable. This variable is either part of a Next.js built-in or is already configured via the \`env\` option.`
+      )
+    }
+    defineEnv[key] = userDefines[key]
+  }
+
   const serializedDefineEnv = serializeDefineEnv(defineEnv)
 
   if (!dev && Boolean(config.experimental.flyingShuttle)) {

diff --git a/packages/next/src/server/config-schema.ts b/packages/next/src/server/config-schema.ts
@@ -410,6 +410,7 @@ export const configSchema: zod.ZodType<NextConfig> = z.lazy(() =>
               .optional(),
             memoryLimit: z.number().optional(),
             moduleIdStrategy: z.enum(['named', 'deterministic']).optional(),
+            define: z.record(z.string(), z.string()).optional(),
           })
           .optional(),
         optimizePackageImports: z.array(z.string()).optional(),

diff --git a/packages/next/src/server/config-shared.ts b/packages/next/src/server/config-shared.ts
@@ -179,6 +179,12 @@ export interface ExperimentalTurboOptions {
    * directory can be resolved by turbopack.
    */
   root?: string
+
+  /**
+   * Replaces variables in your code during compile time. Each key will be
+   * replaced with the respective values.
+   */
+  define?: Record<string, string>
 }
 
 export interface WebpackConfigContext {

diff --git a/test/e2e/define/app/client-component.tsx b/test/e2e/define/app/client-component.tsx
@@ -0,0 +1,9 @@
+'use client'
+
+declare const MY_MAGIC_VARIABLE: string
+
+export function ClientValue() {
+  return (
+    <>{typeof MY_MAGIC_VARIABLE === 'string' ? MY_MAGIC_VARIABLE : 'not set'}</>
+  )
+}
diff --git a/test/e2e/define/app/layout.tsx b/test/e2e/define/app/layout.tsx
@@ -0,0 +1,7 @@
+export default function Root({ children }: { children: React.ReactNode }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}
diff --git a/test/e2e/define/app/page.tsx b/test/e2e/define/app/page.tsx
@@ -0,0 +1,17 @@
+import { ClientValue } from './client-component'
+
+declare const MY_MAGIC_VARIABLE: string
+
+export default function Page() {
+  return (
+    <ul>
+      <li>
+        Server value:{' '}
+        {typeof MY_MAGIC_VARIABLE === 'string' ? MY_MAGIC_VARIABLE : 'not set'}
+      </li>
+      <li>
+        Client value: <ClientValue />
+      </li>
+    </ul>
+  )
+}
diff --git a/test/e2e/define/define.test.ts b/test/e2e/define/define.test.ts
@@ -0,0 +1,21 @@
+import { nextTestSetup } from 'e2e-utils'
+
+describe('define', () => {
+  const { next } = nextTestSetup({
+    files: __dirname,
+  })
+
+  it('should render the magic variable on server side', async () => {
+    const res = await next.fetch('/')
+    const html = (await res.text()).replaceAll(/<!-- -->/g, '')
+    expect(html).toContain('Server value: foobar')
+    expect(html).toContain('Client value: foobar')
+  })
+
+  it('should render the magic variable on client side', async () => {
+    const browser = await next.browser('/')
+    const text = await browser.elementByCss('body').text()
+    expect(text).toContain('Server value: foobar')
+    expect(text).toContain('Client value: foobar')
+  })
+})
diff --git a/test/e2e/define/next.config.js b/test/e2e/define/next.config.js
@@ -0,0 +1,9 @@
+module.exports = {
+  experimental: {
+    turbo: {
+      define: {
+        MY_MAGIC_VARIABLE: JSON.stringify('foobar'),
+      },
+    },
+  },
+}