Which ordering guarantees does PostCSS provide when plugins rewrite the same declaration?

Direct Answer

PostCSS provides no ordering guarantees beyond sequential execution. Plugins run in the exact order registered via use(). The processor does not topologically sort, validate declared dependencies, or detect conflicts. When multiple plugins rewrite the same declaration, the final AST is determined solely by:

1. Plugin registration order
2. Whether each plugin mutates the existing node in place or replaces it with a new node

Plugin deps metadata is informational only — PostCSS never validates or enforces it. Reproducibility across versions requires explicit plugin ordering in configuration, version locking, and integration tests that snapshot serialized output.

Confirmed Behavior

Sequential Single-Pass Execution

PostCSS walks the AST once per plugin, in registration order. Processor#use pushes plugins onto an array; Processor#process iterates that array and calls each plugin's postcssPlugin function with the root node. There is no dependency graph, no topological sort, and no conflict detection in the core (verified in lib/postcss.js since v6.x through current 8.x).

Mutation vs Replacement Determines Outcome

If Plugin A mutates decl.value in place and Plugin B later replaces the declaration via decl.replaceWith(), Plugin A's change is lost. If the order reverses, Plugin B's replacement becomes the target of Plugin A's mutation. Whitespace and comments stored in node.raws are preserved only on nodes that survive; replacement discards prior raws.

Dependency Metadata Is Not Enforced

The postcss.plugin(name, { deps: ['other-plugin'] }) option exists for documentation and tooling (e.g., postcss-sort-plugins), but the core processor ignores it. No validation, reordering, or warning occurs.

Recommended Reproducibility Practices

1. Explicit ordering in config — Define plugin array in postcss.config.js, CLI --use, or programmatic use() calls. Do not rely on alphabetical or package-json order.
2. Document the required sequence — Add comments explaining why Plugin X must precede Plugin Y when they target overlapping declarations.
3. Lock versions — Commit package-lock.json or yarn.lock for PostCSS and all plugins. Core behavior is stable, but plugin internals (e.g., autoprefixer, cssnano) may reorder their internal transforms across major versions.
4. Snapshot integration tests — Render real CSS through the full pipeline and assert exact serialized output. This catches whitespace/comment differences from node replacement that semantic comparison would miss.

Verification Step

Create a minimal test case: a CSS file with one declaration (color: red), Plugin A that mutates decl.value = 'blue', Plugin B that replaces the declaration with decl.replaceWith(postcss.decl({ prop: 'color', value: 'green' })). Run with both plugin orders via PostCSS CLI and compare output. This confirms the mutation-vs-replacement behavior in your version.

One Diagnostic Detail

Are any plugins in your pipeline using Root#walk or Container#walk with callbacks that modify the tree during iteration? Such mutations affect traversal order for subsequent plugins and create subtle ordering dependencies beyond simple declaration rewrites.