feat: add experimental.swcEnvOptions for SWC preset-env configuration (#92272)

### What?

Add `experimental.swcEnvOptions` to expose SWC's preset-env `env`
configuration options — including `mode`, `coreJs`, `include`,
`exclude`, `skip`, `shippedProposals`, `forceAllTransforms`, `debug`,
and `loose`.

### Why?

Currently Next.js only passes `env.targets` (derived from browserslist)
to SWC for **syntax downleveling**, but does not expose the polyfill
injection capabilities that SWC already supports. This means:

- Users who need automatic core-js polyfills (e.g.
`Array.prototype.at()`, `Promise.withResolvers()`, `Set` methods) have
no built-in way to get them.
- The only workarounds are importing `core-js` globally (which bloats
bundles significantly) or ejecting to Babel with `useBuiltIns: 'usage'`
(which sacrifices SWC's performance benefits).
- In the Babel era, Next.js supported this via `@babel/preset-env`'s
`useBuiltIns` (PR #10574). That capability was lost when Next.js
migrated to SWC.

### How?

A new `experimental.swcEnvOptions` config is added. Its properties are
spread into the `env` block that Next.js passes to SWC for client-side
compilation, alongside the existing browserslist-derived `targets`.
Server-side compilation is unaffected (always targets `node`).

The option surface mirrors [SWC's preset-env
docs](https://swc.rs/docs/configuration/supported-browsers) 1:1, keeping
it familiar and forward-compatible.

```js
// next.config.js
module.exports = {
  experimental: {
    swcEnvOptions: {
      mode: 'usage',
      coreJs: '3.38',
    },
  },
}
```
#### Changes:
config-shared.ts — type definition with JSDoc
config-schema.ts — zod validation
next-swc-loader.ts → swc/options.ts — plumb config into the SWC env
block
Unit tests (6 cases) + e2e test (dev & production)

Related issues #66562, #63104, #74978
Related discussion #46724

---------

Co-authored-by: Benjamin Woodruff <[email protected]>

Author: banchichen

crates/next-core/src/next_client/context.rs

@@ -29,6 +29,7 @@ use turbopack_core::{
 use turbopack_css::chunk::CssChunkType;
 use turbopack_ecmascript::{
     AnalyzeMode, TypeofWindow, chunk::EcmascriptChunkType, references::esm::UrlRewriteBehavior,
+    transform::PresetEnvConfig,
 };
 use turbopack_node::{
     execution_context::ExecutionContext,
@@ -330,6 +331,24 @@ pub async fn get_client_module_options_context(
     let enable_foreign_postcss_transform = Some(postcss_foreign_transform_options.resolved_cell());
 
     let source_maps = *next_config.client_source_maps(mode).await?;
+
+    let preset_env_config = (*next_config.experimental_swc_env_options().await?)
+        .as_ref()
+        .map(|opts| {
+            PresetEnvConfig {
+                mode: opts.mode.clone(),
+                core_js: opts.core_js.clone(),
+                skip: opts.skip.clone(),
+                include: opts.include.clone(),
+                exclude: opts.exclude.clone(),
+                shipped_proposals: opts.shipped_proposals,
+                force_all_transforms: opts.force_all_transforms,
+                debug: opts.debug,
+                loose: opts.loose,
+            }
+            .resolved_cell()
+        });
+
     let module_options_context = ModuleOptionsContext {
         ecmascript: EcmascriptOptionsContext {
             esm_url_rewrite_behavior: Some(UrlRewriteBehavior::Relative),
@@ -338,6 +357,7 @@ pub async fn get_client_module_options_context(
             enable_import_as_text: *next_config.turbopack_import_type_text().await?,
             source_maps,
             infer_module_side_effects: *next_config.turbopack_infer_module_side_effects().await?,
+            preset_env_config,
             ..Default::default()
         },
         css: CssOptionsContext {
@@ -374,6 +394,9 @@ pub async fn get_client_module_options_context(
             enable_typeof_window_inlining: None,
             // Ignore e.g. import(`${url}`) requests in node_modules.
             ignore_dynamic_requests: true,
+            // Don't inject core-js polyfills into node_modules — only user code
+            // should be processed by preset_env's usage/entry mode.
+            preset_env_config: None,
             ..module_options_context.ecmascript
         },
         enable_webpack_loaders: foreign_enable_webpack_loaders,
@@ -390,6 +413,8 @@ pub async fn get_client_module_options_context(
                 TypescriptTransformOptions::default().resolved_cell(),
             ),
             enable_jsx: Some(JsxTransformOptions::default().resolved_cell()),
+            // Don't inject core-js polyfills into framework internals.
+            preset_env_config: None,
             ..module_options_context.ecmascript.clone()
         },
         enable_postcss_transform: None,

crates/next-core/src/next_config.rs

@@ -1081,6 +1081,7 @@ pub struct ExperimentalConfig {
     strict_next_head: Option<bool>,
     #[bincode(with = "turbo_bincode::serde_self_describing")]
     swc_plugins: Option<Vec<(RcStr, serde_json::Value)>>,
+    swc_env_options: Option<SwcEnvOptions>,
     external_middleware_rewrites_resolve: Option<bool>,
     scroll_restoration: Option<bool>,
     manual_client_base_path: Option<bool>,
@@ -1419,6 +1420,37 @@ pub struct SwcPlugins(
     #[bincode(with = "turbo_bincode::serde_self_describing")] Vec<(RcStr, serde_json::Value)>,
 );
 
+/// Options for SWC's preset-env, exposed via `experimental.swcEnvOptions`.
+#[derive(
+    Clone,
+    Debug,
+    Default,
+    PartialEq,
+    Eq,
+    Serialize,
+    Deserialize,
+    TraceRawVcs,
+    NonLocalValue,
+    OperationValue,
+    Encode,
+    Decode,
+)]
+#[serde(rename_all = "camelCase")]
+pub struct SwcEnvOptions {
+    pub mode: Option<RcStr>,
+    pub core_js: Option<RcStr>,
+    pub skip: Option<Vec<RcStr>>,
+    pub include: Option<Vec<RcStr>>,
+    pub exclude: Option<Vec<RcStr>>,
+    pub shipped_proposals: Option<bool>,
+    pub force_all_transforms: Option<bool>,
+    pub debug: Option<bool>,
+    pub loose: Option<bool>,
+}
+
+#[turbo_tasks::value(transparent)]
+pub struct OptionSwcEnvOptions(Option<SwcEnvOptions>);
+
 #[turbo_tasks::value(transparent)]
 pub struct OptionalMdxTransformOptions(Option<ResolvedVc<MdxTransformOptions>>);
 
@@ -1854,6 +1886,11 @@ impl NextConfig {
         Vc::cell(self.experimental.swc_plugins.clone().unwrap_or_default())
     }
 
+    #[turbo_tasks::function]
+    pub fn experimental_swc_env_options(&self) -> Vc<OptionSwcEnvOptions> {
+        Vc::cell(self.experimental.swc_env_options.clone())
+    }
+
     #[turbo_tasks::function]
     pub fn experimental_sri(&self) -> Vc<OptionSubResourceIntegrity> {
         Vc::cell(self.experimental.sri.clone())

packages/next/src/build/swc/options.ts

@@ -397,6 +397,7 @@ export function getLoaderSWCOptions({
   optimizeServerReact,
   optimizePackageImports,
   swcPlugins,
+  swcEnvOptions,
   compilerOptions,
   jsConfig,
   supportedBrowsers,
@@ -426,6 +427,7 @@ export function getLoaderSWCOptions({
     NextConfig['experimental']
   >['optimizePackageImports']
   swcPlugins: ExperimentalConfig['swcPlugins']
+  swcEnvOptions?: ExperimentalConfig['swcEnvOptions']
   compilerOptions: NextConfig['compiler']
   jsConfig: any
   supportedBrowsers: string[] | undefined
@@ -539,6 +541,7 @@ export function getLoaderSWCOptions({
         ? {
             env: {
               targets: supportedBrowsers,
+              ...swcEnvOptions,
             },
           }
         : {}),

packages/next/src/build/webpack/loaders/next-swc-loader.ts

@@ -155,6 +155,7 @@ async function loaderTransform(
     modularizeImports: nextConfig?.modularizeImports,
     optimizePackageImports: nextConfig?.experimental?.optimizePackageImports,
     swcPlugins: nextConfig?.experimental?.swcPlugins,
+    swcEnvOptions: nextConfig?.experimental?.swcEnvOptions,
     compilerOptions: nextConfig?.compiler,
     optimizeServerReact: nextConfig?.experimental?.optimizeServerReact,
     jsConfig,

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

@@ -300,6 +300,19 @@ export const experimentalSchema = {
     // The specific swc plugin's option is unknown, use z.any() here
     .array(z.tuple([z.string(), z.record(z.string(), z.any())]))
     .optional(),
+  swcEnvOptions: z
+    .object({
+      mode: z.enum(['usage', 'entry']).optional(),
+      coreJs: z.string().optional(),
+      skip: z.array(z.string()).optional(),
+      include: z.array(z.string()).optional(),
+      exclude: z.array(z.string()).optional(),
+      shippedProposals: z.boolean().optional(),
+      forceAllTransforms: z.boolean().optional(),
+      debug: z.boolean().optional(),
+      loose: z.boolean().optional(),
+    })
+    .optional(),
   swcTraceProfiling: z.boolean().optional(),
   // NonNullable<webpack.Configuration['experiments']>['buildHttp']
   urlImports: z.any().optional(),

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

@@ -534,6 +534,53 @@ export interface ExperimentalConfig {
   forceSwcTransforms?: boolean
 
   swcPlugins?: Array<[string, Record<string, unknown>]>
+
+  /**
+   * Additional options for SWC's preset-env (`env` configuration).
+   * These are merged into the `env` block that Next.js passes to SWC,
+   * alongside the browserslist-derived `targets`.
+   *
+   * See https://swc.rs/docs/configuration/supported-browsers for full details.
+   *
+   * @example
+   * ```js
+   * // next.config.js
+   * module.exports = {
+   *   experimental: {
+   *     swcEnvOptions: {
+   *       mode: 'usage',
+   *       coreJs: '3.38',
+   *     },
+   *   },
+   * }
+   * ```
+   */
+  swcEnvOptions?: {
+    /**
+     * Polyfill injection mode, matching Babel's `useBuiltIns`.
+     * - `'usage'`: Adds specific polyfill imports per file based on actual usage.
+     * - `'entry'`: Replaces a single `import 'core-js'` with only the polyfills
+     *   needed for the target browsers.
+     */
+    mode?: 'usage' | 'entry'
+    /** The core-js version to use (e.g. `'3.38'`). Required when `mode` is set. */
+    coreJs?: string
+    /** Core-js modules or SWC transform passes to skip. */
+    skip?: string[]
+    /** Core-js modules or SWC transform passes to always include. */
+    include?: string[]
+    /** Core-js modules or SWC transform passes to always exclude. */
+    exclude?: string[]
+    /** Enable shipped TC39 proposals. */
+    shippedProposals?: boolean
+    /** Force all transforms regardless of targets. */
+    forceAllTransforms?: boolean
+    /** Enable debug output for preset-env. */
+    debug?: boolean
+    /** Enable loose mode for transforms. */
+    loose?: boolean
+  }
+
   largePageDataBytes?: number
   /**
    * If set to `false`, webpack won't fall back to polyfill Node.js modules in the browser

test/e2e/swc-auto-polyfill-disabled/app/layout.tsx

@@ -0,0 +1,8 @@
+import { ReactNode } from 'react'
+export default function Root({ children }: { children: ReactNode }) {
+  return (
+    <html>
+      <body>{children}</body>
+    </html>
+  )
+}

test/e2e/swc-auto-polyfill-disabled/app/page.tsx

@@ -0,0 +1,9 @@
+'use client'
+
+export default function Page() {
+  // Same code as the enabled fixture, but without swcEnvOptions
+  const text = 'a-b-c'
+  const result = text.replaceAll('-', '_')
+
+  return <p id="result">{result}</p>
+}

test/e2e/swc-auto-polyfill-disabled/next.config.js

@@ -0,0 +1,6 @@
+/**
+ * @type {import('next').NextConfig}
+ */
+const nextConfig = {}
+
+module.exports = nextConfig

test/e2e/swc-auto-polyfill-disabled/swc-auto-polyfill-disabled.test.ts

@@ -0,0 +1,35 @@
+import { nextTestSetup } from 'e2e-utils'
+import { retry } from 'next-test-utils'
+import fs from 'fs'
+import path from 'path'
+
+describe('swc-auto-polyfill-disabled', () => {
+  const { next, isNextDev, isNextDeploy } = nextTestSetup({
+    files: __dirname,
+  })
+
+  it('should render the page correctly without swcEnvOptions', async () => {
+    const browser = await next.browser('/')
+    await retry(async () => {
+      const text = await browser.elementByCss('#result').text()
+      expect(text).toBe('a_b_c')
+    })
+  })
+
+  if (!isNextDev && !isNextDeploy) {
+    it('should not include replaceAll polyfill in non-framework chunks', async () => {
+      const chunksDir = path.join(next.testDir, '.next', 'static', 'chunks')
+      const files = fs.readdirSync(chunksDir, { recursive: true }) as string[]
+      const jsFiles = files.filter((f) => f.endsWith('.js'))
+
+      for (const file of jsFiles) {
+        const content = fs.readFileSync(path.join(chunksDir, file), 'utf-8')
+        // Skip the built-in polyfill-nomodule chunk (contains core-js license URL)
+        if (content.includes('core-js/blob/')) continue
+
+        // Without swcEnvOptions, no replaceAll polyfill should be injected
+        expect(content).not.toMatch(/replaceAll[:]\s*function/)
+      }
+    })
+  }
+})