servd

How Do I 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. By default this means that only files which are part of your commit will end up inside the subsequent bundle.

If your CSS, JS and static images are checked into your repo already then you shouldn't have any problems. Build a bundle and you're all set! If not, there are a few options you can choose from to get everything set up nicely:

Strategy 1: Compile Them During Servd Bundle Builds #

Servd now has the ability to compile your static assets whenever a new bundle is being built. This allows you to keep your static files out of your git repo whilst also ensuring they're compiled via a repeatable, automated process.

There are a few prerequisites to using this functionality.

1. The build process must be 'node' based
2. Your package.json must be in the root of your repository
3. You aren't using any left-field OS level dependencies

We've tried to ensure that all of the commonly used OS packages are available for your build process, but if you encounter errors due to missing packages, please let us know so we can consider adding them.

If your project meets all of the above criteria Servd will offer to build your assets during initial project setup. If not, you can add a build command later via the Project Settings > Build & Deploy page in the Servd dashboard.

We will run npm install for you before executing your build command - no need to add that in yourself.

You can only run a single command as part of your build process, but this command can be anything. You won't have access to any globally installed node modules (gulp, webpack etc) but these can still be executed by using npx to execute them directly from the node_modules/.bin folder.

You can also set up 'npm scripts' and execute those using npm run my-script-name.

Some examples of acceptable commands:

npm run build

npm run bundle --production

npx gulp compile-css

npx webpack build

./build.sh (If ./build.sh is set as executable in the git repo)

Once your build process is complete it should result in your compiled assets being placed in their final location within the repo. This will probably be inside the web or public_html folder.

You can perform other tasks as part of your build process if you wish. For instance you could create a script which downloads some externally hosted assets so that they'll be included in the built bundle, or call out to an external API to gather some information and then hard code that into a php file.

Strategy 2: 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. 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:

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 3: Use an External Continuous Integration Platform
#

Any external CI provider, including but not limited to:

• Gitlab CI
• Github Actions
• Buddy Works
• Deploybot

Can be used to build our assets before triggering a bundle build on Servd.

Under normal circumstances Servd will build a bundle directly from the contents of a commit. If you want to avoid committing these files you can also send an archive of files to use instead.

The steps for your CI platform look a little like this...

1. Clone your repo
2. Perform any relevant build steps such as compiling CSS and JS
3. Make sure all compiled assets are in their final locations inside your repo's directory structure (probably somewhere inside your web folder)
4. Use the Servd Custom Webhook Script to archive and upload your files

Servd Custom Webhook Script?

This script can automate the archive and upload of your a craft base directory and trigger a bundle build based on the contents of this archive.

You can run it using a single command in your CI script which looks like this:

The arguments are as follows:

• [project-slug] - Your project's slug from the Servd dashboard
• [webhook-secret] - Your project's webhook secret from the Servd dashboard
• [commit-sha] - The SHA of the commit you're currently working with. This is usually supplied as an $ENVIRONMENT_VARIABLE by your CI platform
• [path-to-craft-base-dir] - A relative or absolute path to your craft base directory (containing config, web, templates etc)
• [comment] - A comment to attach to the bundle. It's usually a good idea to just use the first line of the Git commit comment
• [branch] - The branch that the commit belongs to. This can be used to trigger webhooks from your project build settings.

A real world example from Gitlab CI which we use to deploy the servd.host website:

GitLab supplies the $CI_* variables and we have defined the others as 'secrets' in the GitLab dashboard. Your CI provider of choice should allow you to do something similar.