Theme: Add build plugins to inject design token fallbacks #75589
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| declare const plugin: import('esbuild').Plugin; | ||
| export default plugin; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,47 @@ | ||
| import { readFile } from 'fs/promises'; | ||
| import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs'; | ||
|
Contributor
There was a problem hiding this comment. Non-blocking nit: While
Member
Author
There was a problem hiding this comment. The plugins themselves are pretty thin so I'd say there's not much meaningful tests we can add at this level that's worth the trouble. I'd lean towards adding targeted tests once we encounter subtle issues we didn't foresee, or if it ends up we edit these plugin files somewhat frequently (hopefully not!). |
||
|
|
||
| const LOADER_MAP = { | ||
| '.js': 'jsx', | ||
| '.jsx': 'jsx', | ||
| '.ts': 'tsx', | ||
| '.tsx': 'tsx', | ||
| '.mjs': 'jsx', | ||
| '.mts': 'tsx', | ||
| '.cjs': 'jsx', | ||
| '.cts': 'tsx', | ||
| }; | ||
|
|
||
| /** | ||
| * esbuild plugin that injects design-system token fallbacks into JS/TS files. | ||
| * | ||
| * Replaces bare `var(--wpds-*)` references in string literals with | ||
| * `var(--wpds-*, <fallback>)` so components render correctly without | ||
| * a ThemeProvider. | ||
| */ | ||
| const plugin = { | ||
|
Contributor
There was a problem hiding this comment. This was something caught while reviewing this PR with the aid of an AI agent: esbuild The esbuild plugin is first in the plugins array ( The // packages/wp-build/lib/build.mjs:1274-1280
const plugins = [
dsTokenFallbacksJs, // ← wins onLoad for matching files
needsEmotionPlugin && emotionPlugin, // ← skipped for those files
wasmInlinePlugin,
externalizeAllExceptCssPlugin,
...createStyleBundlingPlugins( packageDir ),
].filter( Boolean );Suggestion: Verify whether any files in the codebase use both
Member
Author
There was a problem hiding this comment. Good catch. After considering the technical cost of adding support for token replacement in Emotion files (which is not impossible), my current assessment is that it would be better for us to migrate off of Emotion rather than adding more tooling to continue supporting it. Maybe we can add a lint to prevent design token usage in Emotion files. In any case, wanting to use design tokens will hopefully be another good motivation for us to migrate off.
Member
Author
There was a problem hiding this comment.
Added in #75872. This should also address your point about token usage not being checked in Emotion files 😄 |
||
| name: 'ds-token-fallbacks-js', | ||
| setup( build ) { | ||
| build.onLoad( { filter: /\.[mc]?[jt]sx?$/ }, async ( args ) => { | ||
| // Skip node_modules. | ||
| if ( args.path.includes( 'node_modules' ) ) { | ||
| return undefined; | ||
| } | ||
|
Comment on lines
+27
to
+29
Contributor
There was a problem hiding this comment. Performance nit: can we move the
Member
Author
There was a problem hiding this comment. Looked into it. esbuild's Given the measured overhead is negligible, seems like the in-callback check is the most pragmatic option here. |
||
|
|
||
| const source = await readFile( args.path, 'utf8' ); | ||
|
|
||
| if ( ! source.includes( '--wpds-' ) ) { | ||
| return undefined; | ||
| } | ||
|
|
||
| const ext = args.path.match( /(\.[^.]+)$/ )?.[ 1 ] || '.js'; | ||
|
|
||
| return { | ||
| contents: addFallbackToVar( source ), | ||
|
Member
Author
There was a problem hiding this comment. In the both the esbuild and vite plugins, we're replacing all instances of the token strings, including in code comments. This should be safe and still understandable. Ideally we skip code comments, but it would increase the complexity of this plugin in a way that's probably not worth the trouble. |
||
| loader: LOADER_MAP[ ext ] || 'jsx', | ||
| }; | ||
| } ); | ||
| }, | ||
| }; | ||
|
|
||
| export default plugin; | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| declare const plugin: import('postcss').PluginCreator< never >; | ||
| export default plugin; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| import { addFallbackToVar } from './ds-token-fallbacks.mjs'; | ||
|
|
||
| const plugin = () => ( { | ||
| postcssPlugin: 'postcss-ds-token-fallbacks', | ||
| /** @param {import('postcss').Declaration} decl */ | ||
| Declaration( decl ) { | ||
| const updated = addFallbackToVar( decl.value ); | ||
| if ( updated !== decl.value ) { | ||
| decl.value = updated; | ||
| } | ||
| }, | ||
| } ); | ||
|
|
||
| plugin.postcss = true; | ||
|
|
||
| export default plugin; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| declare const plugin: () => import('vite').Plugin; | ||
| export default plugin; |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,28 @@ | ||
| import { addFallbackToVar } from '../postcss-plugins/ds-token-fallbacks.mjs'; | ||
|
|
||
| /** | ||
| * Vite plugin that injects design-system token fallbacks into JS/TS files. | ||
| * | ||
| * Replaces bare `var(--wpds-*)` references in string literals with | ||
| * `var(--wpds-*, <fallback>)` so components render correctly without | ||
| * a ThemeProvider. | ||
| */ | ||
| const plugin = () => ( { | ||
| name: 'ds-token-fallbacks-js', | ||
| transform( code, id ) { | ||
| if ( ! /\.[mc]?[jt]sx?$/.test( id ) ) { | ||
| return null; | ||
| } | ||
| if ( id.includes( 'node_modules' ) ) { | ||
| return null; | ||
| } | ||
| if ( ! code.includes( '--wpds-' ) ) { | ||
| return null; | ||
| } | ||
| // Sourcemap omitted: replacements are small, inline substitutions | ||
| // that preserve line structure, so the debugging impact is negligible. | ||
| return { code: addFallbackToVar( code ), map: null }; | ||
|
Contributor
There was a problem hiding this comment. Non-blocking nit: Returning This is an acceptable trade-off given the simplicity, but a brief comment explaining the choice would help future maintainers. Alternatively, Opus suggests using `magic-string` and importing `ds-token-fallback.mjs` to generate the sourcemapimport MagicString from 'magic-string';
import { tokenFallbackRegex, getFallback } from '../postcss-plugins/ds-token-fallbacks.mjs';
const plugin = () => ( {
name: 'ds-token-fallbacks-js',
transform( code, id ) {
if ( ! /\.[mc]?[jt]sx?$/.test( id ) ) {
return null;
}
if ( id.includes( 'node_modules' ) ) {
return null;
}
if ( ! code.includes( '--wpds-' ) ) {
return null;
}
const s = new MagicString( code );
const regex = /var\(\s*(--wpds-[\w-]+)\s*\)/g;
let match;
while ( ( match = regex.exec( code ) ) !== null ) {
const tokenName = match[ 1 ];
const fallback = tokenFallbacks[ tokenName ];
if ( fallback !== undefined ) {
s.overwrite(
match.index,
match.index + match[ 0 ].length,
`var(${ tokenName }, ${ fallback })`
);
}
}
if ( ! s.hasChanged() ) {
return null;
}
return {
code: s.toString(),
map: s.generateMap( { hires: true } ),
};
},
} );
Member
Author
There was a problem hiding this comment. Added comment in 5206004 Also I think the maps wouldn't degrade in a completely unuseful way, because the line numbers will stay the same (or at least adjacent). |
||
| }, | ||
| } ); | ||
|
|
||
| export default plugin; | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These are official exports so anyone could theoretically integrate them into their build tooling. If necessary, we can even export the data source of the fallbacks so people can make their own injection plugins.