Turbopack: Allow arrays to be used as values in turbopack.rules config (#83138)

bgw · web-flow · commit cad41015dcae · 2025-08-28T21:27:11.000-07:00
This implements the last part of the syntax proposal in #82857. We want to support this syntax: ```javascript module.exports = { turbopack: { rules: { // all matched rules apply, adding their loaders in order '*.svg': [ // this optionally can be an array of objects (shown here), or just an object { // this condition is matched after the glob condition: { all: [ { not: 'foreign' }, // excludes `node_modules` { path: /app\/.*\.svg/, content: /\<svg[^\>]*\>/ }, ], }, loaders: ['@svgr/webpack'], as: '*.js', }, ], }, }, } ``` Prior to this PR, the value of `'*.svg'` in the `turbopack.rules` object had to be a configuration object or an array of shorthand loader syntax. After this PR, it can be an array of "full" configuration objects.
diff --git a/crates/next-core/Cargo.toml b/crates/next-core/Cargo.toml
@@ -15,7 +15,7 @@ workspace = true
 anyhow = { workspace = true }
 async-trait = { workspace = true }
 base64 = "0.21.0"
-either = { workspace = true }
+either = { workspace = true, features = ["serde"] }
 once_cell = { workspace = true }
 qstring = { workspace = true }
 regex = { workspace = true }
diff --git a/crates/next-core/src/next_config.rs b/crates/next-core/src/next_config.rs
@@ -1,6 +1,7 @@
 use std::{collections::BTreeSet, str::FromStr};
 
 use anyhow::{Context, Result, bail};
+use either::Either;
 use rustc_hash::FxHashSet;
 use serde::{Deserialize, Deserializer, Serialize};
 use serde_json::Value as JsonValue;
@@ -558,7 +559,7 @@ pub enum RemotePatternProtocol {
 pub struct TurbopackConfig {
     /// This option has been replaced by `rules`.
     pub loaders: Option<JsonValue>,
-    pub rules: Option<FxIndexMap<RcStr, RuleConfigItemOrShortcut>>,
+    pub rules: Option<FxIndexMap<RcStr, RuleConfigCollection>>,
     #[turbo_tasks(trace_ignore)]
     pub conditions: Option<FxIndexMap<RcStr, ConfigConditionItem>>,
     pub resolve_alias: Option<FxIndexMap<RcStr, JsonValue>>,
@@ -666,6 +667,16 @@ impl TryFrom<ConfigConditionItem> for ConditionItem {
     }
 }
 
+#[derive(
+    Clone, Debug, PartialEq, Eq, Serialize, Deserialize, TraceRawVcs, NonLocalValue, OperationValue,
+)]
+#[serde(rename_all = "camelCase", untagged)]
+pub enum RuleConfigItem {
+    Options(RuleConfigItemOptions),
+    LegacyConditional(FxIndexMap<RcStr, RuleConfigItem>),
+    LegacyBoolean(bool),
+}
+
 #[derive(
     Clone, Debug, PartialEq, Eq, Serialize, Deserialize, TraceRawVcs, NonLocalValue, OperationValue,
 )]
@@ -678,23 +689,33 @@ pub struct RuleConfigItemOptions {
     pub condition: Option<ConfigConditionItem>,
 }
 
-#[derive(
-    Clone, Debug, PartialEq, Eq, Serialize, Deserialize, TraceRawVcs, NonLocalValue, OperationValue,
-)]
-#[serde(rename_all = "camelCase", untagged)]
-pub enum RuleConfigItemOrShortcut {
-    Loaders(Vec<LoaderItem>),
-    Advanced(RuleConfigItem),
+#[derive(Clone, Debug, PartialEq, Eq, Serialize, TraceRawVcs, NonLocalValue, OperationValue)]
+#[serde(transparent)]
+pub struct RuleConfigCollection(Vec<RuleConfigCollectionItem>);
+
+impl<'de> Deserialize<'de> for RuleConfigCollection {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: Deserializer<'de>,
+    {
+        match either::serde_untagged::deserialize::<Vec<RuleConfigCollectionItem>, RuleConfigItem, D>(
+            deserializer,
+        )? {
+            Either::Left(collection) => Ok(RuleConfigCollection(collection)),
+            Either::Right(item) => Ok(RuleConfigCollection(vec![RuleConfigCollectionItem::Full(
+                item,
+            )])),
+        }
+    }
 }
 
 #[derive(
     Clone, Debug, PartialEq, Eq, Serialize, Deserialize, TraceRawVcs, NonLocalValue, OperationValue,
 )]
