@eightshift/frontend-libs-tailwind 4.0.0-beta.3 → 4.0.0-beta.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +30 -1
- package/README.md +149 -12
- package/bin/tw-sweep.mjs +35 -14
- package/bun/browser-css.mjs +487 -0
- package/bun/build.mjs +20 -1
- package/bun/cli-supervisor.mjs +171 -0
- package/bun/cli-worker.mjs +57 -0
- package/bun/cli.mjs +3 -49
- package/bun/css.mjs +126 -25
- package/bun/discovery.mjs +12 -1
- package/bun/editor-native.mjs +38 -0
- package/bun/editor-pure-jsx.mjs +88 -0
- package/bun/editor.mjs +33 -0
- package/bun/eightshift-discovery.mjs +102 -26
- package/bun/flat-publication.mjs +19 -184
- package/bun/index.mjs +14 -0
- package/bun/media.mjs +17 -5
- package/bun/plugin-capabilities.mjs +1 -0
- package/bun/preset.mjs +6 -4
- package/bun/publish.mjs +7 -4
- package/bun/release.mjs +56 -4
- package/bun/shared-fonts.mjs +140 -0
- package/bun/ssr.mjs +26 -12
- package/bun/structured-publication.mjs +66 -0
- package/bun/theme-build.mjs +130 -43
- package/bun/theme-discovery.mjs +113 -9
- package/bun/watch.mjs +32 -0
- package/bun/wordpress.mjs +49 -23
- package/eslint.config.mjs +22 -1
- package/linters/base.config.mjs +1 -0
- package/linters/tw-sweep-extract.mjs +5 -0
- package/package.json +5 -5
- package/scripts/components/link-section-editor.js +1 -0
- package/scripts/editor/editor.js +1 -0
- package/scripts/editor/registration.js +3 -0
- package/scripts/editor/store.js +7 -0
- package/test/bun-discovery.test.mjs +69 -0
- package/test/bun-publication.test.mjs +144 -0
- package/test/bun-theme-build.test.mjs +12 -0
- package/test/bun-wordpress.test.mjs +82 -0
- package/test/fixtures/theme-build-regressions.mjs +585 -0
package/CHANGELOG.md
CHANGED
|
@@ -8,6 +8,35 @@ This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a
|
|
|
8
8
|
|
|
9
9
|
## [4.0.0]
|
|
10
10
|
|
|
11
|
+
### 4.0.0-beta.5
|
|
12
|
+
|
|
13
|
+
- Use ESLint 9 to satisfy the React lint plugin peer range without changing lint rules.
|
|
14
|
+
- Support stable UI Components 8 and explicitly allow 8.5.0-beta.1; validate locally against that exact published beta.
|
|
15
|
+
|
|
16
|
+
- Preserve generic PHP class extraction alongside the documented Tailwind helper patterns.
|
|
17
|
+
- ESLint 9 remains a known end-of-life risk; a major upgrade is deferred pending React plugin peer compatibility.
|
|
18
|
+
|
|
19
|
+
### 4.0.0-beta.4
|
|
20
|
+
|
|
21
|
+
- **Breaking:** make structured directories the only built-in `defineThemeBuild` publication layout. Remove `publicationLayout` from configuration (all explicit values are rejected) and remove the legacy `flattenAssets` export. Migrate publication hooks from `outdir/flat` to the stable `publicationRoot` directory contract and nested relative aliases; fixed special outputs remain supported through `extraFiles`. Custom `publish` callbacks remain supported but must account for structured compiler URLs. Low-level build and prepared-tree packaging APIs retain their existing defaults.
|
|
22
|
+
- Omit unreferenced conventional structured entry stylesheet intermediates after generating hashed replacements; retain aliases, referenced styles, custom CSS and script paths. Cache synchronization, retention and rollback policy are unchanged.
|
|
23
|
+
|
|
24
|
+
- Default conventional theme editor builds to unified sharing; compatible PHP module-readiness integration is required.
|
|
25
|
+
- Add opt-in shared same-origin font publication, requiring UI Components 8.5.0-beta.1 and Eightshift Libs 14.0.0-alpha.3 shared-font support.
|
|
26
|
+
- Compile default SSR entries together as standalone CommonJS bundles; preserve sequential compilation for caller plugins and prevent implicit writes during compilation.
|
|
27
|
+
- Restart CLI watch workers on selected configuration, root package manifest and Bun lockfile changes, draining active work before replacement.
|
|
28
|
+
- Accept both verified generated Smart Image worker URL forms.
|
|
29
|
+
- Resolve externalized WordPress package exports and default globals from core scripts without requiring installed package metadata; remove the API-fetch peer requirement.
|
|
30
|
+
- Preserve isolated editor store IDs across projects without changing them on every rebuild.
|
|
31
|
+
- Compile JavaScript-imported frontend and admin CSS and load it with its importing module, preserving lazy boundaries; resolve Smart Image workers on each surface.
|
|
32
|
+
- Preserve relative asset URLs in nested release stylesheets and retain conditional shared-font rules in their original stylesheets.
|
|
33
|
+
- Preserve eager JavaScript discovery contexts and recognize escaped editor stylesheet patterns.
|
|
34
|
+
- Preserve CommonJS-style WordPress core exports instead of treating them as side-effect-only scripts.
|
|
35
|
+
- Publish local string image URLs in CSS `image-set()` declarations.
|
|
36
|
+
- Decode percent-encoded local CSS asset paths once, preserving query strings and fragments; report malformed path encoding clearly.
|
|
37
|
+
- Allow empty release stylesheets while continuing to reject missing files and empty JavaScript entries.
|
|
38
|
+
- Exit nonzero when a one-shot CLI build is interrupted, including during configuration loading.
|
|
39
|
+
|
|
11
40
|
### Changed
|
|
12
41
|
|
|
13
42
|
- Show build/watch progress and total duration by default, with `--quiet` and `--verbose` output modes.
|
|
@@ -21,7 +50,7 @@ This projects adheres to [Semantic Versioning](https://semver.org/) and [Keep a
|
|
|
21
50
|
- Improved browser bundle tree-shaking and WordPress dependency metadata.
|
|
22
51
|
- Prevented unnecessary watch rebuilds on macOS.
|
|
23
52
|
- Removed the experimental `editor.sharedPackages` option. Existing configurations must remove it or migrate to a supported sharing mode.
|
|
24
|
-
-
|
|
53
|
+
- **Breaking:** conventional theme builds now default to `unified` editor sharing, requiring matching PHP module-readiness integration (validated with eightshift-libs 14.0.0-alpha.2). The lower-level editor API still defaults to `independent`. Explicit editor presets retain their own sharing choice. `native` remains opt-in and shares lazy modules while keeping registration separate.
|
|
25
54
|
- Added opt-in `editor.pureJsxGroups` to reduce chunk requests in unified production builds. Unsupported configurations, including source-map builds, fall back to ungrouped output.
|
|
26
55
|
|
|
27
56
|
## [3.5.0]
|
package/README.md
CHANGED
|
@@ -18,7 +18,7 @@ The Webpack configuration and `webpack/*` imports have been removed. Projects mu
|
|
|
18
18
|
|
|
19
19
|
The Bun helpers are not a drop-in replacement for Webpack. Start with the theme preset for the conventional Eightshift theme layout. Use the lower-level API below for other layouts.
|
|
20
20
|
|
|
21
|
-
The conventional theme build requires a stable WordPress 7.0 or newer installation. Each build reads `wp-includes/version.php` before modifying output and fails if the version is missing, unrecognized, or too old. By default, the WordPress root is three directories above the theme root; set `EIGHTSHIFT_WP_ROOT` to its absolute path for other layouts. The public asset URL defaults to the theme's path under that root plus `/public/`. If that does not match the site's URL layout, set `publicPrefix` in `defineThemeBuild` or `EIGHTSHIFT_PUBLIC_PREFIX` in the environment to the root-relative public URL path, including its trailing slash (for example, `/wp-content/themes/example/public/`). The option takes precedence over the environment variable. The lower-level build API does not enforce this version check.
|
|
21
|
+
The conventional theme build requires a stable WordPress 7.0 or newer installation. Each build reads `wp-includes/version.php` before modifying output and fails if the version is missing, unrecognized, or too old. By default, the WordPress root is three directories above the theme root; set `EIGHTSHIFT_WP_ROOT` to its absolute path for other layouts. The public asset URL defaults to the theme's path under that root plus `/public/`. If that does not match the site's URL layout, set `publicPrefix` in `defineThemeBuild` or `EIGHTSHIFT_PUBLIC_PREFIX` in the environment to the root-relative public URL path, including its trailing slash (for example, `/wp-content/themes/example/public/`). The option takes precedence over the environment variable. The editor store ID is derived from this prefix and remains stable across rebuilds. Builds loaded together must use distinct public prefixes to avoid sharing a store. The lower-level build API does not enforce this version check.
|
|
22
22
|
|
|
23
23
|
### Migrate a conventional theme
|
|
24
24
|
|
|
@@ -54,6 +54,31 @@ The manifest maps the conventional `applicationBlocksFrontend`, `applicationBloc
|
|
|
54
54
|
|
|
55
55
|
Successful default publication replaces the previous `public/` contents. Run only one build or publication per theme at a time; output directories are not locked against concurrent builds. The PHP manifest cache update is not coordinated with PHP cache rebuilds: if they overlap, stale asset URLs can remain until the next successful build or cache reset. Account for cached pages that may still request files removed by successful publication; retain old releases externally if needed. Verify block registration, editor controls and save/reload behavior, frontend styles and lazy assets, representative admin screens, script dependencies, browser console and asset URLs. Keep the previous Webpack build available for rollback until the new build is verified.
|
|
56
56
|
|
|
57
|
+
### Editor default and PHP compatibility
|
|
58
|
+
|
|
59
|
+
`defineThemeBuild({ root })` uses unified editor sharing: registration and lazy editor modules share one ESM graph. It requires the PHP `eightshift-editor-v1` module-readiness integration, validated with `infinum/eightshift-libs` 14.0.0-alpha.2. Install compatible PHP integration before serving these assets, and enqueue editor JavaScript through `enqueue_block_editor_assets`. The build checks WordPress source compatibility but cannot certify which PHP integration is active at runtime. Without the readiness bootstrap, the generated module throws an explicit error; there is no automatic classic-script fallback.
|
|
60
|
+
|
|
61
|
+
Classic consumers that require registered blocks must await the readiness promise described below. This is a registration-semantics change, not a guaranteed startup speedup. Package import optimization and pure JSX grouping are separate settings; JSX grouping remains off by default.
|
|
62
|
+
|
|
63
|
+
For an explicit classic-registration fallback, provide the complete editor preset:
|
|
64
|
+
|
|
65
|
+
```js
|
|
66
|
+
export default defineThemeBuild({
|
|
67
|
+
root: import.meta.dirname,
|
|
68
|
+
editor: {
|
|
69
|
+
entry: 'editor',
|
|
70
|
+
filename: 'applicationBlocksEditor.js',
|
|
71
|
+
sharing: 'independent',
|
|
72
|
+
discovery: {
|
|
73
|
+
filter: /application-blocks-editor\.js$/,
|
|
74
|
+
omitContexts: ({ pattern }) => ['styles-editor.css$', 'styles-editor\\.css$'].includes(pattern.source),
|
|
75
|
+
},
|
|
76
|
+
},
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
Independent entries do not preserve shared module state across separately compiled bundles: context providers and consumers spanning those bundles need an explicit compatibility solution. Rebuild and deploy matching scripts and metadata together when changing modes. Supplying `editor` replaces the whole preset; an explicit editor object without `sharing` retains the lower-level independent default.
|
|
81
|
+
|
|
57
82
|
### Lower-level build API
|
|
58
83
|
|
|
59
84
|
For a nonstandard project, run the following as a project-root `build.mjs`, adapting the paths to your project:
|
|
@@ -101,7 +126,7 @@ Run `bun run build.mjs`, add `--production` for minification, or `--watch` for a
|
|
|
101
126
|
|
|
102
127
|
`build` requires named entries and an output directory. By default, it builds each entry separately as browser ESM with splitting and hashed filenames, writes `manifest.json` and an `<entry>/<entry>.asset.json` with dependencies and a version hash, and returns `{ outdir, entries }`. Integrate these files with your WordPress enqueue code; this package does not enqueue them. Output is staged and published only after success. An existing output directory must have the build's ownership marker, and output paths and trees cannot contain symlinks. Do not use a directory containing the project root. `buildOptions` can override Bun defaults such as `target`, `format`, `splitting`, `naming`, loaders and plugins; callers must ensure the resulting format matches their WordPress loading strategy. Entry points, output directory and write mode are controlled by the build API.
|
|
103
128
|
|
|
104
|
-
For projects that prefer a validated configuration, `createPreset` and `buildPreset` are exported from `@eightshift/frontend-libs-tailwind/bun/preset.mjs`. Pass `wordpress: false`, `discovery: false`, `responsive: false` or `css: false` to disable the corresponding feature; discovery, responsive generation and CSS are opt-in. Configure CSS surfaces or pass a custom CSS callback. `buildOptions` accepts the same overrides as `build`. When an editor entry is enabled, `buildOptions.sourcemap` supports only `none` and `external`. The default `editor.sharing: 'independent'` keeps synchronous registration and lazy entries in separate bundles. Its lazy editor URLs use a build-wide query version derived from the registration and lazy bundles; changing either invalidates all lazy URLs. The opt-in sharing modes below change graph layout, and unified mode also changes registration timing.
|
|
129
|
+
For projects that prefer a validated configuration, `createPreset` and `buildPreset` are exported from `@eightshift/frontend-libs-tailwind/bun/preset.mjs`. Pass `wordpress: false`, `discovery: false`, `responsive: false` or `css: false` to disable the corresponding feature; discovery, responsive generation and CSS are opt-in. Configure CSS surfaces or pass a custom CSS callback. `buildOptions` accepts the same overrides as `build`. When an editor entry is enabled, `buildOptions.sourcemap` supports only `none` and `external`. The lower-level default `editor.sharing: 'independent'` keeps synchronous registration and lazy entries in separate bundles; the conventional theme preset instead defaults to unified sharing. Its lazy editor URLs use a build-wide query version derived from the registration and lazy bundles; changing either invalidates all lazy URLs. The opt-in sharing modes below change graph layout, and unified mode also changes registration timing.
|
|
105
130
|
|
|
106
131
|
### Native editor sharing (experimental, opt-in)
|
|
107
132
|
|
|
@@ -120,7 +145,7 @@ export default defineThemeBuild({
|
|
|
120
145
|
sharing: 'native',
|
|
121
146
|
discovery: {
|
|
122
147
|
filter: /application-blocks-editor\.js$/,
|
|
123
|
-
omitContexts: ({ pattern }) =>
|
|
148
|
+
omitContexts: ({ pattern }) => ['styles-editor.css$', 'styles-editor\\.css$'].includes(pattern.source),
|
|
124
149
|
},
|
|
125
150
|
},
|
|
126
151
|
});
|
|
@@ -130,11 +155,11 @@ Native sharing preserves nested lazy imports and emits source maps when requeste
|
|
|
130
155
|
|
|
131
156
|
This mode requires readable Bun entry metadata and rejects dynamic imports that Bun inlines into the current chunk: those can lose native module namespaces, and dynamic self-imports were observed to generate an undefined helper in Bun 1.4.4-canary.1. These cases fail the build rather than silently falling back to different semantics. Native output must remain JavaScript and source maps, as with the existing editor pipeline.
|
|
132
157
|
|
|
133
|
-
Native sharing can substantially reduce total output while increasing the number of files requested by the editor. It does **not** guarantee faster startup or Webpack parity. Validate cold and warm editor loads, first-block rendering, options, custom plugins, worker URLs and module state before enabling it. No theme is opted
|
|
158
|
+
Native sharing can substantially reduce total output while increasing the number of files requested by the editor. It does **not** guarantee faster startup or Webpack parity. Validate cold and warm editor loads, first-block rendering, options, custom plugins, worker URLs and module state before enabling it. No theme is opted into native sharing automatically. Set `sharing: 'independent'` explicitly to restore independent chunks, or remove the entire editor override to use the theme preset's unified default; rebuild and do not mix outputs from different modes.
|
|
134
159
|
|
|
135
|
-
### Unified editor graph (
|
|
160
|
+
### Unified editor graph (theme default, compatibility-changing)
|
|
136
161
|
|
|
137
|
-
`editor.sharing: 'unified'` builds registration and all lazy editor code in one native ESM graph. Unlike `native`, it can share dependency instances between registration and lazy consumers. It does **not** preserve synchronous classic-script registration.
|
|
162
|
+
`editor.sharing: 'unified'` builds registration and all lazy editor code in one native ESM graph. Unlike `native`, it can share dependency instances between registration and lazy consumers. It does **not** preserve synchronous classic-script registration. The conventional theme preset now selects this mode by default; install matching Eightshift PHP module-readiness integration and check dependent consumers before switching. Lower-level callers must still opt in explicitly.
|
|
138
163
|
|
|
139
164
|
Use the native-sharing configuration above with `sharing: 'unified'`. Do not provide `editor.lazy` rewriting options; unified mode lets Bun discover native imports. It keeps the same lazy-transform rejection rules as native mode. Its JavaScript wrapper statically imports the editor graph and signals completion through `globalThis.eightshiftEditorModules.complete(import.meta.url)`. Generated editor asset metadata declares `format: 'module'` and `readiness: 'eightshift-editor-v1'`; frontend/admin and existing editor modes retain their previous metadata. Older classic-only PHP integration is incompatible.
|
|
140
165
|
|
|
@@ -171,13 +196,23 @@ A second native build compiles the original graph with bounded groups. Static na
|
|
|
171
196
|
|
|
172
197
|
In an isolated production-release comparison using Bun 1.4.4-canary.1, 4 KiB grouping reduced startup theme-JavaScript requests from 34 to 16 while increasing gzip bytes from 307108 to 309447. After rendering a CTA block, requests fell from 37 to 19 and gzip bytes increased from 388459 to 390798. Both variants registered 33 theme blocks and rendered three editable CTA fields without browser errors. These measurements used a synthetic editor page with the PHP readiness bootstrap and disabled browser cache; WordPress core assets are excluded. The same-source Webpack reference used 10 startup requests / 287529 gzip bytes and 12 requests / 366641 gzip bytes after the CTA. These results do **not** establish a repeatable latency improvement or Webpack parity. Measure your own editor and lazy interactions before opting in. Remove `pureJsxGroups` or set it to `false` and rebuild to roll back; independent and native-lazy modes remain unchanged.
|
|
173
198
|
|
|
174
|
-
The earlier `editor.sharedPackages` vendor-bridge experiment was removed. Existing experimental configurations must remove that option; it now fails configuration validation rather than silently changing initialization behavior.
|
|
199
|
+
The earlier `editor.sharedPackages` vendor-bridge experiment was removed. Existing experimental configurations must remove that option; it now fails configuration validation rather than silently changing initialization behavior. The lower-level API retains independent mode by default; the theme preset uses unified mode with the PHP compatibility requirements above. Native sharing remains opt-in.
|
|
175
200
|
|
|
176
201
|
### Theme build and watch integration
|
|
177
202
|
|
|
178
203
|
For `defineBuild` watch configurations with `ssr` or `publish` callbacks, explicitly set `watch.sources` or `watch.ignored`. Exclude every path those callbacks write inside the project root, including paths outside the preset output directory, to avoid rebuild loops.
|
|
179
204
|
|
|
180
|
-
`defineThemeBuild` from `bun/theme-build.mjs` supplies the conventional theme layout and
|
|
205
|
+
`defineThemeBuild` from `bun/theme-build.mjs` supplies the conventional theme layout and structured publication. `entries` replaces the complete entry map; `editor` replaces the editor preset or may be `false`. `responsive` accepts the preset's options or `false`. `css` accepts an async callback receiving `{ root, outdir, stage, responsive, require }` or `false`; `extraCss` still runs afterwards. `discovery` accepts a plugin factory receiving `{ root, setEditorWorker, getEditorWorker }` (also async) or `false`; with either override, callers must provide discovery compatible with their entry sources. `frontendStyles` applies only to default discovery. The built-in worker plugin runs before plugins returned by `createPlugins`; it resolves worker URLs for frontend, admin and editor bundles using `publicPrefix` and structured surface directories. When used separately without a public prefix, it can use the configured editor script URL identifier. Replace it via `media.editorWorker` when custom handling is needed. The returned plugin array is not modified. `ssr` replaces `buildSsr` or can be `false`; do not specify both. `publish` replaces the structured publisher with an async callback receiving the build state, or `false` leaves the intermediate build unpublished in `public/.build`. With custom or disabled publication, the SSR callback runs after the browser build and receives the build state, `mode: 'production'`, and `outdir` pointing to `public/.build/ssr/production`.
|
|
206
|
+
|
|
207
|
+
### Shared same-origin UI Components fonts (opt-in)
|
|
208
|
+
|
|
209
|
+
Set `sharedFonts: true` in `defineThemeBuild` only after installing compatible PHP shared-font integration (`infinum/eightshift-libs` 14.0.0-alpha.3) and a UI Components release containing `dist/assets/fonts-manifest.json` (`@eightshift/ui-components` 8.5.0-beta.1). These are the first published versions containing the shared-font contract; earlier releases do not provide it. Fonts remain required: this option changes their provider, not typography. The default is `false`, preserving standalone builds.
|
|
210
|
+
|
|
211
|
+
The current shared-provider contract supports WOFF2 only and rejects other manifest formats. The build verifies UI Components font bytes against their SHA-256 manifest, extracts matching compiled top-level `@font-face` rules from the published CSS, and stages `shared-fonts.json` plus `fonts/<sha256>.<extension>` alongside other assets. Unrelated or mixed-source faces, faces nested inside rules such as `@media`, `@supports` or `@layer`, and faces in separately loaded stylesheets remain in their original stylesheets. Extraction occurs before final stylesheet hashes are calculated. The default staged publisher is required; custom publication is rejected for this option. Missing manifests, integrity mismatches or no matching faces fail the build rather than silently omitting fonts.
|
|
212
|
+
|
|
213
|
+
Compatible Eightshift PHP integration must read the generated manifest and enqueue the required font declarations with same-origin URLs shared across participating themes/plugins. Deploy PHP support and the matching assets together. Existing consumers that embed their own font faces still download their own URLs until rebuilt with this integration. Separate frames still need declarations; browser caching can reuse common URLs when enabled. No remote CDN, database cache or shared-directory write is required.
|
|
214
|
+
|
|
215
|
+
The exported `prepareSharedFonts({ root, flatDir })` helper in `bun/shared-fonts.mjs` is also available for a custom build pipeline. Its historical `flatDir` parameter accepts the prepared publication tree (`publicationRoot`), including nested CSS. It mutates staged CSS and returns publication `extraFiles`/`aliases`; call it before hashing styles, and publish those additions atomically with the CSS. Do not run it directly on active public assets.
|
|
181
216
|
|
|
182
217
|
### Staged theme publication
|
|
183
218
|
|
|
@@ -219,6 +254,11 @@ are replaced on successful publication: they cannot preserve old browser session
|
|
|
219
254
|
like content-hashed filenames. Additional manifest generation and automatic
|
|
220
255
|
multi-release retention are not provided. Aliases join the primary manifest and
|
|
221
256
|
PHP asset cache; consumers needing separate manifests must use custom publication.
|
|
257
|
+
The lower-level `packageRelease` keeps a stylesheet's hashed output in the same
|
|
258
|
+
release directory as its input, preserving relative asset and `@import` URLs.
|
|
259
|
+
Empty stylesheets are valid and retain their manifest entries; missing stylesheets
|
|
260
|
+
and missing or empty JavaScript entries still fail packaging.
|
|
261
|
+
Its `omit` option cannot remove a JavaScript entry targeted by a generated bootstrap.
|
|
222
262
|
|
|
223
263
|
### Optimizing package imports
|
|
224
264
|
|
|
@@ -258,15 +298,25 @@ export default defineThemeBuild({
|
|
|
258
298
|
- `keys` optionally lists frontend importer keys, such as `components/video` or `custom/example`. Each must match a discovered `src/Blocks/{components,custom}/**/assets/index.js` file, and a key can belong to only one stylesheet group. When an importer is used, its stylesheet loads before the JavaScript; the load is shared between callers. A failed load rejects, removes the link, and can be retried. Without `keys`, the file is built and published but is not loaded automatically.
|
|
259
299
|
- `href` optionally overrides the URL used by those importers. By default it points to the generated output; custom URLs must be deployed and kept in sync by the project. It has no effect without `keys`.
|
|
260
300
|
|
|
261
|
-
|
|
301
|
+
Frontend and admin CSS imported by JavaScript is compiled with Tailwind and loaded before the importing module executes. Styles imported by lazy modules remain unloaded until those modules are requested. Imported stylesheets that generate utilities also scan the generated frontend responsive class list when responsive generation is enabled. Direct imports already included unconditionally by the default conventional CSS compiler are not loaded twice; conditional imports and `@reference` do not suppress a separate JavaScript import. A direct import that matches a single-file keyed `extraCss` group uses the same stylesheet URL as the keyed loader; multi-file groups and CSS modules are compiled independently. Existing `frontendStyles` and other multi-file group contents are not automatically deduplicated against JavaScript imports. When a stylesheet imports CSS modules, Tailwind `@import` modifiers such as `source()`, `prefix()` and `theme()` are not supported there. Import that configured Tailwind entry separately and use `@reference`; unsupported combinations fail the build rather than producing incorrect styles.
|
|
302
|
+
|
|
303
|
+
The generated browser modules use top-level `await` and add stylesheet requests, which can affect startup or lazy-load timings. If a keyed `extraCss` load fails before its module is imported, the loader can retry; a failed JavaScript module evaluation can remain cached by the browser and may require a page reload. Custom build plugins must not bypass the theme CSS loader unless they also provide custom publication; unexpected Bun CSS output fails the build instead of being silently omitted.
|
|
304
|
+
|
|
305
|
+
The default structured publisher includes generated stylesheets in `public/` and its manifest; no alias is required for lazy loading. The output hash changes when compiled CSS changes, including rewritten asset URLs. CSS assets are copied with their own content-hashed names. Publication replaces `public/`, so cached older pages can request files no longer present; retain old releases externally if that matters. For a stable PHP manifest key, set an explicit `output` and an appropriate `aliases` entry. Custom publishers must preserve the CSS and the URL expected by the importer.
|
|
262
306
|
|
|
263
307
|
The build regenerates discovery and CSS on each rebuild. Watch monitors the configured project paths, not `node_modules` or arbitrary external files by default; customize `watch.sources` for additional inputs. Default theme builds use production CSS processing, including Lightning CSS minification and its browser targets, even in watch mode. `extraCss` may also be an async hook receiving `{ root, stage, require }`, or `false` to disable it. Hooks are responsible for their own filenames and loading behavior. `frontendStyles` separately attaches existing URLs to keys; both automatic mechanisms require default discovery.
|
|
264
308
|
|
|
265
|
-
Default
|
|
309
|
+
Default structured publication requires frontend, admin and editor entries, an editor build, and CSS at the conventional filenames. It scans the conventional SSR source glob and expects matching outputs in `.bun-pilot/theme-build/ssr/production`. With default publication, custom `ssr` (or legacy `buildSsr`) callbacks receive `{ root, mode: 'production', outdir }`, where `outdir` is the absolute path to that SSR output directory. Callbacks must finish writing `<name>.js` files there before resolving, where `<name>` is the directory containing each conventional `assets-ssr` directory; `packageFlatRelease` reads those files from the same directory. Use `ssr: false` to omit SSR or supply custom publication for a different layout. Disabling responsive generation requires custom or disabled CSS. Custom publication is required when disabling CSS or the editor, or changing the entry set. With custom or disabled publication, intermediate output remains in `public/.build`; the project owns its publication and cleanup.
|
|
310
|
+
|
|
311
|
+
The default SSR builder compiles all discovered entries together into standalone Node CJS bundles, without shared chunks or sourcemaps. Output filenames remain `<block-or-component-directory>.js`; duplicate names are rejected before compilation. Caller-supplied plugins retain one sequential compilation per entry to preserve their per-build lifecycle. Compilation omits Bun's `outdir` so it stays in memory (Bun 1.4.4 can write files when `outdir` is set even with `write: false`). All outputs are validated before explicit writes; compilation failures leave existing files untouched. Returned `outputs[].path` is the publication path, while `outputs[].output.path` is Bun's intermediate artifact path. `write: false` never creates the output directory. The low-level builder does not prune old files when entries are removed; the theme preset rebuilds its owned staging directory. Writes are sequential, not an atomic transaction for I/O failures. Multi-entry compilation can retain additional dependency definitions and change bundle bytes; it does not guarantee byte identity with separate compilations.
|
|
266
312
|
|
|
267
|
-
|
|
313
|
+
Externalized `@wordpress/*` browser imports do not require matching JavaScript packages in the theme or plugin. Their exports and default-global mappings come from the target WordPress installation. Packages deliberately bundled by the adapter, and packages used by SSR or builds with `wordpress: false`, still need to be installed. React, React DOM and `lodash-es` also retain their installed-package export-discovery requirements.
|
|
268
314
|
|
|
269
|
-
`
|
|
315
|
+
WordPress externalization is enabled by default. Set `wpRoot` to the WordPress installation when using externalized `@wordpress/*` imports; export discovery reads its core scripts without requiring installed package metadata. WordPress scripts without an export table are treated as side-effect-only dependencies: no exported global is required, and their handles are retained even when Bun erases the empty adapter. Resolved side-effect-only handles are retained conservatively, including when their importing code is later tree-shaken. The adapter also maps React and selected common dependencies to WordPress globals. Those globals and script handles must be available at runtime. Set `wordpress: false` to disable this adapter. For direct Bun integration, `wordpressPlugin({ projectRoot, wpRoot })` returns `{ plugin, dependencies, getEmittedDependencies }`; use a fresh adapter for each build and absolute paths. `dependencies` contains all resolved handles. Request a Bun metafile and pass it to `getEmittedDependencies(metafile)` to derive handles from every emitted output; invalid metadata falls back to all resolved handles. Some Bun versions can throw when reading `result.metafile` itself, so catch that access and fall back to `dependencies` too.
|
|
316
|
+
|
|
317
|
+
`processCss` compiles the `files` array in order into one output file. Each item is a path or `{ file, content, scan, sources, scanFiles, removeSources }`: optional `content` replaces the source text while `file` remains the base for imports; scanning is opt-in; `scan: 'auto'` scans only when the stylesheet requests utility generation; `sources` adds Tailwind scanner source objects, `scanFiles` adds explicit candidate files even when those paths are excluded from automatic scanning, and `removeSources` removes exact source-rule strings (and fails if absent). Relative paths resolve from `projectDir`. Local URL assets, including string URLs in `image-set()` and `-webkit-image-set()`, are copied next to the CSS with content-hashed names. Production uses Lightning CSS and the `browsers` option (default `>= 0.25%`); the return value includes `outputFile` and discovered `dependencies`. Watch does not automatically use those dependencies. `responsive: {}` generates frontend and editor class lists from `src/**/manifest.json`, expanding responsive classes for `sm` and `md`; customize `breakpoints`, `manifestGlob`, and `output`. Pass the relevant generated list to CSS scanning, as above. The standalone `generateResponsiveClasses({ projectDir, ... })` is also exported from `bun/build.mjs`.
|
|
318
|
+
|
|
319
|
+
The editor discovery transforms match parsed JavaScript call expressions, not comments, string contents or JSX text. Generated context bindings avoid identifiers already present in the source. Unsupported executable `require.context` arguments still fail the build.
|
|
270
320
|
|
|
271
321
|
For Webpack context replacements, generate a module before building and import its named context in your application:
|
|
272
322
|
|
|
@@ -339,3 +389,90 @@ Eightshift Frontend Libs Tailwind is maintained and sponsored by
|
|
|
339
389
|
|
|
340
390
|
## License
|
|
341
391
|
Eightshift Frontend Libs Tailwind [Eightshift](https://eightshift.com) and [Infinum](https://infinum.com). This is free software, and may be redistributed under the terms specified in the LICENSE file.
|
|
392
|
+
|
|
393
|
+
### CLI watch process restarts
|
|
394
|
+
|
|
395
|
+
`eightshift-build watch` keeps ordinary source watching in the configured watcher.
|
|
396
|
+
It polls the selected config file and the working directory's `package.json`,
|
|
397
|
+
`bun.lock`, and `bun.lockb` for content changes (100 ms polling, 200 ms settling),
|
|
398
|
+
then drains the old worker before importing configuration in a fresh Bun process.
|
|
399
|
+
Missing files and atomic replacements are detected. Invalid configuration prints
|
|
400
|
+
its error and waits for another restart-input change instead of respawning in a loop.
|
|
401
|
+
A worker failure remains reflected in the supervisor's eventual exit status.
|
|
402
|
+
|
|
403
|
+
This is an explicit boundary, not dependency discovery. Nested dependency manifests,
|
|
404
|
+
installed library edits, imported config helpers, other lockfiles and environment
|
|
405
|
+
changes require manually stopping and starting the CLI. In particular, editing a
|
|
406
|
+
nested package's exports alone does not trigger a restart; changing a root restart
|
|
407
|
+
input afterward loads it fresh. Install transactions should finish before restarting.
|
|
408
|
+
Programmatic `defineBuild`/`watchBuild` behavior and custom watch options are unchanged.
|
|
409
|
+
|
|
410
|
+
SIGINT/SIGTERM request shutdown even during configuration loading. Interrupted
|
|
411
|
+
one-shot builds exit nonzero, including when stopped before the build begins.
|
|
412
|
+
The CLI waits
|
|
413
|
+
for config loading and the watcher's `stop()` promise; it never force-kills a slow
|
|
414
|
+
build or launches a concurrent replacement. A hung import or callback can therefore
|
|
415
|
+
hold shutdown indefinitely. Custom watchers must stop scheduling and drain all
|
|
416
|
+
work in `stop()`. Custom SSR/publication callbacks remain responsible for their own
|
|
417
|
+
transactional guarantees: process serialization does not provide rollback across
|
|
418
|
+
browser assets, SSR and custom publication. Reported build errors retain the
|
|
419
|
+
configured watcher's existing reporting/recovery behavior.
|
|
420
|
+
|
|
421
|
+
### Structured publication (only built-in layout; breaking change)
|
|
422
|
+
|
|
423
|
+
Conventional `defineThemeBuild` publication retains compiler surface subdirectories
|
|
424
|
+
(`frontend/`, `admin/`, `editor/`, `css/`). Public manifest keys remain stable, but
|
|
425
|
+
their target URLs change. Consumers must resolve assets through the manifest rather
|
|
426
|
+
than assuming root-level filenames. The `publicationLayout` option has been removed:
|
|
427
|
+
remove it even when its value was `'structured'`. Explicit use is rejected rather
|
|
428
|
+
than silently ignored. The legacy `flattenAssets` implementation/export is removed.
|
|
429
|
+
|
|
430
|
+
Migrate `publication` hooks to use the provided `publicationRoot` for the prepared
|
|
431
|
+
public tree, not `resolve(outdir, 'flat')`. This is a stable directory contract:
|
|
432
|
+
the directory contains the collected nested outputs before packaging, and aliases
|
|
433
|
+
are relative to it. Its absolute path is staging-only; do not persist it or depend
|
|
434
|
+
on its basename. Enumerate nested files when needed and include their directory
|
|
435
|
+
names in aliases. `outdir` remains the compiler staging directory. Fixed UTM/player
|
|
436
|
+
outputs remain supported through `extraFiles: [{ source, destination }]` and aliases
|
|
437
|
+
mapping public manifest keys to those destinations.
|
|
438
|
+
|
|
439
|
+
Custom `publish` functions and `publish: false` remain supported and own publication,
|
|
440
|
+
but theme compiler URLs now always target structured surface directories. Custom
|
|
441
|
+
publishers must preserve those paths or explicitly implement their own relocation.
|
|
442
|
+
A `publication` hook is preferred for extending the built-in publisher. Low-level
|
|
443
|
+
`defineBuild`, `packageRelease` and `packageFlatRelease` remain layout-neutral and
|
|
444
|
+
keep their existing defaults. Despite their historical names, `packageFlatRelease`
|
|
445
|
+
and `publishFlatRelease` in `bun/flat-publication.mjs` operate on prepared trees,
|
|
446
|
+
including nested files; their API is retained for existing custom publishers.
|
|
447
|
+
|
|
448
|
+
Structured conventional CSS omits unreferenced stable entry styles only after the
|
|
449
|
+
same-directory hashed stylesheet and manifest are generated. Alias targets and
|
|
450
|
+
references in packaged files or generated wrappers retain the stable stylesheet;
|
|
451
|
+
queries, fragments and escaped names are considered conservatively. Custom `css`
|
|
452
|
+
callbacks retain their entry styles. Hooks that construct CSS URLs dynamically
|
|
453
|
+
must pin the stable path with an alias; static inspection cannot certify computed
|
|
454
|
+
URLs. Extra styles, script intermediates and source maps are not blanket-removed.
|
|
455
|
+
Low-level packagers can opt into this scoped behavior with
|
|
456
|
+
`removeUnreferencedStyles: true`; this is not a general unused-asset collector.
|
|
457
|
+
|
|
458
|
+
This default does not change cache synchronization, retention, rollback policy,
|
|
459
|
+
or active site configuration. The removed flat layout cannot be restored with a configuration option; keep the
|
|
460
|
+
previous complete release and its compatible tooling when deploying or rolling back.
|
|
461
|
+
Low-level builds and presets optionally accept `entryPublicPaths`, an object mapping
|
|
462
|
+
existing entry names to root-relative public URL prefixes ending in `/`. Omitted
|
|
463
|
+
entries continue using `buildOptions.publicPath`; editor output keeps its editor
|
|
464
|
+
builder URL contract. Shared fonts support nested stylesheet paths.
|
|
465
|
+
|
|
466
|
+
Local CSS asset URL pathnames are percent-decoded once before filesystem resolution.
|
|
467
|
+
Query strings and fragments are preserved on published URLs. Encode literal `%`
|
|
468
|
+
characters as `%25`; malformed pathname encoding fails with an explicit error.
|
|
469
|
+
Remote URLs are left unchanged.
|
|
470
|
+
|
|
471
|
+
## Source formatting
|
|
472
|
+
|
|
473
|
+
Run `bun run lintJs bun bin linters scripts eslint.config.mjs` to check maintained
|
|
474
|
+
JavaScript sources. Add `--fix --fix-type layout,suggestion` to apply formatting
|
|
475
|
+
fixes. The repository configuration requires braces for control-flow statements,
|
|
476
|
+
blank lines before control flow and returns, and separation after blocks. These
|
|
477
|
+
rules also cover `.mjs` build helpers. Tests, packaged output, dependencies and
|
|
478
|
+
compiled output are excluded; the published consumer lint configuration is unchanged.
|
package/bin/tw-sweep.mjs
CHANGED
|
@@ -34,16 +34,25 @@ function parseArgs(argv) {
|
|
|
34
34
|
for (let i = 0; i < argv.length; i++) {
|
|
35
35
|
const a = argv[i];
|
|
36
36
|
|
|
37
|
-
if (a === '--entry')
|
|
38
|
-
|
|
39
|
-
else if (a === '--
|
|
40
|
-
|
|
41
|
-
else if (a === '--
|
|
42
|
-
|
|
43
|
-
else if (a === '--
|
|
44
|
-
|
|
45
|
-
else if (a === '-
|
|
46
|
-
|
|
37
|
+
if (a === '--entry') {
|
|
38
|
+
opts.entry = argv[++i];
|
|
39
|
+
} else if (a === '--include') {
|
|
40
|
+
opts.include = argv[++i].split(',').map((s) => s.trim());
|
|
41
|
+
} else if (a === '--exclude') {
|
|
42
|
+
opts.exclude = argv[++i].split(',').map((s) => s.trim());
|
|
43
|
+
} else if (a === '--ignore-file') {
|
|
44
|
+
opts.ignoreFile = argv[++i];
|
|
45
|
+
} else if (a === '--no-unknown') {
|
|
46
|
+
opts.unknown = false;
|
|
47
|
+
} else if (a === '--root-font-size') {
|
|
48
|
+
opts.rootFontSize = Number(argv[++i]);
|
|
49
|
+
} else if (a === '--write') {
|
|
50
|
+
opts.write = true;
|
|
51
|
+
} else if (a === '--check') {
|
|
52
|
+
opts.write = false;
|
|
53
|
+
} else if (a === '-h' || a === '--help') {
|
|
54
|
+
opts.help = true;
|
|
55
|
+
} else if (a.startsWith('--')) {
|
|
47
56
|
console.error(`Unknown flag: ${a}`);
|
|
48
57
|
process.exit(EXIT_USAGE);
|
|
49
58
|
} else {
|
|
@@ -96,7 +105,9 @@ function findDefaultEntry(cwd) {
|
|
|
96
105
|
|
|
97
106
|
for (let dir = cwd; ; dir = resolve(dir, '..')) {
|
|
98
107
|
for (const name of candidates) {
|
|
99
|
-
if (importsTailwind(resolve(dir, name)))
|
|
108
|
+
if (importsTailwind(resolve(dir, name))) {
|
|
109
|
+
return resolve(dir, name);
|
|
110
|
+
}
|
|
100
111
|
}
|
|
101
112
|
|
|
102
113
|
const wpThemes = resolve(dir, 'wp-content/themes');
|
|
@@ -104,12 +115,16 @@ function findDefaultEntry(cwd) {
|
|
|
104
115
|
if (existsSync(wpThemes)) {
|
|
105
116
|
for (const theme of readdirSync(wpThemes)) {
|
|
106
117
|
for (const name of candidates) {
|
|
107
|
-
if (importsTailwind(resolve(wpThemes, theme, name)))
|
|
118
|
+
if (importsTailwind(resolve(wpThemes, theme, name))) {
|
|
119
|
+
return resolve(wpThemes, theme, name);
|
|
120
|
+
}
|
|
108
121
|
}
|
|
109
122
|
}
|
|
110
123
|
}
|
|
111
124
|
|
|
112
|
-
if (resolve(dir, '..') === dir)
|
|
125
|
+
if (resolve(dir, '..') === dir) {
|
|
126
|
+
return null;
|
|
127
|
+
}
|
|
113
128
|
}
|
|
114
129
|
}
|
|
115
130
|
|
|
@@ -149,6 +164,7 @@ async function main() {
|
|
|
149
164
|
|
|
150
165
|
if (args.help) {
|
|
151
166
|
printHelp();
|
|
167
|
+
|
|
152
168
|
return EXIT_OK;
|
|
153
169
|
}
|
|
154
170
|
|
|
@@ -157,6 +173,7 @@ async function main() {
|
|
|
157
173
|
|
|
158
174
|
if (!entryPath || !existsSync(entryPath)) {
|
|
159
175
|
console.error(entryPath ? `Entry CSS not found: ${entryPath}` : "Could not locate a Tailwind CSS entry that imports 'tailwindcss'. Pass --entry <path>.");
|
|
176
|
+
|
|
160
177
|
return EXIT_USAGE;
|
|
161
178
|
}
|
|
162
179
|
|
|
@@ -166,6 +183,7 @@ async function main() {
|
|
|
166
183
|
ignore = loadTwIgnore(args.ignoreFile, cwd).map((pattern) => new RegExp(pattern));
|
|
167
184
|
} catch (error) {
|
|
168
185
|
console.error(error.message);
|
|
186
|
+
|
|
169
187
|
return EXIT_USAGE;
|
|
170
188
|
}
|
|
171
189
|
|
|
@@ -179,7 +197,9 @@ async function main() {
|
|
|
179
197
|
const found = new Set();
|
|
180
198
|
|
|
181
199
|
for (const pattern of includes) {
|
|
182
|
-
for (const m of await glob(pattern, { cwd, ignore: excludes, absolute: true }))
|
|
200
|
+
for (const m of await glob(pattern, { cwd, ignore: excludes, absolute: true })) {
|
|
201
|
+
found.add(m);
|
|
202
|
+
}
|
|
183
203
|
}
|
|
184
204
|
|
|
185
205
|
files = [...found].sort();
|
|
@@ -187,6 +207,7 @@ async function main() {
|
|
|
187
207
|
|
|
188
208
|
if (files.length === 0) {
|
|
189
209
|
process.stderr.write('No files matched.\n');
|
|
210
|
+
|
|
190
211
|
return EXIT_OK;
|
|
191
212
|
}
|
|
192
213
|
|