Does PostCSS guarantee sequential plugin execution when plugins return promises?

Question

PostCSS Async Plugin Execution ModelPostCSS's plugin architecture supports both synchronous and asynchronous transformations through a standardized API where plugins receive the root AST node. The API allows plugins to return a promise for async operations, but the documentation does not clearly specify how promise resolution affects the execution order of subsequent plugins in the pipeline.The core uncertainty revolves around whether PostCSS enforces a strict sequential execution model for all plugins regardless of their async nature, or permits potential concurrent execution for performance optimization. This becomes critical when plugins modify shared AST state or depend on transformations from preceding plugins.While many plugin implementations assume the root AST is fully processed before the next plugin runs, this behavior is not explicitly guaranteed by the PostCSS runtime. In environments where async plugins might execute concurrently, this could lead to race conditions where plugins operate on incomplete or inconsistent AST states.The unresolved decision impacts plugin developers who must choose between defensive coding practices (assuming sequential execution) or optimizing for potential parallelism. This also affects how developers structure complex transformation pipelines with interdependent plugins.Can PostCSS guarantee that async plugins execute in the order they are defined in the plugin array? Does the current implementation support concurrent plugin execution that could compromise AST consistency? What is the recommended approach for plugin authors to ensure predictable behavior across different PostCSS versions?

Tasadduq Burney · Answer

AnswerYes. In the current PostCSS 8.x architecture, plugins are executed sequentially in the order they appear in the plugin array, and a plugin that returns a Promise is awaited before the next plugin runs. PostCSS does not run plugins concurrently against the same AST.Confirmed factsProcessor walks the plugin list one by one and runs each plugin's transform on the root AST before invoking the next.If any plugin returns a Promise, LazyResult switches the whole run to async mode and awaits that promise before proceeding. Ordering is preserved across mixed sync and async pipelines.Calling the synchronous result accessor on a pipeline that contains an async plugin fails loudly with a guard that requires using the asynchronous API. This is a deliberate runtime guard, not a race.Each plugin sees the AST as left by all previous plugins. Interdependent plugins are safe as long as the array order reflects the dependency.Likely explanation vs assumptionsThe sequential guarantee applies to plugin-to-plugin order. It does not protect against a single plugin that fires off floating promises inside its own visitors without awaiting them. Within a plugin, async work scheduled in Declaration or other visitors must be returned/awaited by the plugin author; otherwise the plugin may report completion before its internal work finishes.Assumption: PostCSS 8.x core runtime. Very old versions pre-8 used a different plugin API and async handling. Third-party wrappers or bundler integrations around PostCSS may batch or reorder work independently of the core runtime.Verification steps for this caseConfirm installed PostCSS major version from package.json or npm ls postcss. The sequential await-per-plugin behavior described here matches the long-standing 8.x LazyResult implementation.Write a minimal ordering test: plugin A async with a delay that appends a node, plugin B asserts the node exists. Run with await processor.process() and confirm correct order and no error.Verify the async guard: attempt to read result synchronously on a pipeline with an async plugin and confirm the runtime requires the asynchronous API.If you can share the exact PostCSS version in use, the recommendation can be tightened to that release's LazyResult implementation.

Does PostCSS guarantee sequential plugin execution when plugins return promises?

PostCSS Async Plugin Execution Model

1 answer

Answer

Confirmed facts

Likely explanation vs assumptions

Verification steps for this case

Your perspective belongs here.

0 question comments