How to install/configure Sage 10 on Windows?

sage
,
1

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!

2

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).

4 Likes
3

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:

4

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.

5

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

6

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.

7

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:)

8

Yes, WSL is required :+1:

9

Do you know how much developers are there who are using Sage 10 with WSL? It feels lot of hassle for Win users now with Bud. And cant really find a good step by step tutorial how to set up sage 10 on windows.

2 Likes
10

I use it on a daily basis and I am very happy with it!

  • Put your source code onto the Linux file system as crossing filesystem boundaries hurt I/O a lot.
  • If you (understandably) want to store your source code somewhere else than just in your WSL 2 (ephemeral / testing) system, I use a privately hosted GitLab for that - but other solutions are also possible, like the (now free) GitHub private repositories.
  • Use Docker for Desktop with WSL 2 integration.
  • Prefer PHP 8.x for development on WSL 2 as I noticed a very significant performance improvement, in fact, loading of a huge site with lots of plugins and functionality only takes seconds on otherwise little optimized development. PHP 7.x also works fine though, just keep in mind that very slowly running sites could have a performance boost by using PHP 8.
  • VSCode is awesome in integrating with WSL 2.
  • I installed Node and PHP CLI (for dev tasks like updating composer) directly onto WSL 2 without containerization, as Node and PHP CLI versions can be easily managed using tools like nvm.
  • With the latest Windows 10 updates, you can now also run Linux GUI apps directly and seamlessly in Windows! You can launch them from start menu as any ordinary program or from a WSL 2 terminal! Though I prefer the native VSCode with WSL 2 integration (it uses a VSCode server on the WSL side to interface).
11

Ok thanks. May I ask how does your docker file look like?

12

I use a more complicated setup with a CA for self-signed certificates and Traefik.
At some point with more time I should write a guide about this I think.

As some starter setup you can look for “docker compose bedrock wordpress”, there are several docker-compose files that can be used. This should also work in WSL 2.

Alternatively there are also tools that set lots of things up automatically and can use docker under the hood.

13

Ok. Im not using bedrock. Only interested in Sage 10

14

Well, in this case you just need WSL 2 (Ubuntu recent or 20.x LTS) + have your code on the Linux filesystem (e.g. ~/src) and use nvm for managing the node versions inside WSL 2.
And you can use the Linux version of nvm, not the Windows one.

Then you can just do

  • nvm install lts/*
  • nvm use lts/*
  • npm install -g npm
  • npm install -g yarn
  • yarn install
  • yarn build (build) or yarn dev (watching)

For installing bud support extension for Sage:

15

At the moment I found to much hassle going WSL and bud. Many different errors not on Sage side but to get stable enviroment working. Lots file permission and so on errors.
Went for last commit with laravel mix. I have been using Win all my life so Im an ordinary Win dumb user :slight_smile: but some day I will try again.

16

I’m also struggeling with WSL2 and Sage/bud, cannot seem to run “yarn build”. Always get the error “/bin/sh: 1: bud: not found
error Command failed with exit code 127.”
And from what I gathered it seems that bud is not installed so it cannot execute the compiling. But I have added bud to my yarn install but still issues…
Also saw some posts saying running a cache clean will fix it but not in my case

17

When you use yarn install, does that command complete successfully?
Clean node_modules/ manually and retry yarn install.
When yarn install fails, bud may very well be not installed yet, hence the error.

1 Like
18

Thanks for your contribution.

However, for those that are new to Sage, there is still confusion about installation of Sage 10 in a Windows 10/11 + WSL2 environment.

I was able to run the yarn command and compile assets, without any visible error. But I don’t see how can I run the configuration steps. For instance, I would like to use Bootstrap instead of Tailwind.

Any suggestions?

19

There is a guide for replacing Tailwind with Bootstrap in Sage 10, which should be helpful: