So testing the existing, updated theme against the newly created one uncovered the underlying issue:
bud.config.js
:
app
.entry({
normalize: {
import: ["@styles/normalize"],
},
app: {
import: ["@scripts/app", "@styles/app"],
dependOn: ["normalize"],
},
})
The normalize
entrypoint is declared a dependency of the app
entrypoint.
The normalize
entrypoint should be enqueued before the app
entrypoint.
Rationale behind a separate `normalize` stylesheet
The rationale behind is that Gutenberg/FSE enqueues its own frontend `global-styles` stylesheet. This stylesheet is enqueued before the theme `app` stylesheet, which is fine, as it allows the theme to override those default `global-styles` styles. However, when the theme also ships with normalize/reset styles (which is very useful btw.), those styles will override the Gutenberg-specific styles and cause issues. Hence separating `normalize` and `app` styles allows to move the `normalize` stylesheet before the theme stylesheet, fixing the issue.When this dependency is declared and normalize
and app
entrypoints enqueued,
app.js
is not executed, albeit its <script>
element being rendered and fetched by browser. The webpack-specific extra logic inside somehow expects the normalize
entrypoint script before execution.
And here lies the underlying issue: The normalize
entrypoint is declared with a stylesheet only, no script file. But the manifest.json
generated during theme build contains a normalize.js
, and no normalize.css
. So entrypoints appear, at least in recent Sage 10, being expected to always having a script file, even if just a stylesheet should be used.
Now I could add an empty script file, but this results in an additional, unnecessary file and I would really want to avoid this. Also this behavior looks like a bug.
Edit: The build fails now:
✘ sage ./public [f9899bd0b87f52832cf4]
│
├─ ✘ error
│
│ Cannot read properties of undefined (reading 'config')
│
│
├─ ✘ error
│
│ Cannot read properties of undefined (reading 'config')