-#[serde(rename_all = "camelCase", untagged)]
-pub enum RuleConfigItem {
-    Options(RuleConfigItemOptions),
-    LegacyConditional(FxIndexMap<RcStr, RuleConfigItem>),
-    LegacyBoolean(bool),
+#[serde(untagged)]
+pub enum RuleConfigCollectionItem {
+    Shorthand(LoaderItem),
+    Full(RuleConfigItem),
 }
 
 #[derive(
@@ -1392,11 +1413,12 @@ impl NextConfig {
             return Ok(Vc::cell(Vec::new()));
         }
         let mut rules = Vec::new();
-        for (glob, rule) in turbo_rules.iter() {
-            fn transform_loaders(loaders: &[LoaderItem]) -> ResolvedVc<WebpackLoaderItems> {
+        for (glob, rule_collection) in turbo_rules.iter() {
+            fn transform_loaders(
+                loaders: &mut dyn Iterator<Item = &LoaderItem>,
+            ) -> ResolvedVc<WebpackLoaderItems> {
                 ResolvedVc::cell(
                     loaders
-                        .iter()
                         .map(|item| match item {
                             LoaderItem::LoaderName(name) => WebpackLoaderItem {
                                 loader: name.clone(),
@@ -1445,65 +1467,67 @@ impl NextConfig {
                 }
             }
             let config_file_path = || project_path.join(&self.config_file_name);
-            match rule {
-                RuleConfigItemOrShortcut::Loaders(loaders) => {
-                    rules.push((
-                        glob.clone(),
-                        LoaderRuleItem {
-                            loaders: transform_loaders(loaders),
-                            rename_as: None,
-                            condition: None,
-                        },
-                    ));
-                }
-                RuleConfigItemOrShortcut::Advanced(rule) => {
-                    if let FindRuleResult::Found(RuleConfigItemOptions {
-                        loaders,
-                        rename_as,
-                        condition,
-                    }) = find_rule(rule, &active_conditions)
-                    {
-                        // If the extension contains a wildcard, and the rename_as does not,
-                        // emit an issue to prevent users from encountering duplicate module names.
-                        if glob.contains("*")
-                            && let Some(rename_as) = rename_as.as_ref()
-                            && !rename_as.contains("*")
+            for item in &rule_collection.0 {
+                match item {
+                    RuleConfigCollectionItem::Shorthand(loaders) => {
+                        rules.push((
+                            glob.clone(),
+                            LoaderRuleItem {
+                                loaders: transform_loaders(&mut [loaders].into_iter()),
+                                rename_as: None,
+                                condition: None,
+                            },
+                        ));
+                    }
+                    RuleConfigCollectionItem::Full(rule_config_item) => {
+                        if let FindRuleResult::Found(RuleConfigItemOptions {
+                            loaders,
+                            rename_as,
+                            condition,
+                        }) = find_rule(rule_config_item, &active_conditions)
                         {
-                            InvalidLoaderRuleRenameAsIssue {
-                                glob: glob.clone(),
-                                config_file_path: config_file_path()?,
-                                rename_as: rename_as.clone(),
-                            }
-                            .resolved_cell()
-                            .emit();
-                        }
-
-                        // convert from Next.js-specific condition type to internal Turbopack
-                        // condition type
-                        let condition = if let Some(condition) = condition {
-                            if let Ok(cond) = ConditionItem::try_from(condition.clone()) {
-                                Some(cond)
-                            } else {
-                                InvalidLoaderRuleConditionIssue {
-                                    condition: condition.clone(),
+                            // If the extension contains a wildcard, and the rename_as does not,
+                            // emit an issue to prevent users from encountering duplicate module
+                            // names.
+                            if glob.contains("*")
+                                && let Some(rename_as) = rename_as.as_ref()
+                                && !rename_as.contains("*")
+                            {
+                                InvalidLoaderRuleRenameAsIssue {
+                                    glob: glob.clone(),
                                     config_file_path: config_file_path()?,
+                                    rename_as: rename_as.clone(),
                                 }
                                 .resolved_cell()
                                 .emit();
-                                None
                             }
-                        } else {
-                            None
-                        };
 
-                        rules.push((
-                            glob.clone(),
-                            LoaderRuleItem {
-                                loaders: transform_loaders(loaders),
-                                rename_as: rename_as.clone(),
-                                condition,
-                            },
-                        ));
+                            // convert from Next.js-specific condition type to internal Turbopack
+                            // condition type
+                            let condition = if let Some(condition) = condition {
+                                if let Ok(cond) = ConditionItem::try_from(condition.clone()) {
+                                    Some(cond)
+                                } else {
+                                    InvalidLoaderRuleConditionIssue {
+                                        condition: condition.clone(),
+                                        config_file_path: config_file_path()?,
+                                    }
+                                    .resolved_cell()
+                                    .emit();
+                                    None
+                                }
+                            } else {
+                                None
+                            };
+                            rules.push((
+                                glob.clone(),
+                                LoaderRuleItem {
+                                    loaders: transform_loaders(&mut loaders.iter()),
+                                    rename_as: rename_as.clone(),
+                                    condition,
+                                },
+                            ));
+                        }
                     }
                 }
             }
diff --git a/packages/next/src/build/swc/index.ts b/packages/next/src/build/swc/index.ts
@@ -14,9 +14,9 @@ import type {
   TurbopackLoaderBuiltinCondition,
   TurbopackLoaderItem,
   TurbopackRuleCondition,
+  TurbopackRuleConfigCollection,
   TurbopackRuleConfigItem,
   TurbopackRuleConfigItemOptions,
-  TurbopackRuleConfigItemOrShortcut,
 } from '../../server/config-shared'
 import { isDeepStrictEqual } from 'util'
 import { type DefineEnvOptions, getDefineEnv } from '../define-env'
@@ -1014,13 +1014,19 @@ function bindingToApi(
 
   // Note: Returns an updated `turbopackRules` with serialized conditions. Does not mutate in-place.
   function serializeTurbopackRules(
-    turbopackRules: Record<string, TurbopackRuleConfigItemOrShortcut>
+    turbopackRules: Record<string, TurbopackRuleConfigCollection>
   ): Record<string, any> {
     const serializedRules: Record<string, any> = {}
     for (const [glob, rule] of Object.entries(turbopackRules)) {
       if (Array.isArray(rule)) {
-        checkLoaderItems(rule, glob)
-        serializedRules[glob] = rule
+        serializedRules[glob] = rule.map((item) => {
+          if (typeof item !== 'string' && 'loaders' in item) {
+            return serializeConfigItem(item, glob)
+          } else {
+            checkLoaderItem(item, glob)
+            return item
+          }
+        })
       } else {
         serializedRules[glob] = serializeConfigItem(rule, glob)
       }
@@ -1036,7 +1042,9 @@ function bindingToApi(
       let serializedRule: any = rule
       if ('loaders' in rule) {
         const narrowedRule = rule as TurbopackRuleConfigItemOptions
-        checkLoaderItems(narrowedRule.loaders, glob)
+        for (const item of narrowedRule.loaders) {
+          checkLoaderItem(item, glob)
+        }
         if (narrowedRule.condition != null) {
           serializedRule = {
             ...rule,
@@ -1056,19 +1064,15 @@ function bindingToApi(
       return serializedRule
     }
 
-    function checkLoaderItems(
-      loaderItems: TurbopackLoaderItem[],
-      glob: string
-    ) {
-      for (const loaderItem of loaderItems) {
-        if (
-          typeof loaderItem !== 'string' &&
-          !isDeepStrictEqual(loaderItem, JSON.parse(JSON.stringify(loaderItem)))
-        ) {
-          throw new Error(
-            `loader ${loaderItem.loader} for match "${glob}" does not have serializable options. Ensure that options passed are plain JavaScript objects and values.`
-          )
-        }
+    function checkLoaderItem(loaderItem: TurbopackLoaderItem, glob: string) {
+      if (
+        typeof loaderItem !== 'string' &&
+        !isDeepStrictEqual(loaderItem, JSON.parse(JSON.stringify(loaderItem)))
+      ) {
+        throw new Error(
+          `loader ${loaderItem.loader} for match "${glob}" does not have serializable options. ` +
+            'Ensure that options passed are plain JavaScript objects and values.'
+        )
       }
     }
   }
diff --git a/packages/next/src/server/config-schema.ts b/packages/next/src/server/config-schema.ts
@@ -12,7 +12,7 @@ import type {
   TurbopackOptions,
   TurbopackRuleConfigItem,
   TurbopackRuleConfigItemOptions,
-  TurbopackRuleConfigItemOrShortcut,
+  TurbopackRuleConfigCollection,
   TurbopackRuleCondition,
   TurbopackLoaderBuiltinCondition,
 } from './config-shared'
@@ -151,11 +151,14 @@ const zTurbopackRuleConfigItem: zod.ZodType<TurbopackRuleConfigItem> = z.union([
   zTurbopackRuleConfigItemOptions,
 ])
 
-const zTurbopackRuleConfigItemOrShortcut: zod.ZodType<TurbopackRuleConfigItemOrShortcut> =
-  z.union([z.array(zTurbopackLoaderItem), zTurbopackRuleConfigItem])
+const zTurbopackRuleConfigCollection: zod.ZodType<TurbopackRuleConfigCollection> =
+  z.union([
+    zTurbopackRuleConfigItem,
+    z.array(z.union([zTurbopackLoaderItem, zTurbopackRuleConfigItemOptions])),
+  ])
 
 const zTurbopackConfig: zod.ZodType<TurbopackOptions> = z.strictObject({
-  rules: z.record(z.string(), zTurbopackRuleConfigItemOrShortcut).optional(),
+  rules: z.record(z.string(), zTurbopackRuleConfigCollection).optional(),
   conditions: z.record(z.string(), zTurbopackCondition).optional(),
   resolveAlias: z
     .record(
@@ -177,7 +180,7 @@ const zTurbopackConfig: zod.ZodType<TurbopackOptions> = z.strictObject({
 const zDeprecatedExperimentalTurboConfig: zod.ZodType<DeprecatedExperimentalTurboOptions> =
   z.strictObject({
     loaders: z.record(z.string(), z.array(zTurbopackLoaderItem)).optional(),
-    rules: z.record(z.string(), zTurbopackRuleConfigItemOrShortcut).optional(),
+    rules: z.record(z.string(), zTurbopackRuleConfigCollection).optional(),
     resolveAlias: z
       .record(
         z.string(),
diff --git a/packages/next/src/server/config-shared.ts b/packages/next/src/server/config-shared.ts
@@ -289,9 +289,18 @@ export type TurbopackRuleConfigItem =
   | { [condition in TurbopackLoaderBuiltinCondition]?: TurbopackRuleConfigItem }
   | false
 
-export type TurbopackRuleConfigItemOrShortcut =
-  | TurbopackLoaderItem[]
+/**
+ * This can be an object representing a single configuration, or a list of
+ * loaders and/or rule configuration objects.
+ *
+ * - A list of loader path strings or objects is the "shorthand" syntax.
+ * - A list of rule configuration objects can be useful when each configuration
+ *   object has different `condition` fields, but still match the same top-level
+ *   path glob.
+ */
+export type TurbopackRuleConfigCollection =
   | TurbopackRuleConfigItem
+  | (TurbopackLoaderItem | TurbopackRuleConfigItemOptions)[]
 
 export interface TurbopackOptions {
   /**
@@ -316,7 +325,7 @@ export interface TurbopackOptions {
    *
    * @see [Turbopack Loaders](https://nextjs.org/docs/app/api-reference/next-config-js/turbo#webpack-loaders)
    */
-  rules?: Record<string, TurbopackRuleConfigItemOrShortcut>
+  rules?: Record<string, TurbopackRuleConfigCollection>
 
   /**
    * (`next --turbopack` only) A list of conditions to apply when running webpack loaders with Turbopack.
diff --git a/test/e2e/turbopack-loader-config/next.config.ts b/test/e2e/turbopack-loader-config/next.config.ts
