Sage 10 - understanding the workflow

So this is a general question about Sage and I hope I can ask it here.

I just started at a company that is using Sage 10, the developer before me built the master template that they are now using. I’m new to Sage and the process I was shown to edit a live site or staging site that is using our Sage template seems very long and tedious. I wanted to reach out and see if anyone tell me if this process is correct or if the previous developer maybe missed something or wasn’t finished before he left.

The process for editing lets say a CSS style on a live site is:

1- I need yarn & node installed on server
2- FTP into server
3- edit CSS file (lets say sections.css, under resources>assets>styles)
4- Connect with Putty
5- Run Yarn build (or whatever the script command may be)

Do this process seem correct for something as simple as a CSS edit?

  1. No, you don’t need and also shouldn’t install node and yarn on the production system (the web server that is used by the public/customers). These are build dependencies that are used for building the theme. As a best practice, this should happen on a workstation or a build/CI server. Not on the production system.
  2. FTP isn’t preferable. Better is SSH/rsync or SFTP for securely and efficiently transfering files and changes from the workstation/CI/build/deploy server to the production system.
  3. Those are not CSS but SCSS files, though you can just use CSS as a valid subset of SCSS (SASS).
  4. Manual deployment should be avoided, roots also offers Bedrock and Trellis that help with further automating deployments.
  5. As explained in 1. you don’t want to build on the production system.

Simple CSS edits would encompass changing the theme, committing the change, building/pushing to CI, deploying the site with the new theme - or deploying just the theme if you don’t use Bedrock/Trellis.

So the best/proper practice workflow looks like this:

1 Like

Sage is built with a philosophy that is opposed to editing anything related to the code on a live site. @strarsis’s points are solid, but I’d also recommend reading this document, which lays out the philosophy behind Sage (and the roots stack in general):


Sorry, I did mean SFTP and SCSS.

@strarsis everything you said makes total sense. What it looks like on my end, is that the developer before me, did not set everything up correctly. He is no longer at the company I work for, so it’s my job now it get it all fixed.

I opened up the theme folder on a production site, “wp-content/themes/” and literally it has the whole folder structure, I’m talking about: /app, /dist, /node_modules, /resources, /storage, /vendor, /.vscode and even the webpack.mix.js file… everything…

But like I said, I’m completely new to Sage but im my experience, the only folder that should be on the web server is the “/dist” folder.

So I definitely have my work cut out for me and I have a lot of learning to do to learn Sage.

