Working on a client's site built with Sage by another dev

sage
1

Hello!

I have never built a WP site with Sage and I am contracted to build a page on a client’s site that has been built with Sage. I tried building a page template in the way I do for other WordPress sites, using a template-[name].php file in a folder I created for this project in the Sage theme’s root folder, and then selecting that template as the template for the page in the WP UI, and it did not work.

After doing some reading on Sage, I see that it requires a dev environment setup including the installation of various packages to use everything the theme/system provides and build the site to make it ready for production. I am hoping to avoid bothering with that and proceed with the project without needing to learn/use that in the interest of staying within the allotted time for this contract.

Some questions:

  • I moved the template and associated styles into subfolder I created in the “resources/views” folder (based on this article) and it seems to be working without breaking the site. My understanding is that there is a “build” process for Sage. Will the existence of these files break the build process? I ask even though it’s working because I saw another post on this forum where the answer to a similar question was that they need to setup the Sage dev environment and work within that. ( Sage 9, beginner’s questions - sage - Roots Discourse )
  • I am not using Laravel or Blade templates as part of this project. Is that a problem?
  • If I wanted to test things myself, how would I find the version of Sage being used and the other parts of the Sage setup? For the Sage version, is the latest entry in CHANGELOG.md the version being used? For the parts of the Sage setup, is everything listed in package.json required for the testing/build? It looks like this site is using Vite instead of Bud and is also using Alpine. I couldn’t find any official documentation on using Vite with Sage; am I missing something or is this something custom?

Any guidance is appreciated.

2

Hi @spsrohan,

Welcome! I’ll try to shed some light on some of your questions, but the ‘Sage 9 beginners questions’ response is still great advice in general. It’s worth tracking changes with GIT and getting the build system set up properly.

Can I add templates to resources/views/** without breaking the build?

Adding *.blade.php files to resources/views won’t break the build process or be overwritten. Blade templates are compiled + cached or retrieved at runtime.

Adding styles or JS to this folder isn’t a good idea though. They won’t be overwritten, but this does break convention, and is the start of a slippery slope towards an unmaintainable mess.

I am not using Laravel or Blade templates as part of this project. Is that a problem?

No problem at all. You can opt in / out of Blade as required. *.blade.php files can be used with plain PHP code.

How would I find the version of Sage being used?

CHANGELOG.md could hint at the version used to seed the project. You could also check composer.json. If composer.json refers to roots/sage-lib as a dependency, you’re running Sage 9.x. If not, it’s likely Sage 10.x.

Is everything listed in package.json required for the testing/build?

Probably, yes.

Generally speaking, running composer install and yarn or npm install should set you up with everything required.

Is using Vite with Sage officially supported?

As far as I know, no. It’s quite possible that your project was started with something like GitHub - 8bit-echo/sage-vite: A WordPress theme based on sage with Vite tooling and HMR Support .

If it looks like it is, I’d highly recommend skimming over that readme, and make use of the build system.

Setting up a compatible dev environment isn’t usually that complex, and most of the tooling is easily installed. If you’re working on a dev server already, you might find all it takes to fire up a great developer experience is to run yarn dev or equivalent.

I might be overstepping the mark here, but I can’t stress enough how beneficial being confident with composer and npm is. You don’t need to learn them in depth, just know enough to operate them.

I hope that’s useful, and apologies if some of it is vague. It’s hard to know exactly what you’re working with.

2 Likes
3

Hi @talss89 , appreciate the in-depth response very much.

Regarding your comment about opting in/out of Blade, you mention the .blade.php files. The template files that I created in the resources/views/* folder are just *.php files not *.blade.php files. I will change them to *.blade.php but just wondering if the plain old *.php files are an issue.

I did find that rep you linked with that combines Sage + Vite and also this other one (ravorona/sage: Wordpress theme, based on Sage starter theme (github.com) ) and unfortunately neither of them look exactly like or close to the setup of this particular site.

As an aside, it seems like my site is using Sage 10 (based on the lack of roots/sage-lib anywhere in the project and the Changelog.md entries), and if I’m not mistaken, the 8bit-echo/sage-vite rep is using Sage 9.

I appreciate your comment about being confident in composer and npm. I am definitely not and have only ever copy-pasted the scripts in my CLI to install whatever was needed. I am very new to dev work and have been thrust into it out of necessity. I am currently drinking from a firehose, so-to-speak, but will take your advice and learn those.

I have also figured out how to install a clean version of Sage 10 on my Windows computer in a “sandbox” (I’m using LocalWP by Flywheel) and get everything working (i.e. installing WSL, Acorn, Bud, nvm-windows, npm, node, etc.). It was not as straightforward as I would have hoped :sweat_smile:.

4

No problem at all, and glad to hear you’re making progress on your project.

I haven’t dived into the template inclusion logic in Sage, but I’d guess that using plain *.php files is no issue at all. Someone else may be more familiar and able to confirm that. They won’t be overwritten or break the build in any case.

Great work on identifying Sage 10, and getting a Local dev environment set up. I don’t use Local by Flywheel, but it sounds like you’re very close to getting the Vite build process to run if you haven’t already.

Don’t worry about it not feeling straightforward - Windows is the reason why.

PS. The scripts section of package.json might give you some clues as to how to run the build pipeline.

1 Like