docs: document postinstall copy-out workaround for shopware-cli #1466 - #2487
Draft
Soner (shyim) wants to merge 1 commit into
Draft
docs: document postinstall copy-out workaround for shopware-cli #1466#2487Soner (shyim) wants to merge 1 commit into
postinstall copy-out workaround for shopware-cli #1466#2487Soner (shyim) wants to merge 1 commit into
Conversation
Developer Docs healthcheckStatus: Completed with |
A pure-SCSS theme that imports from `node_modules` (e.g. @fortawesome/fontawesome-free) fails `shopware-cli project storefront-build` because the storefront-root `node_modules` is deleted before `theme:compile` runs. Document the known `postinstall` copy-out workaround in the npm dependencies guide and link to it from the theme styling guide, with a reference to shopware/shopware-cli#1466 for the longer-term fix.
Soner (shyim)
force-pushed
the
docs/storefront-build-postinstall-npm-workaround
branch
from
August 31, 2026 11:15
945e8ea to
fe96932
Compare
|
|
||
| ## Using npm packages in a pure-SCSS theme (no JS entry point) | ||
|
|
||
| If your plugin is a **theme** and only consumes npm packages from SCSS (for example `@fortawesome/fontawesome-free` or any other package referenced via `@import` in your `theme.json` `style` entries), you will run into a chicken-and-egg problem with `shopware-cli project storefront-build`: |
Contributor
There was a problem hiding this comment.
Idk I find the chicken-egg wording a bit strange for the docs.
Suggested change
| If your plugin is a **theme** and only consumes npm packages from SCSS (for example `@fortawesome/fontawesome-free` or any other package referenced via `@import` in your `theme.json` `style` entries), you will run into a chicken-and-egg problem with `shopware-cli project storefront-build`: | |
| If your plugin is a **theme** and only consumes npm packages from SCSS (for example `@fortawesome/fontawesome-free` or any other package referenced via `@import` in your `theme.json` `style` entries), you will not be able to run `shopware-cli project storefront-build` successfully: |
|
|
||
| If your plugin is a **theme** and only consumes npm packages from SCSS (for example `@fortawesome/fontawesome-free` or any other package referenced via `@import` in your `theme.json` `style` entries), you will run into a chicken-and-egg problem with `shopware-cli project storefront-build`: | ||
|
|
||
| * `shopware-cli` only runs `npm install` for a storefront extension when it has a JavaScript entry point (`src/Resources/app/storefront/src/main.js`). |
Contributor
There was a problem hiding this comment.
I would put this part BEHIND "The result is that a theme.json/SCSS @import like app/storefront/node_modules/@fortawesome/fontawesome-free/scss/fontawesome cannot be resolved, and theme:compile aborts with:".
So the reading is order:
- Will not working
- Error message
- And then the reason (background info) why its not working
|
|
||
| Because the `postinstall` script of a storefront extension's `package.json` runs **before** the root `node_modules` directory is deleted, you can copy the parts of the package that `theme:compile` needs into a persistent (git-ignored) folder inside the theme. After that, the SCSS imports and `theme.json` `style` entries must point at that folder instead of `node_modules`. | ||
|
|
||
| The nested folder must contain a `node_modules` path segment, because `shopware-cli project format` / `validate` only ignore the storefront-**root** `node_modules` and `shopware-cli` only deletes that one level. A nested copy survives both steps. |
Contributor
There was a problem hiding this comment.
Not sure if I understand this part. What does nested folder mean? Maybe provide an example?
| * `shopware-cli project format` / `validate` do not flag the copied files because they live under a nested `node_modules/` path. | ||
| * The webfonts end up under `public/bundles/<theme>/static/fonts/` after compilation, which is what the SCSS expects at runtime. | ||
|
|
||
| This workaround is known to be fragile: it depends on `shopware-cli` running npm lifecycle scripts and on the cleanup deleting only the storefront-root `node_modules`. If you do not need npm packages in your theme, prefer keeping the theme free of `node_modules` imports. A longer-term fix (installing npm dependencies for a JS-less theme and deferring the `node_modules` cleanup until after `theme:compile`) is being discussed in [shopware/shopware-cli#1466](https://github.com/shopware/shopware-cli/issues/1466). |
Contributor
There was a problem hiding this comment.
Maybe you can also point to the normal asset adding workflow here as an alternative.
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.
Documents the known workaround from shopware/shopware-cli#1466 so theme authors can keep using npm packages (e.g.
@fortawesome/fontawesome-free) from SCSS while the upstream fix is still open.Problem
shopware-cli project storefront-buildfails for a pure-SCSS theme that imports fromnode_modulesbecause:npm installfor storefront extensions with a JS entry point, andmain.js, the storefront-rootnode_modulesis removed beforetheme:compileruns.Changes
guides/plugins/plugins/dependencies/using-npm-dependencies.mddescribing thepostinstallcopy-out workaround: emptymain.js,package.jsonpostinstallthat copies SCSS into.vendor/node_modules/...and webfonts intopublic/static/fonts/, updatedtheme.json/SCSSpaths, and.gitignoreentries.guides/plugins/themes/styling/add-css-js-to-theme.mdso theme authors find the workaround from the theme styling guide.webfontsto.wordlist.txt.Quality
make spellcheckpasses.make fix(markdown lint) passes.Refs shopware/shopware-cli#1466.