Guide 12 · Developer docs

Performance, caching, deployment and go-live

How Core dna caches pages, what makes a render fast, how code reaches a site and what stays behind, the go-live checklist, and running a site once it is live. For developers, leads and site operators who already build pages in a theme repository.

L2–L3
Unit 03 · The deployment model

Build before you push

The deployment model Page 16 of 34 Updated

The platform serves what is committed and builds nothing, so the most common deploy failure is a source change pushed without its build. The symptom, how to tell it from a cached file, the rule, and a pre-push check that catches it automatically.

Who this is for. Every developer who pushes to a Core dna theme repository. Afterwards you can recognise an unbuilt deploy in minutes rather than hours, and stop it happening again.

A theme's CSS and JavaScript are compiled from source by the theme's own build, and the compiled files are committed to the repository. The platform deploys exactly what is committed, with no build step of its own: a deploy resets the site folder to the branch as it is, so the site serves whatever compiled files were in the last commit (What is in a theme repository). Commit the build together with every source change, or the site serves files that no longer match it.

The symptom

Nothing fails. The Deployments list says success, the templates are new, and the site looks as it did yesterday, or half of it does:

  • A template uses a class that the committed stylesheet does not have yet, so a new component renders unstyled.
  • A template loads a new script entry that was never built, so the browser console shows a 404 for it, and nothing else does.
  • A fix to a script is in the source and not in the bundle, so the live site still behaves as it did beforehand.

Because there is no error anywhere, the first hour usually goes on caches. The page cache is not the problem: a deploy clears it. Two checks tell the causes apart in a minute:

  1. Is the change in the committed build? Search the committed file for a string from your change (git grep on the deployed commit). If it is not there, the build was not committed.
  2. Is the browser holding an old copy? Theme files are sent with a one-year lifetime, so a browser keeps an old stylesheet until its URL changes. If the asset URL carries the commit hash as a version, a deploy changes it; if it does not, the browser is the stale copy (theme files).

The rule

  • Every commit that changes source includes the build of that source, made with the production build command, not the development one.
  • Never edit the compiled files by hand, and never append to them. The next build overwrites the edit, and the source never had it.
  • One person's build should match another's. Pin the Node version and commit the lock file, so two developers building the same commit produce the same files.

A pre-push check

Catch the mistake before it leaves your machine: a git hook that runs before every push, builds, and refuses the push if the build changes the committed output.

Shell .git/hooks/pre-push 
#!/bin/sh
# Refuses a push whose committed build is out of date. Make it executable.
npm run build --silent || { echo "Build failed; not pushing." >&2; exit 1; }
if ! git diff --quiet -- dist/; then
  echo "The build in dist/ does not match the source. Commit it, then push again:" >&2
  git diff --stat -- dist/ >&2
  exit 1
fi

Replace dist/ with the folder your build writes to. Two things keep it reliable:

  • The build must be deterministic. If it writes a timestamp or an absolute path into its output, every build differs and the check always fails. File names hashed from content, and source maps with relative paths, avoid both.
  • Hooks are not shared through git. Install it with a script in the repository (an npm run prepare step, or a tool such as Husky) so that every clone has it, and repeat the check in CI for anyone who skips it (What CI can do for a theme repo).

When it has already happened

  1. Check out the deployed commit, run the production build, and look at git status: the changed files are what the site is missing.
  2. Commit the build on its own ("issue/sts-322 - Build") and push. The deploy clears the caches, so the next request gets the new files.
  3. Confirm the release hash on the live page (seeing which commit is live) and that the asset URLs carry it.
Go deeper
GuideWebpack and gulp builds GuideWhat CI can do for a theme repo FAQMy CSS or JS change is not appearing How-toCache-bust an asset URL

Was this page helpful?

Your answer goes to the docs team.