next.config.ts: Implement `compiler.defineServer` for server-only constants #79225

wbinnssmith · 2025-05-14T22:25:50Z

Like compiler.define, this allows users to create compile-time constants both Turbopack and webpack from a single API. compiler.defineServer instead only makes these constants available for server or edge environments, not the client environment.

changeset-bot · 2025-05-14T22:25:55Z

⚠️ No Changeset found

Latest commit: 8fa7bd5

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

wbinnssmith · 2025-05-15T01:59:03Z

docs/03-architecture/nextjs-compiler.mdx


 ```js filename="next.config.js"
 module.exports = {
  compiler: {
    define: {
-      MY_STRING_VARIABLE: JSON.stringify('my-string'),


this adds literal quotes inside the string value, which I don't think is the intention.

The current example looks correct to me. I.e. you can MY_VARIABLE: true and it replaces with true as the value, not a string. Removing JSON.stringify will cause my-string to be inlined, which is not a valid variable and not valid code.

I figured that was the case too, but I don't believe it is. Check out the tests, which do not add additional quotes, and run as expected.

serializeDefineEnv applies JSON.stringify to every value. That is then passed to https://webpack.js.org/plugins/define-plugin/#usage which has the semantics you described.

next.js/packages/next/src/build/define-env.ts

Line 304 in 96833da

const serializedDefineEnv = serializeDefineEnv(defineEnv)

So for nextConfig.compiler.define, you can in fact not replace something with a global variable, but

"some_boolean": false, "some_number": 123, "some_str": "hello world", "some_json": [{x: 123}]

works as expected because what webpack.DefinePlugin receives is

"some_boolean": "false", "some_number": "123", "some_str": '"hello world"', "some_json": "[{x: 123}]"

Meaning that nextConfig.compiler.define has the same semantics as nextConfig.env(expect that env effectively prefixes every key with process.env)

ijjk · 2025-05-15T02:04:13Z

Failing test suites

Commit: 96833da

pnpm test-dev test/development/app-dir/use-cache-errors/use-cache-errors.test.ts

use-cache-errors > should show a runtime error when calling the incorrectly used cache function

Expand output

● use-cache-errors › should show a runtime error when calling the incorrectly used cache function

expect(received).toMatchInlineSnapshot(snapshot)

Snapshot name: `use-cache-errors should show a runtime error when calling the incorrectly used cache function 1`

- Snapshot  - 5
+ Received  + 3

  {
    "description": "Attempted to call useStuff() from the server but useStuff is on the client. It's not possible to invoke a client function from the server, it can only be rendered as a Component or passed to props of a Client Component.",
    "environmentLabel": "Cache",
    "label": "Runtime Error",
-   "source": "app/module-with-use-cache.ts (16:18) @ useCachedStuff
- > 16 |   return useStuff()
-      |                  ^",
+   "source": null,
    "stack": [
      "<FIXME-file-protocol>",
-     "useCachedStuff app/module-with-use-cache.ts (16:18)",
-     "Page app/page.tsx (22:10)",
+     "useCachedStuff rsc:/Cache/webpack-internal:///(action-browser)/app/module-with-use-cache.ts (25:68)",
+     "Page ./app/page.tsx",
    ],
  }

  37 |       `)
  38 |     } else {
> 39 |       await expect(browser).toDisplayRedbox(`
     |                             ^
  40 |        {
  41 |          "description": "Attempted to call useStuff() from the server but useStuff is on the client. It's not possible to invoke a client function from the server, it can only be rendered as a Component or passed to props of a Client Component.",
  42 |          "environmentLabel": "Cache",

  at Object.toDisplayRedbox (development/app-dir/use-cache-errors/use-cache-errors.test.ts:39:29)