How to install/configure Sage 10 on Windows?

I’ve followed the installation instructions but I can’t find any information on what to do after running
composer create-project roots/sage your-theme-name

I’m using Windows 10 and on Sage 9 I would run the following commands to configure the theme but I can’t find a way to do this with Sage 10:
./vendor/bin/sage meta
./vendor/bin/sage config
./vendor/bin/sage preset

How do I set those fields in Sage 10 and install Tailwind? Right now if I try to activate the theme then WordPress says there is a “critical error” so clearly something isn’t configured that needs to be. Thanks!

I just went through this yesterday, Windows dev has some specific caveats and considerations re: Sage 10. I imagine they could be avoided if you opted to use Laravel Mix, or rolled your own Webpack for building assets, but wanted to see if I could get things working “out of the box” so to speak.

Unrelated, you should double check Acorn is active/installed first. Acorn is a requirement of Sage, so if Acorn is not active/detected when you activate Sage, it will result in a Critical Error.

As for the caveats - Bud is used as the new asset build pipeline, which states as a requirement that it must be run under WSL. While you should be able to run yarn to install your dependencies, running yarn build will fail if you’re not in WSL (Windows Subsystem for Linux).

If you are not familiar with WSL, you’ll want to go through Microsoft’s docs on what it is and how to install/configure. You’ll also need to setup PHP, Composer, Node, and yarn in WSL, and you’ll likely need to move the rest of your WordPress dev environment and files into WSL (that is, to the /home folder in WSL). If you want to keep everything accessible in Windows (i.e. keep files on your C drive, but still use WSL tools), you will likely need to fix some file mount permissions too.

Last bit, if you are using VS Code, you should look at their docs developing in WSL.

With everything configured, and within WSL on the command line, you should be able to just run composer install and yarn in your theme directory to install all dependencies, then yarn dev or yarn build for development/building assets.

Hopefully this is helpful, I’d be interested to hear from others how Windows development has been working with Sage 10, as again, I only just set this up yesterday (so maybe have got some things wrong, or am not aware of other edge cases).

3 Likes

Thank you, I appreciate your reply! I’ll have to look into WSL as I’m not familiar with it. I do have Acorn installed so at least that’s not the problem. I love developing with Sage but the setup always seems to be 1 step forward 10 steps back whenever I try to do it :weary:

While Sage 9 might have worked with without WSL, it wasn’t something that we ever supported. We’ve really tried to encourage Windows users over the years to run everything from a WSL environment. It’s been a requirement if you’ve ever wanted support on here or via GitHub :eyes:

Sage 10 comes with Tailwind CSS out of the box. Sage 10 doesn’t come with an installer to configure the theme like Sage 9 did.

How did you install Acorn? Is it activated? What is the “critical error” exactly? Please bring all relevant details to this topic if you’re looking for support, including showing the entire error message if there is one.

Is that supposed to say “with” or “without”?

There is nothing whatsoever about WSL on the Installation instructions so I’m not sure how someone new to Sage is supposed to figure that out. I installed Acorn per the Sage installation instructions using composer require roots/acorn

The “critical error” message from WordPress said the following: “There has been a critical error on this website. Please check your site admin email inbox for instructions.”

At the very bottom of that email I just saw that it does give some more info. I’m running Dev Kinsta as my development environment:

Error Details

=============

An error of type E_ERROR was caused in line 133 of the file /www/kinsta/public/mytheme/wp-content/themes/mythemename/vendor/roots/acorn/src/Roots/Acorn/Assets/Manager.php. Error message: Uncaught Roots\Acorn\Assets\Contracts\ManifestNotFoundException: The manifest [/www/kinsta/public/mytheme/wp-content/themes/mythemename/public/manifest.json] cannot be found. in /www/kinsta/public/mytheme/wp-content/themes/mythemename/vendor/roots/acorn/src/Roots/Acorn/Assets/Manager.php:133

Stack trace:

#0 /www/kinsta/public/mytheme/wp-content/themes/mythemename/vendor/roots/acorn/src/Roots/Acorn/Assets/Manager.php(101): Roots\Acorn\Assets\Manager->getJsonManifest()

#1 /www/kinsta/public/mytheme/wp-content/themes/mythemename/vendor/roots/acorn/src/Roots/Acorn/Assets/Manager.php(76): Roots\Acorn\Assets\Manager->resolve()

#2 /www/kinsta/public/mytheme/wp-content/themes/mythemename/vendor/roots/acorn/src/Roots/Acorn/Assets/AssetsServiceProvider.php(22): Roots\Acorn\Assets\Manager->manifest()

#3 /www/kinsta/public/mytheme/wp-content/themes/mythemename/vendor/illuminate/container/Container.php(873): Roots\Acorn\Assets\AssetsServiceProvi

I recently removed the general “Getting Started” guides from the docs site which were clear about requiring WSL. We’ve got an issue open about adding that notice to individual project installation pages :smiley:

Thanks for providing the full error message. Once you run yarn build you’ll be able to access your site.

Awesome, thank you! I would very much appreciate that being added to the docs :heart:

When I run yarn build I get the following error which is what prompted me to think that I was missing a configuration step. Is this likely caused by the fact that I’m not (yet) using WSL? Or something to do with my Webpack installation?

Validation Error: Invalid configuration object. Webpack has been initialized using a configuration object that does not match the API schema.
 - configuration[0].resolve.modules[2] should be a non-empty string.
   -> Folder name or directory path where to find modules.
 - configuration[0].resolve.modules[2] should be a non-empty string.
   -> Folder name or directory path where to find modules.
    at validate (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\schema-utils\dist\validate.js:105:11)
    at validateSchema (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\webpack\lib\validateSchema.js:78:2)
    at create (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\webpack\lib\webpack.js:111:24)
    at webpack (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\webpack\lib\webpack.js:158:32)
    at Compiler.invoke (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\@roots\bud-compiler\lib\cjs\Compiler\compiler.service.js:111:47)
    at async Compiler.compile (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\@roots\bud-compiler\lib\cjs\Compiler\compiler.service.js:77:26)
    at async production (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\@roots\bud-api\lib\cjs\api\methods\run\index.js:16:26)
    at async Bud.run (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\@roots\bud-api\lib\cjs\api\methods\run\index.js:19:35)
    at async Api.call (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\@roots\bud-api\lib\cjs\api\api.service.js:105:16)
    at async BuildCommand.run (C:\Users\Susie\DevKinsta\public\mytheme\wp-content\themes\mythemename\node_modules\@roots\bud\lib\cjs\cli\commands\base.js:85:9)
[process] » i  info      beforeExit
[process] » i  info      exit

(P.S. I promise I’m using a better theme name than “mytheme”/“mythemename”…I’m just using those as placeholders for purposes of sharing the error messages :smile:)

Yes, WSL is required :+1: