Unverified Commit e2fca6c6 authored by Tobias Koppers's avatar Tobias Koppers Committed by GitHub

[Turbopack] Add graph-based CSS chunking algorithm behind…

[Turbopack] Add graph-based CSS chunking algorithm behind experimental.cssChunking: "graph" (#93606)

### What?

Adds an alternative CSS chunking algorithm to Turbopack, opted into via:

```js
// next.config.js
module.exports = {
  experimental: {
    cssChunking: 'graph',
    // or, with explicit cost overrides:
    // cssChunking: { type: 'graph', requestCost: 20_000, moduleFactorCost: 1 },
  },
}
```

The new algorithm is **off by default** — Turbopack still uses the
existing
"loose"/dependencies algorithm unless this flag is set, so this PR is a
pure
addition for users that don't opt in.

While we were here, the `experimental.cssChunking` shape was also
generalized
so every existing string accepts an object form too:

| Value | Bundler | Notes |
|---|---|---|
| `true` / `'loose'` / `{ type: 'loose' }` | both | default
heuristic-based chunking |
| `'strict'` / `{ type: 'strict' }` | webpack | unchanged |
| `false` | webpack | unchanged (one chunk per CSS module) |
| `'graph'` / `{ type: 'graph', requestCost?, moduleFactorCost? }` |
Turbopack | new |

Cross-bundler combinations are rejected at config-validation time:
- `'graph'` with webpack throws.
- `'strict'` and `false` with Turbopack throw.

### Why?

The existing Turbopack CSS chunker (loose / dependencies) is good at
preserving CSS ordering but doesn't share chunks across pages well —
every
page tends to load its own chunk per CSS module, which scales poorly for
apps
with many pages and shared component libraries.

The new "graph" algorithm models the per-chunk-group CSS ordering as a
weighted DAG over modules, then greedily merges adjacent runs in the
global
topological order whenever the merge reduces total cost. The cost model
charges every CSS request and overshipped byte, with two tunable knobs
(`requestCost` and `moduleFactorCost`).

**Trade-off vs. the loose default.** With the default cost parameters
(`requestCost: 20_000`, `moduleFactorCost: 1`) the graph algorithm
typically
ships **less CSS per chunk group at the cost of more requests** than the
loose algorithm. The cost model is tuned to avoid overshipping unrelated
CSS
into pages that don't need it; on apps where the loose algorithm was
already
collapsing a lot into one big chunk that some pages didn't actually use,
the
graph algorithm will split it. Apps that prefer fewer requests can raise
`requestCost`; apps that prefer less overshipping can raise
`moduleFactorCost`.

This is opt-in and Turbopack-only because:
- The cost model is sensitive to per-app properties (number of pages,
size
distribution of CSS modules, …) — keeping it experimental gives us room
to
  tune defaults from real usage.
- Webpack already has its own `CssChunkingPlugin` and `'strict'` mode
that
  cover the equivalent design space; we don't want to fork that.

### Performance

Measured on `vercel.com` (the full graph algorithm spans
`create_graph → make_acyclic → linearize → split_into_chunks →
assemble`):

- **~3s** end-to-end for the synchronous chunking pipeline on a
realistic
  production input.

Implementation choices that matter for that throughput:

- Tarjan SCC uses `Vec<u32>` / `Vec<bool>` scratch arrays indexed by
  `NodeIndex` — no hashing on `indices` / `lowlinks` / `on_stack`.
- `make_acyclic` batches multiple cuts per SCC pass by seeding
successive
short-cycle searches at the previous cut's target, only re-running
Tarjan
  when no further cycle is reachable from the seed.
- `find_short_cycle` is a bidirectional Dijkstra over a `BinaryHeap`
with
predecessor pointers (no path cloning) and skips its refinement loop for
  trivial 2-cycles.
- `split_into_chunks` picks the next merge from a `BinaryHeap` keyed on
the
  cost delta instead of an O(N) linear scan per merge.
- `chunk_cost` reads a once-built `module_to_groups` inverse index
instead of
scanning every chunk group on every call; the GlobalStyle leakage check
uses binary search on the inverse index rather than scanning each
group's
  module list.

### How?

#### Module layout (`turbopack/crates/turbopack-core/src/module_graph/`)

The two algorithms are deliberately split so neither imports from the
other:

- `style_groups/` — algorithm-neutral output types (`StyleGroups`,
  `StyleItemInfo`, `make_style_groups`). Both algorithms produce these.
- `style_groups_loose/` — the existing ("loose") algorithm plus the
shared
  config types (`StyleGroupsAlgorithm`, `StyleGroupsConfig`,
  `F32TaskInput`).
- `style_groups_graph/` — the new algorithm. Pure Rust, no `Vc`, with
  `petgraph::DiGraph` plus a thin `SubgraphView` wrapper and a small
  `ReadonlyGraph` trait that lets the same pipeline run against either a
  `&DiGraph` or a filtered view of one SCC.

#### Algorithm

```text
create_graph → make_acyclic → linearize → split_into_chunks → assemble batches
```

1. **`create_graph`** — for each chunk group, every `(later, earlier)`
pair
   inside the group's CSS-module list becomes an edge `later → earlier`
   (weight 1, accumulated). Heavy edges = strong co-occurrence.
2. **`make_acyclic`** — co-occurrence almost always introduces cycles;
each
multi-node SCC has its lowest-weight cycle edge cut until the graph is a
   DAG.
3. **`linearize`** — Kahn-style topological sort with a tie-break on
edge
weight, so strongly co-occurring modules end up adjacent in the global
   order.
4. **`split_into_chunks`** — greedy bottom-up merger over the global
order.
   At every active split point we score the merge as
`cost(merged) - cost(left) - cost(right)`, take the most-negative score
   from a min-heap, and repeat until no merge would reduce cost.
   `max_chunk_size` and "global CSS must not leak into unrelated chunk
   groups" are enforced as `+infinity` cost.

The cost model is:

```text
cost_per_group(chunk, group)
  = chunk_size
  + (chunk_size / group_total_size) * module_factor_cost
  + request_cost
```

summed over the chunk groups that load the chunk.

#### Wiring

- `StyleGroups::shared_chunk_items` is a
  `FxIndexMap<ChunkItemWithAsyncModuleInfo, StyleItemInfo>` where
  `StyleItemInfo { order: Option<u32>, batch: Option<…> }`. The graph
algorithm fills `order` so `style_production.rs` can stable-sort chunks
globally; the legacy algorithm leaves `order = None`, which makes the
sort
a no-op for it. `flatten_and_sort` returns the `StyleItemInfo`
references
alongside each chunk item so the per-item loop doesn't re-query the map.
- A new `StyleGroupsAlgorithm` enum on `ChunkingConfig` selects the
  algorithm at chunking time; `ModuleGraph::style_groups` dispatches
to either `compute_style_groups` (existing) or
`compute_style_groups_graph`
  (new).
- `next-core` exposes `NextConfig::css_chunking() ->
Vc<CssChunkingAlgorithm>`
resolving the JS `experimental.cssChunking` to the Rust enum, with cost
defaults applied (`requestCost: 20_000`, `moduleFactorCost: 1`). All
three
  chunking-context constructors (`next_client`, `next_edge`,
  `next_server`) thread it through.

#### Configuration

- `experimental.cssChunking` zod schema accepts the new shapes; cost
params
  are `z.number().nonnegative().finite().optional()`.
- `config-shared.ts` exports a `CssChunkingConfig` type alias and a
`resolveCssChunkingMode(value)` helper that normalizes any input to one
of `'off' | 'loose' | 'strict' | 'graph'`. Both `webpack-config.ts`
(plugin
  wiring) and `config.ts` (bundler-compat validation) use the helper.
- New `errors.json` entries for the three bundler-compatibility
validation
  errors (E1193 graph-on-webpack, E1194 strict-on-Turbopack, E1195
  false-on-Turbopack).

#### Tests

- 53 Rust unit tests in `style_groups_graph/tests.rs` cover
`create_graph`,
Tarjan SCC, `find_short_cycle` (bidirectional Dijkstra), `make_acyclic`,
  `linearize`, `split_into_chunks`, and end-to-end pipeline scenarios.
- `test/e2e/app-dir/css-order/css-order.test.ts` is parametrised over
`[label, value]` pairs. The Turbopack matrix now includes `'graph'` and
an
object-form `{ type: 'graph', requestCost: 1, moduleFactorCost: 1 }` in
addition to the existing default. Per-page expectations grew a
`requests`
object encoding distinct request counts for `loose` and `graph` where
they
  differ.
- A new `sandwich` e2e fixture (`/sandwich/a`, `/sandwich/b`) exercises
the
case where two pages share a leading and trailing chunk around a unique
middle stylesheet — including a global stylesheet that the algorithm
must
not leak into unrelated chunk groups. The graph algorithm hits the
optimal
  3 chunks per page on this fixture; loose mode falls short.

#### Documentation

- `ExperimentalConfig.cssChunking` JSDoc describes every accepted shape
and
  what each cost knob does.
- The `style_groups_graph` module-level docs describe the pipeline, cost
  model and constraints with diagrams.

Closes NEXT-

<!-- NEXT_JS_LLM_PR -->

---------
Co-authored-by: 's avatarv-work-app[bot] <262237222+v-work-app[bot]@users.noreply.github.com>
Co-authored-by: 's avatarClaude <noreply@anthropic.com>
Co-authored-by: 's avatarTobias Koppers <sokra@users.noreply.github.com>
parent 7da98e13
......@@ -1594,6 +1594,7 @@ impl Project {
hash_salt: self.next_config().output_hash_salt().to_resolved().await?,
cross_origin: self.next_config().cross_origin(),
chunk_loading_global: self.next_config().turbopack_chunk_loading_global(),
style_groups_algorithm: self.next_config().css_chunking().owned().await?,
}))
}
......@@ -1629,6 +1630,7 @@ impl Project {
asset_prefix: self.next_config().computed_asset_prefix().owned().await?,
css_url_suffix,
hash_salt: self.next_config().output_hash_salt().to_resolved().await?,
style_groups_algorithm: self.next_config().css_chunking().owned().await?,
};
Ok(if client_assets {
get_server_chunking_context_with_client_assets(options)
......@@ -1669,6 +1671,7 @@ impl Project {
css_url_suffix,
hash_salt: self.next_config().output_hash_salt().to_resolved().await?,
cross_origin: self.next_config().cross_origin(),
style_groups_algorithm: self.next_config().css_chunking().owned().await?,
};
Ok(if client_assets {
get_edge_chunking_context_with_client_assets(options)
......
......@@ -23,7 +23,9 @@ use turbopack_core::{
environment::{BrowserEnvironment, Environment, ExecutionEnvironment},
free_var_references,
issue::IssueSeverity,
module_graph::binding_usage_info::OptionBindingUsageInfo,
module_graph::{
binding_usage_info::OptionBindingUsageInfo, style_groups::StyleGroupsAlgorithm,
},
resolve::{parse::Request, pattern::Pattern},
};
use turbopack_css::chunk::CssChunkType;
......@@ -476,6 +478,7 @@ pub struct ClientChunkingContextOptions {
pub hash_salt: ResolvedVc<RcStr>,
pub cross_origin: Vc<CrossOrigin>,
pub chunk_loading_global: Vc<Option<RcStr>>,
pub style_groups_algorithm: StyleGroupsAlgorithm,
}
#[turbo_tasks::function]
......@@ -505,6 +508,7 @@ pub async fn get_client_chunking_context(
hash_salt,
cross_origin,
chunk_loading_global,
style_groups_algorithm,
} = options;
let next_mode = mode.await?;
......@@ -575,6 +579,7 @@ pub async fn get_client_chunking_context(
Vc::<CssChunkType>::default().to_resolved().await?,
ChunkingConfig {
max_merge_chunk_size: 100_000,
style_groups_algorithm: style_groups_algorithm.clone(),
..Default::default()
},
)
......
......@@ -26,6 +26,7 @@ use turbopack_core::{
issue::{
IgnoreIssue, IgnoreIssuePattern, Issue, IssueExt, IssueSeverity, IssueStage, StyledString,
},
module_graph::style_groups::StyleGroupsAlgorithm,
resolve::ResolveAliasMap,
};
use turbopack_ecmascript::{OptionTreeShaking, TreeShakingMode};
......@@ -1040,6 +1041,135 @@ pub struct TurbopackIgnoreIssueRule {
pub description: Option<TurbopackIgnoreIssueTextPattern>,
}
/// `experimental.cssChunking` accepts the following shapes (all normalized to a single canonical
/// object form via [`CssChunkingConfig::normalize`]):
///
/// * `true` — equivalent to `{ type: "loose" }` (default loose behaviour).
/// * `false` — disabled chunking.
/// * `"strict"` / `"loose"` / `"graph"` — string shorthands.
/// * `{ type: "strict" }` / `{ type: "loose" }` — object form for the legacy modes.
/// * `{ type: "graph", requestCost?, moduleFactorCost? }` — object form for the graph algorithm.
#[derive(
Clone, Debug, PartialEq, Deserialize, TraceRawVcs, NonLocalValue, OperationValue, Encode, Decode,
)]
#[serde(untagged)]
pub enum CssChunkingConfig {
Bool(bool),
String(CssChunkingMode),
Object(CssChunkingObject),
}
/// String shorthand variants for [`CssChunkingConfig`].
#[derive(
Clone,
Copy,
Debug,
PartialEq,
Eq,
Deserialize,
TraceRawVcs,
NonLocalValue,
OperationValue,
Encode,
Decode,
)]
#[serde(rename_all = "lowercase")]
pub enum CssChunkingMode {
Strict,
Loose,
Graph,
}
/// Object form of `experimental.cssChunking`.
///
/// `None` is the normalized representation of `false` ("CSS chunking is disabled"). It is not
/// reachable through deserialization — users write `false`, not `{ type: "none" }`.
#[derive(
Clone, Debug, PartialEq, Deserialize, TraceRawVcs, NonLocalValue, OperationValue, Encode, Decode,
)]
#[serde(tag = "type", rename_all = "lowercase")]
pub enum CssChunkingObject {
#[serde(skip)]
None,
Strict,
Loose,
Graph(CssChunkingGraphOptions),
}
/// Cost parameters for the graph algorithm. See [`CssChunkingConfig`] for details.
#[derive(
Clone,
Debug,
Default,
PartialEq,
Deserialize,
TraceRawVcs,
NonLocalValue,
OperationValue,
Encode,
Decode,
)]
#[serde(rename_all = "camelCase")]
pub struct CssChunkingGraphOptions {
pub request_cost: Option<f32>,
pub module_factor_cost: Option<f32>,
}
impl CssChunkingConfig {
/// Normalize all input shapes (booleans, strings, object form) to the canonical object form.
/// `false` maps to [`CssChunkingObject::None`]; `true` is equivalent to `'loose'`.
pub fn normalize(&self) -> CssChunkingObject {
match self {
CssChunkingConfig::Bool(false) => CssChunkingObject::None,
CssChunkingConfig::Bool(true) => CssChunkingObject::Loose,
CssChunkingConfig::String(CssChunkingMode::Strict) => CssChunkingObject::Strict,
CssChunkingConfig::String(CssChunkingMode::Loose) => CssChunkingObject::Loose,
CssChunkingConfig::String(CssChunkingMode::Graph) => {
CssChunkingObject::Graph(CssChunkingGraphOptions::default())
}
CssChunkingConfig::Object(obj) => obj.clone(),
}
}
}
/// Default `requestCost` for the graph algorithm (in bytes).
const DEFAULT_REQUEST_COST: f32 = 20_000.0;
/// Default `moduleFactorCost` for the graph algorithm.
const DEFAULT_MODULE_FACTOR_COST: f32 = 1.0;
/// Resolve `experimental.cssChunking` to the [`StyleGroupsAlgorithm`] Turbopack should use.
///
/// `strict` and `false` (`CssChunkingObject::None`) are bundler-incompatible with Turbopack and
/// are rejected at config-validation time on the JS side; if one slips through, we bail rather
/// than silently falling back. `loose` and `true` map to [`StyleGroupsAlgorithm::Default`].
fn resolve_css_chunking_algorithm(
config: Option<&CssChunkingConfig>,
) -> Result<StyleGroupsAlgorithm> {
let Some(config) = config else {
return Ok(StyleGroupsAlgorithm::Default);
};
Ok(match config.normalize() {
CssChunkingObject::None => {
anyhow::bail!(
"`experimental.cssChunking: false` is not supported by Turbopack; this should \
have been rejected at config validation time"
)
}
CssChunkingObject::Strict => {
anyhow::bail!(
"`experimental.cssChunking: \"strict\"` is not supported by Turbopack; this \
should have been rejected at config validation time"
)
}
CssChunkingObject::Loose => StyleGroupsAlgorithm::Default,
CssChunkingObject::Graph(opts) => StyleGroupsAlgorithm::graph(
opts.request_cost.unwrap_or(DEFAULT_REQUEST_COST),
opts.module_factor_cost
.unwrap_or(DEFAULT_MODULE_FACTOR_COST),
),
})
}
#[derive(
Clone,
Debug,
......@@ -1097,6 +1227,9 @@ pub struct ExperimentalConfig {
/// no salt.
output_hash_salt: Option<RcStr>,
/// CSS chunking strategy. See [`CssChunkingConfig`] for the accepted shapes.
css_chunking: Option<CssChunkingConfig>,
// ---
// UNSUPPORTED
// ---
......@@ -1817,6 +1950,13 @@ impl NextConfig {
Vc::cell(self.experimental.inline_css.unwrap_or(false))
}
/// Resolve `experimental.cssChunking` to a [`StyleGroupsAlgorithm`] (with defaults applied
/// for the cost parameters of the graph algorithm).
#[turbo_tasks::function]
pub fn css_chunking(&self) -> Result<Vc<StyleGroupsAlgorithm>> {
Ok(resolve_css_chunking_algorithm(self.experimental.css_chunking.as_ref())?.cell())
}
#[turbo_tasks::function]
pub fn mdx_rs(&self) -> Vc<OptionalMdxTransformOptions> {
let options = &self.experimental.mdx_rs;
......
......@@ -13,7 +13,9 @@ use turbopack_core::{
environment::{EdgeWorkerEnvironment, Environment, ExecutionEnvironment, NodeJsVersion},
free_var_references,
issue::IssueSeverity,
module_graph::binding_usage_info::OptionBindingUsageInfo,
module_graph::{
binding_usage_info::OptionBindingUsageInfo, style_groups::StyleGroupsAlgorithm,
},
};
use turbopack_css::chunk::CssChunkType;
use turbopack_ecmascript::chunk::EcmascriptChunkType;
......@@ -202,6 +204,7 @@ pub struct EdgeChunkingContextOptions {
pub css_url_suffix: Vc<Option<RcStr>>,
pub hash_salt: ResolvedVc<RcStr>,
pub cross_origin: Vc<CrossOrigin>,
pub style_groups_algorithm: StyleGroupsAlgorithm,
}
/// Like `get_edge_chunking_context` but all assets are emitted as client assets (so `/_next`)
......@@ -229,6 +232,7 @@ pub async fn get_edge_chunking_context_with_client_assets(
css_url_suffix,
hash_salt,
cross_origin,
style_groups_algorithm,
} = options;
let cross_origin_loading = *cross_origin.await?;
let output_root = node_root.join("server/edge")?;
......@@ -280,6 +284,7 @@ pub async fn get_edge_chunking_context_with_client_assets(
Vc::<CssChunkType>::default().to_resolved().await?,
ChunkingConfig {
max_merge_chunk_size: 100_000,
style_groups_algorithm: style_groups_algorithm.clone(),
..Default::default()
},
)
......@@ -314,6 +319,7 @@ pub async fn get_edge_chunking_context(
css_url_suffix,
hash_salt,
cross_origin,
style_groups_algorithm,
} = options;
let cross_origin = *cross_origin.await?;
let css_url_suffix = css_url_suffix.to_resolved().await?;
......@@ -382,6 +388,7 @@ pub async fn get_edge_chunking_context(
Vc::<CssChunkType>::default().to_resolved().await?,
ChunkingConfig {
max_merge_chunk_size: 100_000,
style_groups_algorithm: style_groups_algorithm.clone(),
..Default::default()
},
)
......
......@@ -22,7 +22,9 @@ use turbopack_core::{
compile_time_info::{CompileTimeDefines, CompileTimeInfo, FreeVarReferences},
environment::{Environment, ExecutionEnvironment, NodeJsEnvironment, NodeJsVersion},
issue::IssueSeverity,
module_graph::binding_usage_info::OptionBindingUsageInfo,
module_graph::{
binding_usage_info::OptionBindingUsageInfo, style_groups::StyleGroupsAlgorithm,
},
target::CompileTarget,
};
use turbopack_css::chunk::CssChunkType;
......@@ -1021,6 +1023,7 @@ pub struct ServerChunkingContextOptions {
pub asset_prefix: RcStr,
pub css_url_suffix: Vc<Option<RcStr>>,
pub hash_salt: ResolvedVc<RcStr>,
pub style_groups_algorithm: StyleGroupsAlgorithm,
}
/// Like `get_server_chunking_context` but all assets are emitted as client assets (so `/_next`)
......@@ -1048,6 +1051,7 @@ pub async fn get_server_chunking_context_with_client_assets(
asset_prefix,
css_url_suffix,
hash_salt,
style_groups_algorithm,
} = options;
let css_url_suffix = css_url_suffix.to_resolved().await?;
......@@ -1117,6 +1121,7 @@ pub async fn get_server_chunking_context_with_client_assets(
Vc::<CssChunkType>::default().to_resolved().await?,
ChunkingConfig {
max_merge_chunk_size: 100_000,
style_groups_algorithm: style_groups_algorithm.clone(),
..Default::default()
},
)
......@@ -1151,6 +1156,7 @@ pub async fn get_server_chunking_context(
asset_prefix,
css_url_suffix,
hash_salt,
style_groups_algorithm,
} = options;
let css_url_suffix = css_url_suffix.to_resolved().await?;
let next_mode = mode.await?;
......@@ -1221,6 +1227,7 @@ pub async fn get_server_chunking_context(
Vc::<CssChunkType>::default().to_resolved().await?,
ChunkingConfig {
max_merge_chunk_size: 100_000,
style_groups_algorithm: style_groups_algorithm.clone(),
..Default::default()
},
)
......
......@@ -1244,5 +1244,8 @@
"1243": "This \"use cache\" has a dynamic cache life that was propagated to its parent.",
"1244": "A \"use cache\" with short \\`expire\\` (under 5 minutes) is nested inside another \"use cache\" that has no explicit \\`cacheLife\\`, which is not allowed during prerendering. Add \\`cacheLife()\\` to the outer \"use cache\" to choose whether it should be prerendered (with longer \\`expire\\`) or remain dynamic (with short \\`expire\\`). Read more: https://nextjs.org/docs/messages/nested-use-cache-no-explicit-cachelife",
"1245": "A \"use cache\" with zero \\`revalidate\\` is nested inside another \"use cache\" that has no explicit \\`cacheLife\\`, which is not allowed during prerendering. Add \\`cacheLife()\\` to the outer \"use cache\" to choose whether it should be prerendered (with non-zero \\`revalidate\\`) or remain dynamic (with zero \\`revalidate\\`). Read more: https://nextjs.org/docs/messages/nested-use-cache-no-explicit-cachelife",
"1246": "Could not validate instant UI because an expected segment was not rendered."
"1246": "Could not validate instant UI because an expected segment was not rendered.",
"1247": "\\`experimental.cssChunking: \"graph\"\\` is only supported with Turbopack. Please remove the option or run Next.js with Turbopack in %s.",
"1248": "\\`experimental.cssChunking: \"strict\"\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s.",
"1249": "\\`experimental.cssChunking: false\\` is only supported with webpack. Please remove the option or run Next.js with webpack in %s."
}
......@@ -32,6 +32,7 @@ import {
import type { CompilerNameValues } from '../shared/lib/constants'
import { execOnce } from '../shared/lib/utils'
import type { NextConfigComplete } from '../server/config-shared'
import { resolveCssChunkingMode } from '../server/config-shared'
import { finalizeEntrypoint } from './entries'
import * as Log from './output/log'
import { buildConfiguration } from './webpack/config'
......@@ -2188,17 +2189,21 @@ export default async function getBaseWebpackConfig(
new NextFontManifestPlugin({
appDir,
}),
// CSS chunking plugin. Graph mode is Turbopack-only and is rejected at config-validation
// time for webpack, so we only need to wire up `'loose'` (default) and `'strict'` here.
!dev &&
isClient &&
config.experimental.cssChunking &&
(isRspack
? new (getRspackCore().experiments.CssChunkingPlugin)({
strict: config.experimental.cssChunking === 'strict',
nextjs: true,
})
: new CssChunkingPlugin(
config.experimental.cssChunking === 'strict'
)),
(() => {
const mode = resolveCssChunkingMode(config.experimental.cssChunking)
if (mode !== 'loose' && mode !== 'strict') return false
const strict = mode === 'strict'
return isRspack
? new (getRspackCore().experiments.CssChunkingPlugin)({
strict,
nextjs: true,
})
: new CssChunkingPlugin(strict)
})(),
telemetryPlugin,
!dev &&
isNodeServer &&
......
......@@ -272,7 +272,21 @@ export const experimentalSchema = {
middlewareClientMaxBodySize: zSizeLimit.optional(),
proxyClientMaxBodySize: zSizeLimit.optional(),
multiZoneDraftMode: z.boolean().optional(),
cssChunking: z.union([z.boolean(), z.literal('strict')]).optional(),
cssChunking: z
.union([
z.boolean(),
z.literal('strict'),
z.literal('loose'),
z.literal('graph'),
z.strictObject({ type: z.literal('strict') }),
z.strictObject({ type: z.literal('loose') }),
z.strictObject({
type: z.literal('graph'),
requestCost: z.number().nonnegative().finite().optional(),
moduleFactorCost: z.number().nonnegative().finite().optional(),
}),
])
.optional(),
nextScriptWorkers: z.boolean().optional(),
// The critter option is unknown, use z.any() here
optimizeCss: z.union([z.boolean(), z.any()]).optional(),
......
......@@ -405,6 +405,40 @@ export interface LightningCssFeatures {
exclude?: LightningCssFeature[]
}
/**
* Accepted shapes for `experimental.cssChunking`. See [`ExperimentalConfig.cssChunking`] for the
* accepted values; use [`resolveCssChunkingMode`] to normalize the value at runtime.
*/
export type CssChunkingConfig =
| boolean
| 'strict'
| 'loose'
| 'graph'
| { type: 'strict' }
| { type: 'loose' }
| { type: 'graph'; requestCost?: number; moduleFactorCost?: number }
/**
* Normalize any [`CssChunkingConfig`] value to one of the four modes the build pipeline cares
* about:
* - `'off'` — `false`/`undefined`: do not run a CSS chunking plugin.
* - `'loose'` — `true` / `'loose'` / `{ type: 'loose' }`: heuristic-based chunking
* (the default).
* - `'strict'` — `'strict'` / `{ type: 'strict' }`: webpack-only ordered-chunking plugin.
* - `'graph'` — `'graph'` / `{ type: 'graph', … }`: Turbopack-only graph algorithm.
*/
export function resolveCssChunkingMode(
value: CssChunkingConfig | undefined
): 'off' | 'loose' | 'strict' | 'graph' {
if (value === undefined || value === false) return 'off'
if (value === true || value === 'loose') return 'loose'
if (value === 'strict' || value === 'graph') return value
// Object form. `requestCost` and `moduleFactorCost` are validated by the schema.
if (value.type === 'strict') return 'strict'
if (value.type === 'graph') return 'graph'
return 'loose'
}
export interface ExperimentalConfig {
/**
* A string that is incorporated into content-addressed output filenames
......@@ -508,12 +542,27 @@ export interface ExperimentalConfig {
proxyPrefetch?: 'strict' | 'flexible'
manualClientBasePath?: boolean
/**
* CSS Chunking strategy. Defaults to `true` ("loose" mode), which guesses dependencies
* between CSS files to keep ordering of them.
* An alternative is 'strict', which will try to keep correct ordering as
* much as possible, even when this leads to many requests.
*/
cssChunking?: boolean | 'strict'
* CSS Chunking strategy. Defaults to `true` (loose mode), which guesses dependencies between
* CSS files to keep ordering of them.
*
* - `true` / `'loose'` / `{ type: 'loose' }` — default heuristic-based chunking.
* - `'strict'` / `{ type: 'strict' }` — preserve correct ordering as much as possible, even
* when this leads to many requests. Webpack only.
* - `false` — disable chunking; emit one chunk per CSS module. Webpack only.
* - `'graph'` / `{ type: 'graph', requestCost?, moduleFactorCost? }` — Turbopack only.
* Selects a CSS chunking strategy that analyzes the most common style orderings across the
* application and produces shared chunks accordingly. Compared to the default mode it
* intentionally overships some styles in order to reduce the number of CSS requests per
* page. Cost overrides:
* - `requestCost` (bytes, default `20000`) — additional cost charged for every CSS
* request a chunk group makes. Larger values bias the algorithm toward fewer, larger
* shared chunks; smaller values toward more, smaller chunks.
* - `moduleFactorCost` (default `1`) — controls how much the algorithm cares about
* small chunk groups. `0` distributes overshipped bytes evenly across chunk groups.
* Higher values penalize overshipping in small chunk groups proportionally more, so
* small pages ship fewer unrelated styles at the expense of more requests overall.
*/
cssChunking?: CssChunkingConfig
disablePostcssPresetEnv?: boolean
cpus?: number
memoryBasedWorkersCount?: boolean
......
......@@ -13,7 +13,11 @@ import {
PHASE_PRODUCTION_SERVER,
type PHASE_TYPE,
} from '../shared/lib/constants'
import { defaultConfig, normalizeConfig } from './config-shared'
import {
defaultConfig,
normalizeConfig,
resolveCssChunkingMode,
} from './config-shared'
import type {
ExperimentalConfig,
NextConfigComplete,
......@@ -456,6 +460,35 @@ function assignDefaultsAndValidate(
)
}
// Validate experimental.cssChunking compatibility with the active bundler. Graph mode is
// Turbopack-only; strict mode and `false` (single-chunk-per-module) are webpack-only.
// Only validate during build/dev — `next start` doesn't pick a bundler and would otherwise
// see `process.env.TURBOPACK` unset and reject a valid `cssChunking: "graph"` config.
if (phase !== PHASE_PRODUCTION_SERVER) {
const cssChunkingValue = result.experimental.cssChunking
const cssChunkingMode = resolveCssChunkingMode(cssChunkingValue)
if (cssChunkingMode === 'graph' && !process.env.TURBOPACK) {
throw new Error(
`\`experimental.cssChunking: "graph"\` is only supported with Turbopack. ` +
`Please remove the option or run Next.js with Turbopack in ${configFileName}.`
)
}
if (cssChunkingMode === 'strict' && process.env.TURBOPACK) {
throw new Error(
`\`experimental.cssChunking: "strict"\` is only supported with webpack. ` +
`Please remove the option or run Next.js with webpack in ${configFileName}.`
)
}
// Only error when `false` was set explicitly. `undefined` (the default) also resolves to
// `'off'` but that's the implicit default and must not error on Turbopack.
if (cssChunkingValue === false && process.env.TURBOPACK) {
throw new Error(
`\`experimental.cssChunking: false\` is only supported with webpack. ` +
`Please remove the option or run Next.js with webpack in ${configFileName}.`
)
}
}
if (result.experimental.cachedNavigations && !result.cacheComponents) {
throw new Error(
`\`experimental.cachedNavigations\` requires \`cacheComponents\` to be enabled. Please update your ${configFileName} accordingly.`
......
......@@ -86,6 +86,16 @@ export default function Nav() {
Partial Reversed B
</Link>
</li>
<li>
<Link href={'/sandwich/a'} id="sandwich-a" prefetch={false}>
Sandwich A
</Link>
</li>
<li>
<Link href={'/sandwich/b'} id="sandwich-b" prefetch={false}>
Sandwich B
</Link>
</li>
<li>
<Link href={'/global-first'} id="global-first" prefetch={false}>
Global First
......
import shared1 from '../shared1.module.css'
import uniqueA from '../uniqueA.module.css'
import shared2 from '../shared2.module.css'
import Nav from '../../nav'
export default function Page() {
return (
<div>
<p
className={`${shared1.name} ${uniqueA.name} ${shared2.name}`}
id="hellosba"
>
hello world
</p>
<Nav />
</div>
)
}
import shared1 from '../shared1.module.css'
import '../uniqueB.css'
import shared2 from '../shared2.module.css'
import Nav from '../../nav'
export default function Page() {
return (
<div>
<p
className={`${shared1.name} sandwich-b-marker ${shared2.name}`}
id="hellosbb"
>
hello world
</p>
<Nav />
</div>
)
}
/* Global CSS used by `/sandwich/b` only. Its purpose is to prevent the chunking algorithm from
collapsing all sandwich styles into one shared chunk: a global stylesheet must not be loaded by
chunk groups that don't import it (`/sandwich/a`), so the algorithm has to keep `uniqueB`
isolated. */
.sandwich-b-marker {
outline: 1px solid rgb(255, 128, 0);
}
......@@ -9,7 +9,10 @@ use crate::{
ChunkItemBatchGroup, ChunkItemWithAsyncModuleInfo, ChunkingConfig, ChunkingContext,
chunking::{ChunkItemOrBatchWithInfo, SplitContext, make_chunk},
},
module_graph::{ModuleGraph, style_groups::StyleGroupsConfig},
module_graph::{
ModuleGraph,
style_groups::{StyleGroups, StyleGroupsConfig, StyleItemInfo},
},
};
pub async fn make_style_production_chunks(
......@@ -30,12 +33,22 @@ pub async fn make_style_production_chunks(
*chunking_context,
StyleGroupsConfig {
max_chunk_size: chunking_config.max_merge_chunk_size,
algorithm: chunking_config.style_groups_algorithm.clone(),
},
)
.await?;
// Flatten the input to a sequence of (chunk item, info) pairs (preserving input order
// as the tie-breaker for items without an explicit `order`), then stably sort by
// `StyleItemInfo::order`. Each item's `StyleItemInfo` is fetched once here so the loop
// below doesn't have to re-query the map.
let flat_items = flatten_and_sort(chunk_items, &style_groups).await?;
let mut handled = FxHashSet::default();
let mut handle_chunk_item = async |chunk_item: &ChunkItemWithAsyncModuleInfo| {
if let Some(&batch) = style_groups.shared_chunk_items.get(chunk_item) {
for (chunk_item, info) in &flat_items {
if let Some(info) = info
&& let Some(batch) = info.batch
{
if handled.insert(batch) {
make_chunk(
vec![&ChunkItemOrBatchWithInfo::Batch { batch, size: 0 }],
......@@ -45,32 +58,19 @@ pub async fn make_style_production_chunks(
)
.await?;
}
} else {
make_chunk(
vec![&ChunkItemOrBatchWithInfo::ChunkItem {
chunk_item: *chunk_item,
size: 0,
asset_ident: rcstr!(""),
}],
vec![],
&mut String::new(),
&mut split_context,
)
.await?;
continue;
}
anyhow::Ok(())
};
for chunk_item in chunk_items {
match chunk_item {
ChunkItemOrBatchWithInfo::ChunkItem { chunk_item, .. } => {
handle_chunk_item(chunk_item).await?;
}
ChunkItemOrBatchWithInfo::Batch { batch, .. } => {
for chunk_item in &batch.await?.chunk_items {
handle_chunk_item(chunk_item).await?;
}
}
};
make_chunk(
vec![&ChunkItemOrBatchWithInfo::ChunkItem {
chunk_item: *chunk_item,
size: 0,
asset_ident: rcstr!(""),
}],
vec![],
&mut String::new(),
&mut split_context,
)
.await?;
}
Ok(())
......@@ -78,3 +78,37 @@ pub async fn make_style_production_chunks(
.instrument(span_outer)
.await
}
/// Flatten input batches into a single ordered list of `(chunk_item, info)` pairs and stably
/// sort by `StyleItemInfo::order`. In practice each [`StyleGroups`] result is uniform:
/// * the loose algorithm produces all `None` orders, so the sort is a no-op and items keep their
/// input position;
/// * the graph algorithm produces all `Some(_)` orders (including for singleton chunks; see
/// [`crate::module_graph::style_groups_graph::compute_style_groups_graph`]), so the sort key
/// fully determines the final order and any missing-from-map sentinel can't slip in.
///
/// Returns the `StyleItemInfo` reference for each item so the caller can avoid re-querying
/// `style_groups.shared_chunk_items`.
async fn flatten_and_sort<'a>(
chunk_items: Vec<&ChunkItemOrBatchWithInfo>,
style_groups: &'a StyleGroups,
) -> Result<Vec<(ChunkItemWithAsyncModuleInfo, Option<&'a StyleItemInfo>)>> {
let mut flat_items: Vec<(ChunkItemWithAsyncModuleInfo, Option<&'a StyleItemInfo>)> =
Vec::with_capacity(chunk_items.len());
for chunk_item in chunk_items {
match chunk_item {
ChunkItemOrBatchWithInfo::ChunkItem { chunk_item, .. } => {
let info = style_groups.shared_chunk_items.get(chunk_item);
flat_items.push((*chunk_item, info));
}
ChunkItemOrBatchWithInfo::Batch { batch, .. } => {
for chunk_item in &batch.await?.chunk_items {
let info = style_groups.shared_chunk_items.get(chunk_item);
flat_items.push((*chunk_item, info));
}
}
}
}
flat_items.sort_by_key(|(_, info)| info.and_then(|i| i.order));
Ok(flat_items)
}
......@@ -20,7 +20,7 @@ use crate::{
module::Module,
module_graph::{
ModuleGraph, binding_usage_info::ModuleExportUsage, chunk_group_info::ChunkGroup,
module_batches::BatchingConfig,
module_batches::BatchingConfig, style_groups::StyleGroupsAlgorithm,
},
output::{
ExpandOutputAssetsInput, OutputAsset, OutputAssets, OutputAssetsReferences,
......@@ -274,6 +274,11 @@ pub struct ChunkingConfig {
/// This makes sure that code in big chunks is not duplicated in multiple chunks.
pub max_merge_chunk_size: usize,
/// Selects the algorithm used to compute
/// [`crate::module_graph::style_groups::StyleGroups`]. Only consulted for the CSS chunk
/// type.
pub style_groups_algorithm: StyleGroupsAlgorithm,
#[allow(dead_code)]
pub placeholder_for_future_extensions: (),
}
......
......@@ -35,7 +35,9 @@ use crate::{
chunk_group_info::{ChunkGroupEntry, ChunkGroupInfo, compute_chunk_group_info},
merged_modules::{MergedModuleInfo, compute_merged_modules},
module_batches::{ModuleBatchesGraph, compute_module_batches},
style_groups::{StyleGroups, StyleGroupsConfig, compute_style_groups},
style_groups::{StyleGroups, StyleGroupsAlgorithm, StyleGroupsConfig},
style_groups_graph::compute_style_groups_graph,
style_groups_loose::compute_style_groups,
traced_di_graph::TracedDiGraph,
},
reference::{ModuleReference, primary_chunkable_referenced_modules},
......@@ -49,7 +51,9 @@ pub mod merged_modules;
pub mod module_batch;
pub(crate) mod module_batches;
mod side_effect_module_info;
pub(crate) mod style_groups;
pub mod style_groups;
pub mod style_groups_graph;
pub mod style_groups_loose;
mod traced_di_graph;
pub use self::module_batches::BatchingConfig;
......@@ -760,7 +764,24 @@ impl ModuleGraph {
chunking_context: Vc<Box<dyn ChunkingContext>>,
config: StyleGroupsConfig,
) -> Result<Vc<StyleGroups>> {
compute_style_groups(self, chunking_context, &config).await
match &config.algorithm {
StyleGroupsAlgorithm::Default => {
compute_style_groups(self, chunking_context, &config).await
}
StyleGroupsAlgorithm::Graph {
module_factor_cost,
request_cost,
} => {
compute_style_groups_graph(
self,
chunking_context,
request_cost.get(),
module_factor_cost.get(),
config.max_chunk_size as u64,
)
.await
}
}
}
#[turbo_tasks::function(root)]
......
//! `SubgraphView`: a borrow-only filtered view over a [`petgraph::graph::DiGraph`] driven by a
//! [`rustc_hash::FxHashSet`] of node indices.
//!
//! The PoC algorithms ([`super::algorithm`]) accept any type that implements [`ReadonlyGraph`].
//! That lets us pass either a `&DiGraph` directly or a `SubgraphView` restricted to e.g. one
//! SCC, without cloning the underlying graph.
use std::marker::PhantomData;
use petgraph::{
Direction,
graph::{DiGraph, NodeIndex},
};
use rustc_hash::FxHashSet;
/// Read-only view over a directed weighted graph. Implemented for `&DiGraph<N, u32>` and for
/// [`SubgraphView`].
#[allow(dead_code)] // Some methods are kept for symmetry with the JS PoC; not all are used yet.
pub(super) trait ReadonlyGraph<'a>: Copy {
type NodesIter: Iterator<Item = NodeIndex>;
type OutgoingIter: Iterator<Item = NodeIndex>;
type IncomingIter: Iterator<Item = NodeIndex>;
type OutgoingWithWeightIter: Iterator<Item = (NodeIndex, u32)>;
type IncomingWithWeightIter: Iterator<Item = (NodeIndex, u32)>;
fn nodes(self) -> Self::NodesIter;
fn node_count(self) -> usize;
/// Upper bound on `NodeIndex::index()` values returned by this view. Always equals the
/// underlying [`DiGraph`]'s node count, regardless of any subset filtering. Useful for
/// sizing scratch arrays keyed by node id.
fn index_bound(self) -> usize;
fn outgoing_edges(self, node: NodeIndex) -> Self::OutgoingIter;
fn outgoing_edges_with_weight(self, node: NodeIndex) -> Self::OutgoingWithWeightIter;
fn incoming_edges(self, node: NodeIndex) -> Self::IncomingIter;
fn incoming_edges_with_weight(self, node: NodeIndex) -> Self::IncomingWithWeightIter;
}
impl<'a, N: 'a> ReadonlyGraph<'a> for &'a DiGraph<N, u32> {
type NodesIter = petgraph::graph::NodeIndices<u32>;
type OutgoingIter = petgraph::graph::Neighbors<'a, u32>;
type IncomingIter = petgraph::graph::Neighbors<'a, u32>;
type OutgoingWithWeightIter = NeighborsWithWeight<'a, N>;
type IncomingWithWeightIter = NeighborsWithWeight<'a, N>;
fn nodes(self) -> Self::NodesIter {
self.node_indices()
}
fn node_count(self) -> usize {
DiGraph::node_count(self)
}
fn index_bound(self) -> usize {
DiGraph::node_count(self)
}
fn outgoing_edges(self, node: NodeIndex) -> Self::OutgoingIter {
self.neighbors_directed(node, Direction::Outgoing)
}
fn outgoing_edges_with_weight(self, node: NodeIndex) -> Self::OutgoingWithWeightIter {
NeighborsWithWeight {
graph: self,
iter: self.neighbors_directed(node, Direction::Outgoing).detach(),
_n: PhantomData,
}
}
fn incoming_edges(self, node: NodeIndex) -> Self::IncomingIter {
self.neighbors_directed(node, Direction::Incoming)
}
fn incoming_edges_with_weight(self, node: NodeIndex) -> Self::IncomingWithWeightIter {
NeighborsWithWeight {
graph: self,
iter: self.neighbors_directed(node, Direction::Incoming).detach(),
_n: PhantomData,
}
}
}
/// Iterator over a node's neighbors plus the weight of each edge.
pub(super) struct NeighborsWithWeight<'a, N> {
graph: &'a DiGraph<N, u32>,
iter: petgraph::graph::WalkNeighbors<u32>,
_n: PhantomData<N>,
}
impl<'a, N> Iterator for NeighborsWithWeight<'a, N> {
type Item = (NodeIndex, u32);
fn next(&mut self) -> Option<Self::Item> {
let (edge, target) = self.iter.next(self.graph)?;
Some((target, *self.graph.edge_weight(edge).unwrap()))
}
}
/// A live view over `graph` restricted to the nodes in `subset`. Edges whose source or target
/// is outside the subset are filtered out on iteration.
pub(super) struct SubgraphView<'a, N> {
graph: &'a DiGraph<N, u32>,
subset: &'a FxHashSet<NodeIndex>,
}
impl<'a, N> SubgraphView<'a, N> {
pub(super) fn new(graph: &'a DiGraph<N, u32>, subset: &'a FxHashSet<NodeIndex>) -> Self {
Self { graph, subset }
}
}
impl<'a, N> Clone for SubgraphView<'a, N> {
fn clone(&self) -> Self {
*self
}
}
impl<'a, N> Copy for SubgraphView<'a, N> {}
impl<'a, N: 'a> ReadonlyGraph<'a> for SubgraphView<'a, N> {
type NodesIter = SubgraphNodes<'a>;
type OutgoingIter = SubgraphNeighbors<'a, N>;
type IncomingIter = SubgraphNeighbors<'a, N>;
type OutgoingWithWeightIter = SubgraphNeighborsWithWeight<'a, N>;
type IncomingWithWeightIter = SubgraphNeighborsWithWeight<'a, N>;
fn nodes(self) -> Self::NodesIter {
SubgraphNodes {
iter: self.subset.iter(),
}
}
fn node_count(self) -> usize {
// Nodes are never removed from the graph, so every subset element is valid.
self.subset.len()
}
fn index_bound(self) -> usize {
self.graph.node_count()
}
fn outgoing_edges(self, node: NodeIndex) -> Self::OutgoingIter {
SubgraphNeighbors {
iter: if self.subset.contains(&node) {
Some(self.graph.neighbors_directed(node, Direction::Outgoing))
} else {
None
},
subset: self.subset,
_n: PhantomData,
}
}
fn outgoing_edges_with_weight(self, node: NodeIndex) -> Self::OutgoingWithWeightIter {
SubgraphNeighborsWithWeight {
graph: self.graph,
iter: if self.subset.contains(&node) {
Some(
self.graph
.neighbors_directed(node, Direction::Outgoing)
.detach(),
)
} else {
None
},
subset: self.subset,
_n: PhantomData,
}
}
fn incoming_edges(self, node: NodeIndex) -> Self::IncomingIter {
SubgraphNeighbors {
iter: if self.subset.contains(&node) {
Some(self.graph.neighbors_directed(node, Direction::Incoming))
} else {
None
},
subset: self.subset,
_n: PhantomData,
}
}
fn incoming_edges_with_weight(self, node: NodeIndex) -> Self::IncomingWithWeightIter {
SubgraphNeighborsWithWeight {
graph: self.graph,
iter: if self.subset.contains(&node) {
Some(
self.graph
.neighbors_directed(node, Direction::Incoming)
.detach(),
)
} else {
None
},
subset: self.subset,
_n: PhantomData,
}
}
}
pub(super) struct SubgraphNodes<'a> {
iter: std::collections::hash_set::Iter<'a, NodeIndex>,
}
impl<'a> Iterator for SubgraphNodes<'a> {
type Item = NodeIndex;
fn next(&mut self) -> Option<Self::Item> {
self.iter.next().copied()
}
}
pub(super) struct SubgraphNeighbors<'a, N> {
iter: Option<petgraph::graph::Neighbors<'a, u32>>,
subset: &'a FxHashSet<NodeIndex>,
_n: PhantomData<N>,
}
impl<'a, N> Iterator for SubgraphNeighbors<'a, N> {
type Item = NodeIndex;
fn next(&mut self) -> Option<Self::Item> {
let it = self.iter.as_mut()?;
it.by_ref().find(|n| self.subset.contains(n))
}
}
pub(super) struct SubgraphNeighborsWithWeight<'a, N> {
graph: &'a DiGraph<N, u32>,
iter: Option<petgraph::graph::WalkNeighbors<u32>>,
subset: &'a FxHashSet<NodeIndex>,
_n: PhantomData<N>,
}
impl<'a, N> Iterator for SubgraphNeighborsWithWeight<'a, N> {
type Item = (NodeIndex, u32);
fn next(&mut self) -> Option<Self::Item> {
let it = self.iter.as_mut()?;
while let Some((edge, target)) = it.next(self.graph) {
if self.subset.contains(&target) {
return Some((target, *self.graph.edge_weight(edge).unwrap()));
}
}
None
}
}
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment