Skip to content

perf(css): struct-of-arrays AST for the streaming CSS parser#21285

Open
alexander-akait wants to merge 17 commits into
mainfrom
perf/css-struct-of-arrays-parser
Open

perf(css): struct-of-arrays AST for the streaming CSS parser#21285
alexander-akait wants to merge 17 commits into
mainfrom
perf/css-struct-of-arrays-parser

Conversation

@alexander-akait

Copy link
Copy Markdown
Member

Summary

The CSS parser allocated a class instance per AST node on the hot parse path, so large stylesheets are GC-bound. This reworks the streaming parser to a struct-of-arrays representation — node fields live in reused typed arrays with no per-node objects — behind an accessor seam, so CssParser is unchanged; it also trims redundant per-node value/name slices outside CSS Modules. On compiled Tailwind (3.3 MiB, ~478k nodes) a non-Modules parse is ~26% faster using ~47% less memory, and CSS Modules ~11% faster / ~39% less.

What kind of change does this PR introduce?

perf

Did you add tests for your changes?

No new cases — the change is behavior-preserving and covered by the existing suites (654 configCases/css, plus the parser unit tests); I updated test/walkCssTokensParser.unittest.js to read nodes through the accessor seam.

Does this PR introduce a breaking change?

No.

If relevant, what needs to be documented once your changes are merged or what have you already documented?

n/a — internal parser change, no public API or config surface.

Use of AI

Yes. Developed with Claude Code: it designed the struct-of-arrays representation, ported the CssParser consumer onto the accessor seam, profiled and benchmarked each change, and gated every commit on the CSS test suites. All output was reviewed and validated before submission.


Generated by Claude Code

Profile-driven changes to the CSS tokenizer/parser hot path:

- consumeAToken: replace the switch over sparse lead code points with a
  precomputed char-class dispatch table (one Uint8Array load + a dense
  jump table). Idents — the most frequent lead — dispatch directly
  instead of falling through the digit/whitespace cases. This was the
  single hottest function (~17% of parse time).

- Collapse the five non-leaf node types (function, simple block,
  declaration, at-rule, qualified rule) into one Container class with a
  fixed field layout, so the walker's .type / .value loads see four node
  shapes instead of eight — back inside V8's polymorphic inline-cache
  limit (the profile showed ~5% in LoadIC_Megamorphic).

- Drop the per-token _value cache slot: derive value from the byte range
  on read, re-derive hash id-ness from the source, and keep only url's
  content offsets. Leaf tokens are ~94% of nodes, so removing the slot
  is the bulk of the memory win.

Net on a streaming parse+walk benchmark: ~5% faster and ~5% less
retained AST memory. AST output is byte-identical (same nodes, ranges,
and lazy getter results).
Add a spec-mapped reference (CSS Syntax Level 3 §4) above `_charClass`
explaining why the per-character dispatch table is used and listing which
code points map to each handler class, so future spec changes are easy to
locate and apply.
`_consumeAnIdentSequence` runs per code point of every ident, at-keyword,
hash, function name and unit — the hottest tokenizer function on a large
real-world build (Tailwind v4). Inline the two per-char checks: the ASCII
ident test becomes a direct table load (no `_isIdentCodePoint` call), and
the terminating escape test reads the next code point only when the char
is a backslash instead of eagerly via `_ifTwoCodePointsAreValidEscape`.

~1.7% faster on lex-only over the Tailwind build; token output unchanged.
Annotate the `consumeAToken` char-class switch so each case states which
CSS Syntax §4 token(s) it yields (and why `-`/`+`/`.`/`#`/`@`/`<`/`\\` branch
further), making the optimized dispatch self-documenting.
consumeAComponentValue is called for every component value (the bulk of
nodes on a large stylesheet). Two redundancies removed:

