DefinePlugin alternative for for Turbopack

[lforst]

Goals

Allow users to define key-value pairs in next.config.js that are statically replaced in the output bundles (all runtimes).

Non-Goals

Differenciate between between runtimes for injected values.

Background

This is a common feature in various bundlers and frameworks that allows for features like:

• Facilitating tree shaking
• Passing values determined during build-time to the runtime application code

Proposal

Suggestion for now while turbo is experimental:

// next.config.js

experimental: {
  turbo: {
    define: { // <- new
      values: { // <- values are put inside a `values` Record<string, string> so that there can be options for behavior inside `define`
        MY_STATIC_CONSTANT: Math.random(),
        'process.env.FOO': JSON.stringify("bar")
      }
    }
  }
}

Prior art:

• Webpack DefinePlugin: https://webpack.js.org/plugins/define-plugin/
• Rollup replace plugin: https://www.npmjs.com/package/@rollup/plugin-replace
• Vite define: https://v2.vitejs.dev/config/#define

[timneutkens]

define: { MY_STATIC_CONSTANT: 'a' } matches other bundlers closer so I don't think we'll want a special key in between.

[lforst]

My considerations here were:

• If we ever want to actually differentiate between runtimes, we could have serverValues, clientValues, edgeValues as keys for example.
• The rollup replace plugin has options, some of which I find pretty valid: https://www.npmjs.com/package/@rollup/plugin-replace#options

In general, just wanted to keep the door open for iteration.

[huozhi]

Mark as resolved since the initial support is landed in #71802