Guide 03 · Developer docs

The theme repo and the asset pipeline

Everything a developer changes on a Core dna site lives in its theme repository. This guide covers the repository and its build, printing records in templates, stylesheets and client-side code, and the parts of a site around the main content.

L1–L2
Unit 01 · Anatomy of a theme repo

Source and build output

Anatomy of a theme repo Page 3 of 35 Updated

You write in one folder and the build writes another, and both are committed because the platform builds nothing. How to tell them apart, why a hand edit to the output disappears weeks later, cleaning the output, which build to commit, and checking what .gitignore really ignores.

Who this is for. Anyone who changes a site's CSS or JavaScript. Afterwards you can tell authored files from generated ones in any repository, keep the generated ones trustworthy, and avoid the change that works today and silently disappears at the next build.

Which folder is which

The source is what people write: SCSS, JavaScript or TypeScript, and the fonts and images the build copies, usually under src/. The output is what the build writes and the site serves: dist/ in most webpack repositories, static/ in the gulp ones, build/ in a few. The build configuration says which: output.path in a webpack config, the gulp.dest() paths in a gulp file. When a folder name is ambiguous, trust the configuration over the name.

The platform has no build step. A deploy makes the files on the server match the branch, so the output must be committed, together with the source that produced it, in the same commit. The build output is committed and served has the deploy side, including how to settle a merge conflict in built files.

Never edit the output

The build replaces its output in full. A fix typed into dist/app.css works, passes review because the page looks right, and is deployed. It then survives until the next person builds, for any reason, and disappears with their change, often weeks later and with no trace of why. Make every change in the source and build. The same goes for appending code to a built file, or putting CSS or JavaScript inline in a template to avoid a rebuild.

Clean the output on every build

Without a clean step, the build writes new files beside old ones. A renamed or removed entry leaves its old file in the output folder, where it is committed and served for years. In webpack 5, set output.clean:

JavaScript webpack.common.js (extract) 
output: {
  filename: '[name].js',
  chunkFilename: 'chunks/[name].[contenthash:8].js',
  path: path.resolve(__dirname, '../dist'),
  clean: true
}

Check that a clean step really runs. One production gulp file defines a clean function that no task calls. Another repository's production config builds a single entry when given entry=<name> and turns cleaning off for that run, which is right for a quick rebuild but leaves the rest of the output untouched: run a full build before you commit.

Commit a production build

Commit what the production command produces (npm run prod or npm run build, whichever package.json maps to the production config). A development build is larger, may embed source maps or eval wrappers, and in some configurations names its files differently from the ones the templates link. After building, git status should list only the output files you expected to change.

Check what is ignored

Read .gitignore before you trust either folder:

  • Two production gulp repositories ignore dist/, a leftover from a starter kit. Their output is static/, which is committed. The entry is harmless, but it misleads anyone who assumes dist/ is the output.
  • A repository that ignores its real output folder deploys nothing new: the server keeps serving whatever was there.
  • A new file the build writes is untracked until someone adds it. The template that links it works on your machine and the file is a 404 on the server. Look for untracked files in the output folder in git status after every build that adds an entry.

Source maps

A .map file is served like any other asset, so a committed map publishes your original source. Some repositories commit them on purpose for debugging production; others ignore them with a line such as dist/**/*.map. Decide deliberately, and do not commit maps from a development build.

Go deeper
GuideThe build output is committed and served GuideBuild before you push GuideWebpack and gulp builds FAQMy CSS or JS change is not appearing

Was this page helpful?

Your answer goes to the docs team.