What does the WP_ENV variable do?

Hello,
I’m a Sage noob And so far I’m a big fan. Already my development process is faster and cleaner thanks to the gulp/browsersync workflow!

One point I’m unclear on is the purpose of the WP_ENV variable that the docs indicate should be set here:
https://roots.io/sage/docs/theme-installation/

If you don’t use Bedrock as your WordPress stack, you’ll want to add the following to your wp-config.php on your development installation:

define('WP_ENV', 'development');

But the docs don’t say why we need to set this.

The docs don’t indicate why this variable is needed, or whether this should be changed for staging and production environments. I’ve found documentation from earlier versions of Roots that indicate “Staging” and “Production” settings for this variable, but these aren’t referenced in the Sage documentation.

So what does this variable do? Why should it be set during development, and what should it be set to after deployment to staging, and production respectively? Should the Sage docs be updated to describe this more thoroughly?

Thanks for your time!

1 Like

WP_ENV is only used for one thing. See here https://github.com/roots/sage/blob/403ec062c9b505fc8e5eb6934a5093d1812f0ee2/lib/assets.php#L66-L71

In Gulp production mode, it “versions” the assets and creates a manifest of the versions in dist/assets.json. This versioning is just done by generating an MD5 hash of the asset files content for caching purposes.

When WP_ENV is not “development”, we lookup the filename in assets.json and load the “revved” version.

Example:

Take the general main.js file. Here’s what it would look like with different WP_ENV:

  • development: http://example.dev/app/themes/sage/assets/main.js
  • production: http://example.dev/app/themes/sage/assets/main-bd3644a2.js

This means that your assets can have a really long expires headers so browsers always cache them. But when you change your assets and deploy, they’ll get a new version string meaning that they’ll be downloaded again.

You’re correct that we need to document this better.

2 Likes

I was initially confused about the setup difference between development/staging environments, I know you guys have a lot to document, especially with the new release, but some of us are new to this type of workflow and a bit more info on the steps could help.

I think I might not be alone in needing a little more help understanding how I should set up the different environments. For example, am I supposed to define the production URL in the manifest.json file as well? Also if I am only developing with Sage without Bedrock, is there a different way to compile everything for deployment?

I’ve been messing with the different prod/dev settings for days now trying to get my build to work and now I am realizing that most of the time it doesn’t even compile the assets.json file, is there a setting that could be causing this?

I really love the theme/framework, I can’t wait to get this all sorted out, even with the set backs I have had learning it, it is worth it!

devUrl in manifest.json only applies to the development URL. It is mostly used so Browsersync will proxy the correct URL to localhost

assets.json is only generated when you run gulp --production, since the compiled assets are then revisioned in the file name. This still happened in older versions of Roots, but the file name were written directly to the PHP file, which wasn’t ideal.