Deployment

Note

In this section it’s assumed your compiled assets are under web/assets/.

To build your assets for the production environment:

gulp build --env production

In production, CSS and JavaScript assets are minified and all assets are revisioned so that browsers don’t use a stale version from cache. As an example, if you have an images/foo.png file it will become something like images/foo-123abc.png where 123abc is the hash of the file’s content.

Manifest

So, how does this magic work? How can you do:

<script src="{{ asset('js/foo.js') }}"></script>

And have it output:

<script src="/assets/js/foo-123abc.js"></script>

The answer is: by using a manifest file that maps the original filename to the filename with the hash appended. When you run gulp build --env production you will also get a manifest.json file that looks something like:

{
  "js/foo.js": "js/foo-123abc.js"
}

Using the manifest

Using the manifest file to generate the URLs is disabled by default. You need to enable it for the production environment:

# app/config/config_prod.yml

rj_frontend:
    manifest: true

Changing the manifest path

By default, the manifest is expected to be found under web/assets/manifest.json. If you need to change this, you would add the following to your app/config/config_prod.yml file:

# app/config/config_prod.yml

rj_frontend:
    manifest: "%kernel.root_dir%/../web/foo/manifest.json"

Configuring assets to never expire

Since an asset’s filename will change if its content changes, you can safely tell browsers to cache all assets indefinitely. You can do that by having your webserver set the Expires header to a value in the far future, say one year.

If you’re using nginx, you can do this by adding the following location block to the server configuration:

location /assets/ {
    expires 1y;
}

If using Apache, make sure you have mod_expires active and add the following to your configuration:

<ifmodule mod_expires.c>
    <Directory /path/to/web/assets>
        ExpiresActive on
        ExpiresDefault "access plus 1 year"
    </Directory>
</ifmodule>

Using a CDN

When serving assets from a Content Delivery Network, you want to use an absolute URL, for example:

<script src="//cdn.example.com/js/foo-123abc.js"></script>

You can do this with the following configuration:

# app/config/config_prod.yml

rj_frontend:
    prefix: //cdn.example.com/
    manifest: true

Note

The manifest file must still be present locally in your server

You also want references between assets to use the absolute URL, like when referencing images from your stylesheets. In your gulpfile.js you can set an URL prefix to use in production as follows:

// gulpfile.js

var config = {
  ...
  // Prepend references between assets with a prefix.
  // Will only be used in production builds.
  urlPrefix: '//cdn.example.com',
  ...
};