Documentation

How Do Include Compiled Assets In My Bundles?

Bundles on Servd track the contents of specific Git Commits to ensure you have a clear papertrail from commit to deployment on the Servd platform. The down side is that only files which are part of your commit will end up inside the subsequent bundle.

We therefore have to rethink how we go about deploying compiled assets, such as CSS and JavaScript, to make sure that they end up in the right places when our project is deployed.

Below are a few different strategies that can be used to accomplish this.

Note: we'll be adding a customisable node build step to project deployments in the future which will make all of this much easier. 💪

Strategy 1: Add the files to the commit

The easiest, if not the most popular, solution to this is to just add your compiled assets to your repo and forego any CI based build steps. This will ensure your files end up exactly where you expect inside your bundles and in the exact form that they take in the Git Commit.

The primary disadvantage of this approach is that you may subsequently experience merge conflicts on these files if you're using multiple Git branches in your repo. However there area couple of easy fixes:

a. Recompile

When git complains about merge conflict on these files, just re-run your buildchain to generate new compiled assets and then resolve the merge conflict. Easy.

b. Ignore the conflict

Alternatively you can create a .gitattributes file in the root of your repo which lists the compiled files with a simpler merge strategy:

/web/assets/css/app.css merge=theirs
/web/assets/js/app.js merge=theirs

With that file added to the repo git will simply accept the remote version of the file when it encounters a merge conflict. You can then re-run your buildchain and create a new commit with the updated files.

Strategy 2: Use the Servd CDN

If you're using the Servd Asset Platform for asset volumes inside Craft, you're already making use of the CDN, but you can use it for arbitrary files outside of Craft volumes.

To do this you'll need to connect to the platform via SFTP. You can then organise your files however you like. We like to create a directory called assets and inside that create a directory for each of our environments: staging, production etc.

We can then either manually upload our compiled assets to the CDN as part of our deployment process, or include relevant SFTP commands in our CI process to do it automatically whenever we release a new version of our project.

If you want to use this strategy we recommend using an environment variable to define the base URL of your CDN assets. That way it can be different in each environment without having to change any code.

Also, be aware that the CDN will cache assets for a while, so you might need to employ some cache busting techniques such as appending a query parameter or including a revision number in the filename of your compiled assets.

Strategy 3: Use a compiled assets Git branch

In this strategy we create a special git branch which is used as the basis for all Servd bundles. This branch is identical to our main repo branch, but has one additional commit to remove any .gitignore references to compiled assets and include a .gitattributes file as per Strategy 1 above.

A deployment using this strategy might proceed as follows:

  1. We make a change to some css on our master branch
  2. We commit those changes - compiled files are excluded due to .gitignore
  3. We merge master into master-assets
  4. We run the buildchain against the master-assets branch to recreate the compiled assets
  5. We commit these to the master-assets branch
  6. We build a new Servd bundle based on this commit

All of these steps can be automated as part of a CI build script of course, so once it's set up, you don't need to think about it again.