- It re-called ts.next() even though every caller had already peeked that
  token; thread the peeked token in (default ts.next() for the few callers
  that don't) so the common loops skip the extra call.
- The leaf-token branch delegated to consumeATokenAsNode, which peeked the
  token a third time via ts.consume(); inline it (advance + tokenToNode on
  the token we already hold).

~2% faster on a Tailwind v4 build (CPU-isolated); token/AST output
unchanged.
tokenToNode was a ~20-arm switch with a `new Token(...)` in each arm. V8
compiled those into generic construct stubs (visible in profiles), since
the function had many allocation sites. Replace the switch with a
lexer-type → node-type lookup table and one `new Token` call (URL, the
only leaf with own state, handled separately).

~13% faster on a CPU-isolated parse, ~6% on a Tailwind v4 build; AST
output unchanged.
Introduce an accessor object A in lib/css/syntax.js routing every AST-node
field read through a function, so the node representation can be swapped from
class objects to a struct-of-arrays without touching consumers. Additive and
object-backed for now; no behavior change.
Rewrite every AST-node field read in CssParser to go through the A accessor
object instead of touching node properties directly, and move the ad-hoc
`urlRecovery` flag off the node into a parser-local. Behavior-preserving
(654 css config cases pass); prepares the consumer for a struct-of-arrays
node representation.
Build every parser node through module-level construction primitives
(_mkLeaf / _mkContainer / _setName / ...) instead of calling new Token /
new Container directly. An object backend reproduces the existing
class-instance tree the parseA* entry points return. This is a
behavior-preserving refactor (654 css config cases + 105 parser unit tests
pass) that lets the streaming grammar swap in a struct-of-arrays backend
without forking the consume algorithms.
The streaming grammar (the only path CssParser uses) now builds nodes into
reused typed arrays instead of class instances: node fields live in parallel
Uint8/Int32 arrays indexed by a 1-based node id, child lists hang off three
object arrays, and the write cursor is reset after each top-level rule's walk
so the buffers are reused and the parse allocates almost nothing across rules.
The A accessor reads the arrays, so CssParser is unchanged. parseA* keep the
object backend (retainable class tree the unit tests inspect).

654 css config cases + 105 css parser unit tests pass.
Remove the dead isIdentStartCodePoint (superseded by _isIdentStartCodePointCC)
and the unused HC_DELIM constant (the delim class is the default 0), brace the
char-class build loop, and order the parser unit-test imports — clearing the
eslint debt on the touched files.
The typed-array buffers stay pooled across parses for reuse, but the
per-container child-list arrays are dropped once the parse completes so they
are not retained idle until the next parse overwrites them (matters for watch
builds between rebuilds).
The Ident and Declaration value-visitors sliced the node value / property
name on every node even for plain (non-CSS-Modules) stylesheets, where the
dashed-ident and ICSS paths that consume them are inert. Gate that work behind
the dashed/ICSS context (Ident) and isModules (Declaration), so the common
non-modules parse skips a slice per ident and a slice + property-name
normalization per declaration. ~6.5% faster on a non-modules Tailwind parse;
CSS Modules behavior and output unchanged (654 css config cases pass).
processDashedIdentInVarFunction fires for every var()/style() in CSS-Modules
mode (Tailwind has thousands). It sliced the first ident's value only to test
the `--` prefix; check the two leading bytes directly instead. CSS Modules
output unchanged (654 css config cases pass).
@changeset-bot

changeset-bot Bot commented Jun 26, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 5991398

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package
Name Type
webpack Patch

Not sure what this means? Click here to learn what changesets are.

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

@github-actions

github-actions Bot commented Jun 26, 2026

Copy link
Copy Markdown
Contributor

This PR is packaged and the instant preview is available (5991398).

Install it locally:

  • npm
npm i -D webpack@https://pkg.pr.new/webpack@5991398
  • yarn
yarn add -D webpack@https://pkg.pr.new/webpack@5991398
  • pnpm
pnpm add -D webpack@https://pkg.pr.new/webpack@5991398

@codecov

codecov Bot commented Jun 26, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 97.15061% with 21 lines in your changes missing coverage. Please review.
✅ Project coverage is 92.87%. Comparing base (e8f9334) to head (5991398).
⚠️ Report is 13 commits behind head on main.

Files with missing lines Patch % Lines
lib/css/syntax.js 96.93% 13 Missing ⚠️
lib/css/CssParser.js 97.44% 8 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##             main   #21285      +/-   ##
==========================================
+ Coverage   92.82%   92.87%   +0.04%     
==========================================
  Files         592      593       +1     
  Lines       64829    65163     +334     
  Branches    18067    18119      +52     
==========================================
+ Hits        60175    60517     +342     
+ Misses       4654     4646       -8     
Flag Coverage Δ
css-parsing 28.61% <42.87%> (-0.11%) ⬇️
html5lib 31.14% <13.70%> (-0.03%) ⬇️
integration 88.88% <85.88%> (-0.10%) ⬇️
test262 45.54% <13.70%> (+0.12%) ⬆️
unit 43.09% <51.15%> (+1.61%) ⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@codspeed-hq

codspeed-hq Bot commented Jun 26, 2026

Copy link
Copy Markdown

Merging this PR will improve performance by 52.68%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 3 improved benchmarks
❌ 2 regressed benchmarks
✅ 139 untouched benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

Mode Benchmark BASE HEAD Efficiency
Memory benchmark "css-modules", scenario '{"name":"mode-production","mode":"production"}' 7.1 MB 9.3 MB -23.45%
Memory benchmark "many-chunks-commonjs", scenario '{"name":"mode-production","mode":"production"}' 6.9 MB 8.9 MB -23.28%
Memory benchmark "side-effects-reexport", scenario '{"name":"mode-development-rebuild","mode":"development","watch":true}' 858.9 KB 127.7 KB ×6.7
Memory benchmark "wasm-modules-async", scenario '{"name":"mode-development-rebuild","mode":"development","watch":true}' 332.3 KB 189.9 KB +74.92%
Memory benchmark "future-defaults", scenario '{"name":"mode-production","mode":"production"}' 8.8 MB 7.4 MB +20.1%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.


Comparing perf/css-struct-of-arrays-parser (5991398) with main (5e7db5d)

Open in CodSpeed

@github-actions

Copy link
Copy Markdown
Contributor

Types Coverage

Coverage after merging perf/css-struct-of-arrays-parser into main will be
99.36%
Coverage Report
FileStmtsBranchesFuncsLinesUncovered Lines
bin
   webpack.js98.77%100%100%98.77%91
examples
   build-common.js100%100%100%100%
   buildAll.js100%100%100%100%
   examples.js100%100%100%100%
   template-common.js98.21%100%100%98.21%72
examples/custom-javascript-parser
   test.filter.js100%100%100%100%
examples/custom-javascript-parser/internals
   acorn-parse.js100%100%100%100%
   meriyah-parse.js100%100%100%100%
   oxc-parse.js91.30%100%100%91.30%140, 142–143, 145, 147, 153–154, 161, 168, 90
examples/markdown
   webpack.config.mjs100%100%100%100%
examples/module-federation
   test.filter.js100%100%100%100%
examples/reexport-components
   test.filter.js100%100%100%100%
examples/typescript
   test.filter.js100%100%100%100%
examples/typescript-non-erasable
   test.filter.js50%100%100%50%5
examples/virtual-modules
   test.filter.js100%100%100%100%
examples/wasm-bindgen-esm
   test.filter.js100%100%100%100%
examples/wasm-complex
   test.filter.js100%100%100%100%
examples/wasm-emscripten
   test.filter.js100%100%100%100%
examples/wasm-simple
   test.filter.js100%100%100%100%
examples/wasm-simple-source-phase
   test.filter.js100%100%100%100%
lib
   APIPlugin.js100%100%100%100%
   AsyncDependenciesBlock.js100%100%100%100%
   AutomaticPrefetchPlugin.js100%100%100%100%
   BannerPlugin.js100%100%100%100%
   Cache.js98.21%100%100%98.21%101
   CacheFacade.js100%100%100%100%
   Chunk.js99.72%100%100%99.72%39
   ChunkGraph.js100%100%100%100%
   ChunkGroup.js100%100%100%100%
   ChunkTemplate.js100%100%100%100%
   CircularModulesPlugin.js98.81%100%100%98.81%136
   CleanPlugin.js99.12%100%100%99.12%207, 227
   CodeGenerationResults.js100%100%100%100%
   CompatibilityPlugin.js100%100%100%100%
   Compilation.js98.43%100%100%98.43%1641, 1960, 1967, 1975, 1997, 2000, 2940, 3419–3420, 3452, 4118, 4148, 4201–4202, 4206, 4211, 4227–4228, 4242–4243, 4248–4249, 4726, 4752, 526, 531, 5560, 5592, 5609, 5625, 5641, 5656, 5681–5682, 5684, 6012, 6017, 6023, 6026, 6038, 6040, 6044, 6060, 6075, 6107, 6161, 6185, 6299, 777–778
   Compiler.js99.56%100%100%99.56%1147–1148, 1156
   ConcatenationScope.js98.65%100%100%98.65%195
   ConditionalInitFragment.js100%100%100%100%
   ConstPlugin.js100%100%100%100%
   ContextExclusionPlugin.js100%100%100%100%
   ContextModule.js100%100%100%100%
   ContextModuleFactory.js97.40%100%100%97.40%258, 395, 418, 420, 424, 433–434
   ContextReplacementPlugin.js100%100%100%100%
   DefinePlugin.js98.99%100%100%98.99%172–173, 189, 208, 282
   DependenciesBlock.js100%100%100%100%
   Dependency.js98.51%100%100%98.51%479, 525
   DependencyTemplate.js100%100%100%100%
   DependencyTemplates.js100%100%100%100%
   DotenvPlugin.js98.41%100%100%98.41%378, 391–392
   DynamicEntryPlugin.js100%100%100%100%
   EntryOptionPlugin.js100%100%100%100%
   EntryPlugin.js100%100%100%100%
   Entrypoint.js100%100%100%100%
   EnvironmentPlugin.js97.14%100%100%97.14%49
   ErrorHelpers.js100%100%100%100%
   EvalDevToolModulePlugin.js100%100%100%100%
   EvalSourceMapDevToolPlugin.js100%100%100%100%
   ExportsInfo.js100%100%100%100%
   ExportsInfoApiPlugin.js100%100%100%100%
   ExternalModule.js98.49%100%100%98.49%1044, 1047, 451–455, 457, 603
   ExternalModuleFactoryPlugin.js100%100%100%100%
   ExternalsPlugin.js100%100%100%100%
   FileSystemInfo.js99.52%100%100%99.52%182, 2382–2383, 2386, 2397, 2408, 2419, 280, 3823, 3838, 3862
   FlagAllModulesAsUsedPlugin.js100%100%100%100%
   FlagDependencyExportsPlugin.js98.42%100%100%98.42%413, 422, 424, 428
   FlagDependencyUsagePlugin.js100%100%100%100%
   FlagEntryExportAsUsedPlugin.js100%100%100%100%
   Generator.js100%100%100%100%
   HotModuleReplacementPlugin.js100%100%100%100%
   HotUpdateChunk.js100%100%100%100%
   IgnorePlugin.js100%100%100%100%
   IgnoreWarningsPlugin.js100%100%100%100%
   InitFragment.js100%100%100%100%
   JavascriptMetaInfoPlugin.js100%100%100%100%
   LazyBarrel.js100%100%100%100%
   LibraryTemplatePlugin.js100%100%100%100%
   LoaderOptionsPlugin.js100%100%100%100%
   LoaderTargetPlugin.js100%100%100%100%
   MainTemplate.js100%100%100%100%
   ManifestPlugin.js100%100%100%100%
   Module.js98.50%100%100%98.50%1285, 1290, 1350, 1364, 1426, 1435
   ModuleFactory.js100%100%100%100%
   ModuleFilenameHelpers.js98.85%100%100%98.85%106, 108
   ModuleGraph.js99.73%100%100%99.73%1005
   ModuleGraphConnection.js100%100%100%100%
   ModuleInfoHeaderPlugin.js100%100%100%100%
   ModuleNotFoundError.js100%100%100%100%
   ModuleProfile.js100%100%100%100%
   ModuleSourceTypeConstants.js100%100%100%100%
   ModuleTemplate.js100%100%100%100%
   ModuleTypeConstants.js100%100%100%100%
   MultiCompiler.js99.69%100%100%99.69%661
   MultiStats.js100%100%100%100%
   MultiWatching.js100%100%100%100%
   NoEmitOnErrorsPlugin.js100%100%100%100%
   NodeStuffPlugin.js100%100%100%100%
   NormalModule.js97.89%100%100%97.89%1227, 1230, 1247, 1264, 1511, 1545, 1561, 1648, 2004, 2303, 2308–2318, 419, 423, 577
   NormalModuleFactory.js99.47%100%100%99.47%1083, 1392, 486, 498
   NormalModuleReplacementPlugin.js100%100%100%100%
   NullFactory.js100%100%100%100%
   OptimizationStages.js100%100%100%100%
   OptionsApply.js100%100%100%100%
   Parser.js100%100%100%100%
   PlatformPlugin.js100%100%100%100%
   PrefetchPlugin.js100%100%100%100%
   ProgressPlugin.js98.85%100%100%98.85%527–528, 533, 535, 599
   ProvidePlugin.js100%100%100%100%
   RawModule.js100%100%100%100%
   RecordIdsPlugin.js100%100%100%100%
   RequestShortener.js100%100%100%100%
   ResolverFactory.js100%100%100%100%
   RuntimeGlobals.js100%100%100%100%
   RuntimeModule.js100%100%100%100%
   RuntimePlugin.js100%100%100%100%
   RuntimeTemplate.js100%100%100%100%
   SelfModuleFactory.js100%100%100%100%
   SingleEntryPlugin.js100%100%100%100%
   SourceMapDevToolModuleOptionsPlugin.js100%100%100%100%
   SourceMapDevToolPlugin.js98.62%100%100%98.62%220, 224, 226, 419, 430, 889
   Stats.js100%100%100%100%
   Template.js100%100%100%100%
   TemplatedPathPlugin.js99.43%100%100%99.43%308–309
   UseStrictPlugin.js100%100%100%100%
   WarnCaseSensitiveModulesPlugin.js100%100%100%100%
   WarnDeprecatedOptionPlugin.js100%100%100%100%
   WarnNoModeSetPlugin.js100%100%100%100%
   WatchIgnorePlugin.js100%100%100%100%
   Watching.js100%100%100%100%
   WebpackError.js100%100%100%100%
   WebpackIsIncludedPlugin.js100%100%100%100%
   WebpackOptionsApply.js100%100%100%100%
   WebpackOptionsDefaulter.js100%100%100%100%
   buildChunkGraph.js99.87%100%100%99.87%371
   cli.js98.63%100%100%98.63%10, 119, 549, 581, 631, 905
   index.js99.72%100%100%99.72%184
   validateSchema.js94.67%100%100%94.67%100, 87, 89, 98
   webpack.js96.33%100%100%96.33%10, 198, 220, 222
lib/asset
   AssetBytesGenerator.js100%100%100%100%
   AssetBytesParser.js100%100%100%100%
   AssetGenerator.js100%100%100%100%
   AssetModule.js100%100%100%100%
   AssetModulesPlugin.js97.33%100%100%97.33%282, 306, 309, 36, 362, 41
   AssetParser.js100%100%100%100%
   AssetSourceGenerator.js100%100%100%100%
   AssetSourceParser.js100%100%100%100%
   RawDataUrlModule.js100%100%100%100%
lib/async-modules
   AsyncModuleHelpers.js100%100%100%100%
   AwaitDependenciesInitFragment.js100%100%100%100%
   InferAsyncModulesPlugin.js100%100%100%100%
lib/bun
   BunTargetPlugin.js100%100%100%100%
lib/cache
   AddBuildDependenciesPlugin.js100%100%100%100%
   AddManagedPathsPlugin.js100%100%100%100%
   IdleFileCachePlugin.js97.92%100%100%97.92%75, 87, 95
   MemoryCachePlugin.js95.83%100%100%95.83%33
   MemoryWithGcCachePlugin.js93.15%100%100%93.15%107, 114–115, 123, 90
   PackFileCacheStrategy.js96.40%100%100%96.40%1251, 1351, 1355, 1417, 628, 647, 657–659, 661, 677–678, 683, 686, 688, 693, 698, 723, 729, 763, 769, 775, 780, 791, 800, 805–806, 808, 825, 831–832, 834
   ResolverCachePlugin.js100%100%100%100%
   getLazyHashedEtag.js100%100%100%100%
   mergeEtags.js100%100%100%100%
lib/config
   browserslistTargetHandler.js100%100%100%100%
   defaults.js99.33%100%100%99.33%1468–1470, 1478, 274,

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant