Read this guide first. Core dna is hosted, so there is nothing to install; your repository holds only templates and front-end assets; and a new kind of page starts in the admin, with a layout. In half a day, from what the platform is to a page you built, deployed and rendered in Smarty or Twig.
L0
Unit 02 · From zero to a deployed change
The build output is committed and served
From zero to a deployed changePage 12 of 28Updated
The platform compiles nothing when you deploy: a site serves its built CSS and JavaScript exactly as committed. So you build before you push, never edit the built files, settle their merge conflicts by building again, and give every asset URL a cache-buster.
Who this is for. Anyone who changes a site's CSS or JavaScript. Not realising the build output is committed and served is the second thing that wastes a first day. After this page you will know what to commit, how to settle a conflict in built files, and how to make sure visitors get the new file.
Served as committed
A deploy makes the files on the server match the branch, and does nothing else: there is no build step on the server. The site then sends the built files from its folder as they are, so dist/app.css in the commit is exactly what /dist/app.css returns. Browsers are told they may keep these files for a year.
Build before you push
A change to the source with no build ships nothing: the site goes on serving the old built file. Commit the source and the build output together, in the same commit, so that every commit on the branch is consistent and any of them can be deployed.
Never edit the built files
The build replaces its output in full. A fix made by hand in a built file works until the next person builds, and then disappears without a trace. Make the change in the source and build.
Conflicts in the build output
Two branches that both rebuilt will conflict in the built files, often in minified lines no one can read. Do not merge those by hand. Settle the conflicts in the source, then build and take the new output:
Shell
# during the merge, after settling the conflicts in the source files
npm run build # the production build, as package.json names it
git add dist/ # the freshly built files replace both conflicting versions
git commit
A cache-buster on every asset URL
Because browsers keep a built file for a year, its URL has to change when the file does. A deploy clears the CDN's copies, but not the copies already in visitors' browsers. Most sites add the deployed commit to the URL: getLastVcsHash() on _currentSite returns the first seven characters of the commit of the environment's latest deployment.
getLastVcsHash() reads the environment's deployment log. On an environment that has never been deployed by a push it is empty, and on one updated by uploading files it does not change when the files do. Add a version of your own to the URL there, and raise it after each upload.
The nonce on the script tag is not part of the cache-buster: it is the site's Content Security Policy, which Conventions every theme follows explains.