So I’ve just finished my first theme using sage. I’m ready to upload it to my clients site. I’ve run gulp --production now what? I’m not using bedrock or trellis. I bought the “The Development With Sage” which is extreamly disappointing at this stage and merely says to run gulp --production can anyone offer a little more detail than that? It’s my first project using all these technologies like NPM, gulp, bower so what do I need to include in the final product?
This is like when you get to the end of a TV series only to be left hanging…
You need all theme files, including the generated dist folder (don’t forget the vendor one as well) in a .zip to manually install the theme 
Oh, you don’t need the node_modules.
What about node_modules or bower_components? And all the “hidden” .files? Theres a lot of them, like .bowerrc, .editorconfig, .jshintrc, .travis.yml. I don’t even know what these files are or why they are there. Then there are things like gulpfile.js and bower.json?
What is the bare minimum required for the theme to function?
No, don’t upload node_modules or bower_componemts - what sage version are you using? 8.x it sounds like?
1 Like
The .files aren’t needed: They’re all for development, and aren’t needed (or used) in production. The “bare minimum” will depend on how your theme was development, but when I’m manually deploying a Sage-based theme, I generally upload everything in my theme directory except for node_modules and .git.
Would I need both assets and dist? Sorry I’m just trying to grasp this!
Technically you wouldn’t need assets as everything should be copied and built and placed in dist
So… think of it like this - -
/assets
These are your front end files - most notably your SCSS and JS. These are the files for you to work on and though they are used to build your front end they are never actually served to the browser. A normal persons web browser can’t load an SCSS file, right?
That’s why this stuff does get committed to VC but does not need to be on the server.
/bower_components
These are front end dependencies, like Bootstrap for example. They get installed with bower install into that bower_componentsdirectory and though you use them for your project you never actually touch them.
Take the bootstrap example - when you run gulp, before your stuff in /assets/styles/ gets compiled, Bootstrap’s styles get compiled first and added to the top of your (compiled and minified) stylesheet, then your stuff gets added below.
So if the steps were broken down into plain English it might go something like:
- Hey gulp, go get bootstrap from
bower_componentsand compile it into css. - Done, great! Now go get my styles from
/assets/styles/, and compile it to css. - Now merge those files together, bootstrap styles first then my styles below.
- Now minify those styles and save them to
/dist/stylesas styles.min.css so that the browser can get them.
The idea behind bower (and NPM, and Composer, and other package managers) is that if you needed to or wanted to you could update Bootstrap from like 3.2 to 3.5 (or something) by just updating the bower file and running bower install && gulp.
Make sense?
There’s never a need to put bower_components on the server because all that stuff is already built into your compiled assets.
The bower stuff doesn’t get version controlled because you never actually work on those files, when you need them you just use bower to install them.
/dist
These are the front end files that get served up to the browser. They get generated every time you run an applicable gulp command. That is why these need to go on your server.
These don’t go in version control though. It doesn’t hurt if they are there, but it doesn’t make sense because you can rebuild them any time by running gulp
/node_modules
These are all the little apps that make all this craziness possible - the sass compiler, the auto prefixing, the minifying, concatenating, how the build process runs - all this craziness is handled by the stuff in node_modules.
It doesn’t get version controlled for the same reason bower_components doesn’t get version controlled.
Sort of the same for the server, node_modules doesn’t need to go on the server because you are never running gulp on your server. You can upload them if you want, they won’t hurt anything, but if you’re just dragging the folder into an FTP client I’d block off about 20 years to wait for them to finish uploading. 
The . files don’t go on the server either - especially not .git.
So, in summary, at a minimum you’ll want all of your PHP files, and your /dist, /lang, /lib, and /templates directories.
Here’s a screen grab of an old Sage 8 site directory I have on a server somewhere. Note that none of the . files are needed, nor is the package.json file.
Hope this was helpful.
4 Likes
Yes very helpful. Thanks for taking the time to write such a long post. This should be a page in the Book!
1 Like