Does PostCSS guarantee sequential plugin execution when plugins return promises?

PostCSS Async Plugin Execution Model

PostCSS'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?