Sage "9.1": Please test

Note: Changed Sage 9.2 to 9.1 (as 9.0.10 is the current release in master).

Updated Sage 9.x

You can now try out the Sage PR branch for webpack 5 and updated dependencies.
The sage-installer which is used by Sage 9.x for adding framework support was also updated to add the right configuration and styles. Bootstrap 5 (Beta2) has been added for selection. Tailwind 2 is used now.

Trying it out now!

To prevent siloing of existing working forks of Sage 9 + (insert framework), please try this setup as it applies the fixes via PRs.

You can create a new Sage 9 project from this PR branch by using the following command:

composer create-project roots/sage your-theme-name dev-webpack5 --repository='{"type":"vcs","url":""}'

(it may take a moment as composer usually iterates over some branches in the repository)

Updating an existing Sage 9 theme (quick guide)

  1. Create a new Sage 9 project with the command above,
    select the framework that is also used by your own Sage 9 project.
  2. (It is assumed that your own Sage project is already under version control (as git).
    Copy all the files of the newly created, empty Sage 9 project over the ones of your own Sage 9 project,
    overwrite everything. You can skip the vendor/ folder to speed things up slightly.
  3. Use diff/merge tools to resolve any differences, apply your own configuration and adjust it if necessary. Updating to webpack 4 and 5 requires surprisingly little configuration changes.
  4. Invoke composer update or, if there is trouble, remove the composer.lock file (it shouldn’t cause issues most of the time) and invoke composer install.
  5. Invoke npm install, or, if there is trouble, remove the package-lock.json and/or yarn.lock (it shouldn’t cause issues as the base dependencies are already maxed out) and invoke npm install.
    Also note that recent npm is much faster than in the earlier days, so you may want to switch back to npm, but this is up to you.
  6. Invoke npm run build, the theme should build fine, fix your re-applied configuration if otherwise.
  7. Test your theme, styles and images should load as before.


Report issues you encounter with the blank theme and your updated theme, so the PRs for Sage 9.x and sage-installer can be merged.

Related PRs

Sage 9 problems problems problems
__webpack.hmr Error 404 not found
Yarn build eror
Browsersync page refresh loop
Tailwind 2 sage 9.0.10
Wordpress links and Browsersync server
Sage: Displaying images in assets / images folder
Sage 9 Font Issue : resolve-url-loader
What version of sage is a reliable one?
Module build failed: TypeError: this.getOptions is not a function
"No files matching the pattern" then "Module build failed" errors for new user
Browsersync stuck loading when proxying Trellis local dev site
Javascript wrong in yarn start (while correct in build or build:production)
Sage 9 browsersync not updating right
Sage 9 hot reloading not working
Issue with custom fonts import and Sage 9.0.10
Relative asset paths issue in SCSS files - Sage 9
Sage 9 Font Issue : resolve-url-loader
How to remove unused CSS in sage 10 bootstrap theme
Error Loading images in css using resource relative path ../
Sage 9 w/ React
PostCSS Loader has been initialized using an options object that does not match the API schema
Base64 SVG erros on :production
Error when compiling with fonts
Update Bootstrap to v4.6.0 in Sage 9.0.9
Sage 9 illuminate/support conflicts with custom plugin trying to use latest illuminate/support
Error following tutorial about slick-carousel
Sage 9 Font Issue : resolve-url-loader
Sage fails to build on ARM Mac
Still recommend using Sage 9 in a new project?
Sage 9 and webp image format
No dist folder output on updated Sage 9 theme
No Source CSS shown in Developer Tools
Proper Way To Add Fonts To Sage 9 Theme
SCSS URLs displayed as [object Object]
Yarn build:production fails on Bootstrap compilation
Reloading the page applies all past hot-updates
Yarn install has a lot of warnings
Using Sage 9 with Valet Share - Asset Paths
When an imported css file refers to an image in a node_module folder
Operation not permitted, copyfile
Run Prettier in Sage 9 with Tailwind

It would be good if TailwindCSS was fixed.

I have an easy fix, and I could tell you what I did, but not sure I’d be able to contribute to it.

Edit: Actually, my mistake - I think? Well, not sure anymore. It works with this code. Ummm. Sage is soo unmaintained. Though this 9.2 sage seems to be working alright so far. I’m impressed xD

I wonder how much money they need to support development of this. WordPress is soo behind… I wouldn’t giving some money each month to support the dev of this… and so would other thousands of devs wouldn’t mind am sure. It makes the work soo much easier etc… there are still a few things that are bit uff. Plus the more support it gets, the more people will use it, more yt videos etc…

IMHO one issue is that node versions become unsupported, which can cause issues with bindings.
package rot rogether with the need for then bumping the node version often results in incompatible node packages, forcing one to update to newer packages. Also the switch from composer 1 to 2 forced me to update existing sage projects.
And some packages like the Imagemin Mix for Laravel Mix hasn’t been updated for 2 years now and doesn’T currently work with Laravel Mix…

production builds log a warning/notice message I try to get rid off:

[DEP_WEBPACK_COMPILATION_ASSETS] DeprecationWarning: Compilation.assets will be frozen in future, all modifications are deprecated.
BREAKING CHANGE: No more changes should happen to Compilation.assets after sealing the Compilation.
        Do changes to assets earlier, e. g. in Compilation.hooks.processAssets.
        Make sure to select an appropriate stage from Compilation.PROCESS_ASSETS_STAGE_*.
(Use `node --trace-deprecation ...` to show where the warning was created)

How can this be fixed? The assets are changed twice or something?

It worked to me.

yarn build:production
yarn run v1.22.10
$ webpack --mode=production --progress --config resources/assets/build/webpack.config.js
46% building 2/3 entries 10/10 dependencies 8/9 modules
warn - Tailwind is not purging unused styles because no template paths have been provided.
warn - If you have manually configured PurgeCSS outside of Tailwind or are deliberately not removing unused styles, set `purge: false` in your Tailwind config file to silence this warning.
warn -
92% sealing asset processing ESLintWebpackPlugin(node:2543) [DEP_WEBPACK_TEMPLATE_PATH_PLUGIN_REPLACE_PATH_VARIABLES_HASH] DeprecationWarning: [hash] is now [fullhash] (also consider using [chunkhash] or [contenthash], see documentation for details)
(Use `node --trace-deprecation ...` to show where the warning was created)
95% emitting emit(node:2543) [DEP_WEBPACK_COMPILATION_ASSETS] DeprecationWarning: Compilation.assets will be frozen in future, all modifications are deprecated.
BREAKING CHANGE: No more changes should happen to Compilation.assets after sealing the Compilation.
	Do changes to assets earlier, e. g. in Compilation.hooks.processAssets.
	Make sure to select an appropriate stage from Compilation.PROCESS_ASSETS_STAGE_*.
99% done plugins FriendlyErrorsWebpackPlugin


assets by chunk 3.96 MiB (name: main)
  asset styles/main_de31624e.css 3.96 MiB [emitted] [immutable] [big] (name: main)
  asset scripts/main_de31624e.js 1.04 KiB [emitted] [immutable] [minimized] (name: main)
asset scripts/customizer_de31624e.js 426 bytes [emitted] [immutable] [minimized] (name: customizer)
asset assets.json 161 bytes [emitted]
Entrypoint main [big] 3.96 MiB = styles/main_de31624e.css 3.96 MiB scripts/main_de31624e.js 1.04 KiB
Entrypoint customizer 426 bytes = scripts/customizer_de31624e.js
webpack compiled with 3 warnings
✨  Done in 18.42s.

Did you do yarn build:production? Generally speaking you should be using yarn, not npm (edit: for this particular project, since roots sage is mainly on yarn) - I found when using npm there are some issues, even tho there’s almost no difference between yarn and npm.

When working on your starter theme, yarn build:production works just fine.

1 Like

Further bug fixes have been added, so if you still had some problems it may work better now:

What about Sage 10 instead of Sage 9? I’m getting confused with all of this :smiley:

1 Like

This is primarily meant for updating existing Sage 9 themes so they build again properly (newer node and npm versions). Updating should be easy as most what is changed consists of “glue” code.
Then there are some devs that have familiarized with Sage 9 and are still learning Sage 10 (notably the webpack and acorn part), hence they will still start new theme projects with Sage 9.

Webpack starts up with errors in docker

Development environment

  • Node JS version: 14.16.0
  • Docker
  • Bedrock

Step to reproduce:

  1. run “composer install”
  2. run “npm install”
  3. run “npm run start”

After starting, errors begin to appear in the console:
UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). To terminate the node process on unhandled promise rejection, use the CLI flag --unhandled-rejections=strict (see (rejection id: 14748)

After build does not start.

  1. Does a normal build / production build (no watch) work?
  2. What is the compelte error message, from what node module, file and line does it come from?
  3. Are you building inside the Docker container? What OS? WSL 2?
  1. The build goes well through “npm run build”
  2. Anywhere, installing Node 10 helped fix, but browsersync does work.
  3. OS: Linux Mint 20.1, Inside docker.


I’m testing this new version. It works, but I noticed that the scss compiling takes longer after every change. It takes everytime 1 second more. After few changes all the process starts to be very very long.

Thanks for testing. Does this increasing delay only occur during watch-builds or also development/production builds?


it happens during the development, watching the files with the browsersync.

Thanks for the great instructions. I have been trying to get tailwind working for a few days now with no luck, before finding this.

The reason is that Sage (9.x) uses an extra script that adds modifications on top of the base Sage files.
These modifications also had to be updated to be compatible with the new fixes.

Trying this out! Running into an issue with background-image properties that use url(), such as

.page-header {
  background-image: url("/app/themes/abundanthousingma/resources/assets/images/bg-home-outlines.svg");

That version ^^ works w/ Sage v9.0.10. With this bleeding edge version, this error shows up:

♠ yarn build
yarn run v1.22.4
$ webpack --progress --config resources/assets/build/webpack.config.js
assets by path images/ 1.65 MiB
  assets by path images/*.png 535 KiB 10 assets
  assets by path images/*.svg 115 KiB 8 assets
  assets by path images/*.jpg 1.01 MiB
    asset images/bg-page-header.jpg 945 KiB [compared for emit] [from: images/bg-page-header.jpg] [copied] [big]
    asset images/hamilton-affordable-housing-advocates-logo.jpg 37.3 KiB [compared for emit] [from: images/hamilton-affordable-housing-advocates-logo.jpg] [copied]
    asset images/jp-yimby.jpg 30.2 KiB [compared for emit] [from: images/jp-yimby.jpg] [copied]
    asset images/brookline-for-everyone-logo-square.jpg 26.5 KiB [compared for emit] [from: images/brookline-for-everyone-logo-square.jpg] [copied]
assets by path scripts/*.js 29.5 KiB
  asset scripts/main.js 25.8 KiB [emitted] (name: main) 1 related asset
  asset scripts/customizer.js 3.73 KiB [compared for emit] (name: customizer) 1 related asset

ERROR in ./styles/main.scss
Module build failed (from ../../node_modules/mini-css-extract-plugin/dist/loader.js):
ModuleBuildError: Module build failed (from ../../node_modules/css-loader/dist/cjs.js):
Error: Can't resolve '/app/themes/abundanthousingma/resources/assets/images/bg-page-header.jpg' in '/Users/jeffbyrnes/dev/'
    at finishWithoutResolve (/Users/jeffbyrnes/dev/
    at /Users/jeffbyrnes/dev/
    at /Users/jeffbyrnes/dev/
    at eval (eval at create (/Users/jeffbyrnes/dev/, <anonymous>:16:1)
    at /Users/jeffbyrnes/dev/
    at eval (eval at create (/Users/jeffbyrnes/dev/, <anonymous>:27:1)
    at /Users/jeffbyrnes/dev/
    at /Users/jeffbyrnes/dev/
    at eval (eval at create (/Users/jeffbyrnes/dev/, <anonymous>:15:1)
    at /Users/jeffbyrnes/dev/
    at processResult (/Users/jeffbyrnes/dev/
    at /Users/jeffbyrnes/dev/
    at /Users/jeffbyrnes/dev/
    at /Users/jeffbyrnes/dev/
    at context.callback (/Users/jeffbyrnes/dev/
    at Object.loader (/Users/jeffbyrnes/dev/
    at processTicksAndRejections (node:internal/process/task_queues:94:5)

1 ERROR in child compilations (Use 'stats.children: true' resp. '--stats-children' for more details)
webpack compiled with 2 errors
error Command failed with exit code 1.

Figured it out, the value has to be updated like so:

.page-header {
  background-image: url("/images/bg-page-header.jpg");

It now treats the app/themes/abundanthousingma/resources/assets path as the root, but I should be clear that this doesn’t work:

.page-header {
  background-image: url("images/bg-page-header.jpg");

The url() value needs to be an absolute path, not a relative one.


IMHO this behaviour is better than the previous one where URLs had been relative to the main stylesheet, even inside other nested, imported stylehseets.

1 Like

I agree. Probably a change that should be messaged out in the CHANGELOG or README, however.