Style Runtime: Support CSS module style injection across documents#77965
Open
Style Runtime: Support CSS module style injection across documents#77965
Conversation
github-actions
Bot
added
[Package] Components
|
Size Change: +2.23 kB (+0.03%) Total Size: 7.95 MB 📦 View Changed
ℹ️ View Unchanged
|
mirka
changed the title
mirka
commented
May 5, 2026
| '@wordpress/grid', | ||
| '@wordpress/icons', | ||
| '@wordpress/interface', | ||
| '@wordpress/style-runtime', |
Member
Author
There was a problem hiding this comment.
This can be a bundled package for now.
Member
Author
There was a problem hiding this comment.
This component already existed to solve a similar problem for Emotion styles. Here we hook into the same provider.
mirka
requested review from
a team,
ajitbohra,
fabiankaegy and
juanmaguitar
as code owners
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
mirka
commented
May 5, 2026
Comment on lines
+223
to
+227
| let cssModule = cssModules | ||
| ? `import { registerStyle } from '@wordpress/style-runtime'; | ||
| if (typeof process === 'undefined' || process.env.NODE_ENV !== 'test') { | ||
| registerStyle("${ hash }", ${ JSON.stringify( css ) }); | ||
| } |
Member
Author
There was a problem hiding this comment.
I'm gating this behavior to CSS modules only for now, because we eventually want to stop injecting non-module styles (#76744). Eventually, only CSS modules will be processed by this compileInlineStyle function.
|
Flaky tests detected in 3fa1117. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/25393296119
|
Contributor
|
Consider how this impacts folks using wp-build outside Gutenberg. Ideally things should continue to work without any change on their part. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Fixes an issue reported in #77575 (comment)
Adds a shared
@wordpress/style-runtimepackage for registering package styles and injecting them into one or more documents.Why?
CSS module imports are evaluated as JavaScript side effects, so their generated style tags are inserted into the root document. That does not cover components rendered into another document, such as the editor iframe canvas.
How?
Adds a runtime registry that stores compiled CSS by hash and tracks target documents. Generated CSS module output now registers styles with the runtime, and
StyleProviderregisters its target document so previously registered styles can be replayed into that document.Next steps
@wordpress/componentsStyleProvider. This means that the fix won't be available in older versions of WordPress, if plugin developers want to start using@wordpress/uicomponents there. To solve this, we can add temporary workarounds in@wordpress/uiitself to register their own styles in their owner document, not relying onStyleProvider.style-runtimeas a package.json and tsconfig dependency. We probably need some kind of CI check to enforce this, since it's hard to even know about.Full strategy plan
Direction
Use a shared runtime as the single source of truth for CSS module style registration, and add an
@wordpress/uimount-time bridge for compatibility.The key idea is:
PR 1: Shared Runtime And Host Integration
/Users/lena/Documents/Work/Automattic/gutenberg/packages/wp-build/lib/build.mjswith an import of a shared runtime package.@wordpress/style-runtime, that exposes:registerStyle( hash, css )registerDocument( document )documentregistration by default when available/Users/lena/Documents/Work/Automattic/gutenberg/packages/wp-build/lib/build.mjsso generated modules stay tiny:registerStyleregisterStyle( hash, css )/Users/lena/Documents/Work/Automattic/gutenberg/packages/components/src/style-provider/index.tsxto register its target document with the shared runtime.StyleProvidersupport as the long-term host-level path for portals, SlotFill, and iframe canvas documents.PR 2:
@wordpress/uiMount-Time Hook@wordpress/uishort-term compatibility via a hook, likely/Users/lena/Documents/Work/Automattic/gutenberg/packages/ui/src/utils/use-styles.ts, that registersnode.ownerDocumenton mount.@wordpress/uicomponents that import CSS modules, by merging its ref with each component's forwarded/root ref. This makes iframe support travel with@wordpress/ui, rather than requiring a newer WordPressStyleProvider.@wordpress/uiand use the shared runtime from PR 1 rather than adding another injection path.Optional PR 3: Dependency Validation
packages/*/srcfor direct imports of.module.cssor.module.scss.package.jsondeclares@wordpress/style-runtimeindependenciestsconfig.jsonreferences../style-runtime@wordpress/style-runtimeitself.lint:pkg-jsonorlint:tsconfig, so packages that start importing CSS modules directly cannot forget the runtime dependency metadata.Approaches Considered And Discarded
StyleProvider. This is the right long-term host integration point, but plugin consumers on older WordPress versions would not get the fix.Testing Instructions
In the site editor, add a Navigation block. This block contains a
VisuallyHiddendescription which is not properly hidden in trunk due to missing styles in the editor iframe. With this PR, the styles should be injected in the iframe, and the visually hidden description should be hidden.