Anatomy of a theme repo

01 What is in a theme repository A theme repository holds templates, front-end source, the committed build output and a few files served as they are. What each folder is for, where the parts you expect from an application framework live instead, and which committed files anyone can download.

02 Repository shapes you will inherit Theme repositories differ in size, engine and build, and you will usually inherit one rather than start one. Four real shapes side by side, what stays the same in all of them, and a route through a repository you have never seen.

03 Source and build output 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.

04 Webpack and gulp builds Theme repositories build with webpack, or with gulp running webpack inside it. How to tell which one you have from its files, the commands each uses, why a watch task cannot be trusted until you have run it, and how to read package.json before anything else.

05 Bundle boundaries Sites split their JavaScript into a bundle per page type, so a content page never downloads the checkout. A real bundle table with the template that loads each bundle and its measured size, and the rule for when a new bundle is worth its cost.

06 Queueing a script from a template A component that needs a bundle should add it to a queue, and the base template should print every queued script once, at the end of the page, with the nonce and the cache-buster. The queue in both engines, the block alternative and where it stops working, and queueing code that waits for a bundle.

07 The CSP nonce Every page is sent with a Content Security Policy built from a site setting, and every script tag, inline or external, carries the request's nonce. The policy and its default, the syntax in both engines, what a refused script looks like, and what a nonce cannot fix.

08 Cache-busting asset URLs Built files are sent with a one-year cache lifetime, so a changed file needs a changed URL. The deploy-hash query parameter in both engines, why it is empty on some environments and what to do then, assets that scripts load themselves, and what returning visitors see without it.

09 Translation files in the theme repo A site can carry XLIFF files in translations/ that replace the platform's own wording or hold its own interface strings. When a site needs them, how the files are named, which file wins for a key, and the one difference between the engines.

10 What must never be committed Provider keys, mail-service credentials, deploy credentials, environment files and local IDE settings do not belong in a theme repository. The categories with the shapes they take in real repositories, where each belongs instead, and what to do when one is already in the history: rotate it.

Objects ReferenceGenerated from the platform, so it is always current

API ReferenceEvery REST endpoint, in cURL, PHP, Python and JavaScript

In this unit