How do you actually deploy the Sage theme to a Wordpress site?!

I’m trying to build a ZIP file that can be uploaded directly to a Wordpress admin panel.

I found this discussion page which mentions just re-running the build process, and I’ve looked at the docs here, but they seem to be outdated (refer to Gulp instead of Yarn/Webpack).

Regardless, when I run yarn build:production, I don’t get an uploadable zip so I’m unsure about the proper deployment procedure here. Am I meant to zip up the whole project file after running this build process? There are about 40,000 files (literally) and 150mb in there including all the composer stuff so I assume I’m doing something way wrong…


1 Like

You are going to zip up the theme, but you can exclude the node_modules folder, which likely contains the bulk of those 40,000 files. You may want to keep this issue with style.css in mind if you’re deploying in a more traditional way.


Thanks for this! I’ve done as suggested in that style.css issue (moved style, functions.php and index.php to the root + changed the references in functions.php to the root directory), and I’ve tried activating my theme within Wordpress, but I get a “page not found” now for all pages of the site / admin (no sage errors though!). Here are the 3 things I changed in functions.php, as per that github issue:

  1. Moved style.css, index.php and functions.php to the root of the theme.

  2. Changed the source of the autoloading conditional in functions.php:

     if (!file_exists($composer = __DIR__.'/vendor/autoload.php')) {
             __('You must run <code>composer install</code> from the Sage directory.', 'sage'),
             __('Autoloader not found.', 'sage')
  3. Changed the source of the app map:$file = "/app/{$file}.php";

Think there might be something else wrong with my functions.php file? Perhaps something in this bottom section needs to change too?

    ['theme_file_path', 'theme_file_uri', 'parent_theme_file_path', 'parent_theme_file_uri'],
    array_fill(0, 4, 'dirname')
    ->bindIf('config', function () {
        return new Config([
            'assets' => require dirname(__DIR__).'/config/assets.php',
            'theme' => require dirname(__DIR__).'/config/theme.php',
            'view' => require dirname(__DIR__).'/config/view.php',
    }, true);

Do you have access to your server’s error log? That might help you identify where things are breaking. IIRC if the include statements are failing to find files, you’d see ‘file does not exist’ errors.

Ah cool, debug in wp-config.php was turned off. I’m getting this error:

Warning: require(/var/www/html/wp-content/themes/config/assets.php): failed to open stream: No such file or directory in /var/www/html/wp-content/themes/blog/functions.php on line 88

Line 88 is

'assets' => require dirname(__DIR__).'/config/assets.php',

mentioned above, so clearly something needs to be changed in that snippet as well.

I tried changing it to 'assets' => require '/config/assets.php', on the offchance that it was some directory issue, but this didn’t work either (obviously changed it for assets, theme and view but it still breaks on assets.

Update: Fix these errors. Needed to change these lines:

    ->bindIf('config', function () {
        return new Config([
            'assets' => require dirname(__DIR__).'/config/assets.php',
            'theme' => require dirname(__DIR__).'/config/theme.php',
            'view' => require dirname(__DIR__).'/config/view.php',
    }, true);


    ->bindIf('config', function () {
        return new Config([
            'assets' => require dirname(__DIR__).'/THEMEDIR/config/assets.php',
            'theme' => require dirname(__DIR__).'/THEMEDIR/config/theme.php',
            'view' => require dirname(__DIR__).'/THEMEDIR/config/view.php',
    }, true);

where /THEMEDIR/ is your theme’s folder name within /wp-content/themes/

So now I have my wp-admin back, which is one thing, but now I have a completely blank page when I try to visit my site. Have tried activating another theme and it works fine, but re-activating my Sage theme ends with a completely blank screen again. No WP errors, no JS console errors, no HTML content in source, nothing…

Why on earth is deploying with Sage so convoluted? Really regretting using this at this point… Is there some significantly more logical way to deploy this thing that I’m just not seeing?

1 Like

Whenever I’ve had to deploy Sage without Trellis I’ve always simply run the Sage version appropriate build production command, and FTPed the theme directory (sans node_modules) to the server. I haven’t had an issue. Do you have to use the ZIP method? Could you simply FTP the files up?

1 Like

I’m not using the ZIP method, I’m doing a push to Git and the pulling the theme directly into wp-content/themes. Have tried redoing yarn build:production directly from the server but no luck at all…

And the Git repo includes the build artifacts (the dist directory) and the composer libraries (the vendor directory)?

Could you share a link to the GitHub repo if it’s not private?

Could you post a screenshot of your appearance/themes screen with the theme activated?

Does cloning the theme into whatever your development environment is also product the white screen of death?

Have you tried re-saving your permalinks?

Is your front page set to a static page or a posts page correctly matching your development environment?

1 Like

Yes, it includes dist and vendor (although I’ve also run yarn build:production and composer install on the server to be sure

It’s on a private work repo unfortunately.

Could you post a screenshot if your appearance/themes screen with the theme activated?
Does cloning the theme into whatever your development environment is also product the white screen of death?


This may be a clue actually. On my remote server I get a blank screen, but now (after moving the functions.php / etc into the root directory) when I run it locally i get this:

and in the admin section I see The active theme is broken. Reverting to the default theme.

Not sure what this entails. It’s a brand new wordpress install though

It uses a static front page (which exists on both server and local)

Okay. The problem is the changes you made to move style.css and functions.php to the theme root. Considering you’re not distributing the theme, I recommend reverting that change and putting style.css, functions.php, and whatever else back in resources and confirm functionality with a more standard Sage configuration.

The problem described in the thread @alwaysblank linked happens sometimes when a Sage theme is updated, but deactivating and reactivating the theme will fix it if it does happen. You’ll be in charge of when this theme is updated so you can deactivate and reactivate if necessary at that time.

Well I’ve reverted back to how it was originally, and it works fine locally, but when I put it on the server I get the same errors - stylesheet is missing, and then when I make a blank style.css in the root I get this error at the bottom of my themes page:


So I’m back at square one.

So what’s different about your local environment? Are they the same version of WordPress? PHP?

Same PHP, both brand new WP builds (4.8.1). Only difference I suppose is that I’m running yarn watch locally and it’s set up for localhost, whereas my dev environment is running on a VPS.

I just zipped up the whole thing (sans node_modules) and uploaded it to the production. Doesn’t get past the style.css missing thing. If I add a style.css, I get the index.php is missing, then functions.php is missing.

Should note that if I upload the same zip to my local environment, it fails in the exact same way. Yet the theme itself is running fine, so perhaps something about the way composer (I think?) initially deploys it via the sage installation composer create-project roots/sage your-theme-name dev-master worked to register it properly with WP, whereas it doesn’t work the traditional way?

This is the master branch (9.0.0-beta.4) btw, maybe I’ll have more luck using 8?

You’re making progress. You are now able to reproduce the problem locally. That’s actually great news.

Anything that Composer does, it does in the theme directory. As long as you have vendor, you have everything Composer did.

So if you’re zipping the theme and it doesn’t work, something is getting messed up when you zip it.

Does the theme work locally when you load your local environment without yarn start?

What if you just drag and drop the entire directory up via FTP?

:roll_eyes: please leave your entitlement at the door before posting on here.

Shoutout to @MWDelaney for the [free] support

1 Like

It seems to me, although it’s only a hunch, that installing via a zip file has some extra checks for “required” files.

So while this is of course completely possible, if this is a site you have control of, and will not be distributing the theme outside this project… Why are you uploading the theme via zip?

1 Like

Apologies mate, you caught me in a foul mood on a frustrating day. I definitely appreciate the support, I was just hoping that such a seemingly simple task would…work. Perhaps there’s something entirely wonky with my local setup that is causing the errors so starting from scratch might be an idea.

@kalenjohnson as mentioned, I was originally pulling from git, and then tried uploading as a zip as a fallback, also tried FTPing the entire directory over. Nothing is working. Only running the local browsersync server with yarn which is mapped to my MAMP setup is working.

1 Like

Okay so it sounds like even a non-browsersync session doesn’t work? Is that correct?

Does the theme work in browsersync and NOT without it?

1 Like

The theme works without browsersync, it just seems like the way it was installed on the site (which I’m pretty sure happened automatically when I did the compose-sage installation) actually got it activated properly.

So right now I’m NOT running browsersync, or anything, just MAMP. I’m running my theme just fine.

If I simply copy and past the theme directory (locally), it breaks. Only the initial theme that sage set up (and the sage starter theme) are selectable.

So to clarify my process from the beginning,

  1. I was in my themes folder (where I had hte clone of the sage repo set up)
  2. I ran composer create-project roots/sage your-theme-name dev-master
  3. I cd’d into themes/my-new-blog/
  4. I ranyarn && yarn start, and then I did all the development and customisation in that theme

Could it be some issues with ./assets/config.json that I need to change when leading onto the server/ I assumed these were only used by Yarn, and considering a copy-and-paste of the whole directory doesn’t work anyway, I assume it’s not…