Please note that besides the public/ folder, Sage themes also need the vendor/ folder (runtime) and the resources/ folder for the views. This also depends a bit on the Sage version. Sage 9 needs some other folders than Sage 10. In the end, it should be sufficient to add everything of the Sage theme to Git repository, except the files and folders in the .gitignore, which notably are vendor/ and node_modules/.
Why also ignore vendor/ when it was just stated that it is required by the theme during its runtime?
The idea is that during deployment, as using roots Trellis for example, composer install would run on the server and let the server pull the PHP package dependencies from the composer repositories (notably and

When you don’t use roots Bedrock or Trellis, you can adjust the existing deployment flow, e.g. pull the composer dependencies on the workstation and then rsync them to server, or, if you really need/want to create a self-contained plugin ZIP (see Deployment on Shared Hosting).

It sounds like the previous developer left you the entire theme. If there isn’t already a git repo, I’d recommend downloading the entire theme, creating a new repo for it, and then setting up a more modern deployment system.

@alwaysblank so he developed and launch 5+ sites with the Sage framework theme that he designed. All of them have the complete folder structure in the theme directory. There is a git repo for each site. Plus there is a git repo for the “master” template that he built, which is what they are starting every new site with, it’s basically blank, just setup and configured with the settings he put in place.

But after reading some of the Sage documentations, he either didn’t know what he was doing or he wasn’t 100% complete and just started building new sites anyway.

I guess I’m not totally following what your problem is then. The repos should be the source of truth for each site, so if you need to update a site make your changes locally, run the build process, check your work in your local development environment, and then push any changed files to the remote server (or, ideally, use a system like Trellis that allows for no-downtime deploys).

Well I’m not sure if its a problem, I’m trying to get a better understanding of how Sage and the deployment process should work.

It looks like they are only using Sage 10, not using Bedrock or Trellis.

We are using Kinsta, so I went into each website’s server that is live and looked at the theme folder and each site has the complete folder structure of the git repo (everything that you would see when your building it locally for the firs time). They don’t have the repo connected to the server in anyway, so it looks like when the developer went to push a site live for the first time, he just manually copied everything from his local environment over to the server and than installed yarn & node on the server, then ran the build script.

So right now if I wanted to work on a live site in a local environment, I would have to clone the repo, then either use like a migration plugin like Duplicator to copy over the WP Database & plugins, etc., from the live site. Use a tool like Local by FlyWheel to run WP locally, run the migration tool locally and whatever else to get it up locally. Then when im done editing it and I run the build script, I could either copy over the changed files like you said or do what he did and probably just dragged the whole folder over to the server.

Or like I said earlier, since he has yarn/node installed on the server I can just SFTP to the server, edit the files and run the build right there on the server BUT when I was told that’s how they have been doing it, it just didn’t seem right. Which leads me to believe that the developer either didn’t fully know what he was doing or just didn’t care.

One should avoid to develop on a production server.

The developers usually have their own development system, like a VM (Vagrant) or Containers (e.g. Docker).
Often a staging server is put between the developers and the production system for more extensive review.

You can deploy to Kinsta with trellis: That’s what we did at my last agency and it worked great.

Generally you shouldn’t run the build process on a production server. It exposes you to potential vulnerabilities in the node ecosystem that are otherwise not a concern, and it uses up system resources on a system that shouldn’t be used for that. Always run the build process locally and transfer files to the production server. The only thing the production server should do is serve your site. If the previous developer was running builds on production, he was doing it wrong.

1 Like

Well it sounds like my suspicions were correct. I’m new to WordPress development, so I just wanted to double check. My background is mainly JavaScript, React/Nextjs, so this is a little bit of a learning curve, although I have built my far share of WordPress websites but using prebuilt themes/frameworks.

You guys have been very hopefully thank you!

Update: I pulled a fresh copy of the Sage 10:

composer create-project roots/sage your-theme-name dev-master

I followed the steps from:, did yarn start, browsersync started with no errors, the last line in the terminal is:

[Browsersync] Watching files...

So I edited a few different files and noticed that in the terminal browsersync did nothing after I saved the changes, meaning that it did not run/re-compile any of the files, it still said Watching files…

Any ideas why it would be working? This issue does not seem to be related to Local by Flywheel, seems to be Browsersync or something on my computer.

What OS are you using? OS X; WSL 2; Linux? Maybe BrowserSync has issues watching on that file system - which would mean it has to use polling - or it has issues doing both?

I’m on Windows 10 with WSL 2, using VSCode and using WSL 2 as the terminal. I’ve tried using PowerShell in VSCode terminal, same outcome.

I’m guessing it has issues watching the files because when I run yarn start, everything is the terminal looks normal, browsersync launches and displays the proxy & urls for the localhost and the last line says “[Browsersync] Watching files…” but like I said once I edit any files and save them, nothing changes/happens in the terminal.

Are you sure the files are really changed? Have you tried to directly change a file in the console (e.g. nano)? I noticed that sometimes WSL 2 can be in a wrong directory although it shows the path to the directory. cd out of it and then cd back in, maybe this helps.

Does this help:

I did notice that I have some webpack errors, so I searched online and came across this GitHub ticket: Watchpack Error (initial scan): Error: EACCES: permission denied, lstat '/mnt/c/...' · Issue #187 · webpack/watchpack · GitHub
I tried to do what he said to try, I can move my project into my Ubuntu directory but I cant launch a Flywheel Local WP site from that directory.

Also my original reply to this thread from yesterday, I should of posted it on this thread I started about the browsersync issue: Sage 10 Browsersync not refreshing - #16 by alwaysblank

It looks like this is a problem with WSL2 and Flywheel Local. I don’t think there’s anything in Sage that’s going to affect this particular issue. WSL2 is running its own virtual file system thingie and I haven’t used Flywheel’s Local in years but it probably either wants to do something similar or it wants file/system resources that it can’t get at when they’re in WSL2. In any event you may have better success talking to Flywheel, webpack, or WSL2 support.

I just tried it with Docker, I don’t get the webpack errors, but Browsersync still does not update when I edit & save any files (i.e. resources>styles>app.scss).

Can I ask what you guys use to run WordPress locally?

I’ve been pretty happy with