Skip to content
HomePagesHomePages template kit
Menu
Start here
What you're buildingInstallFirst renderRead the starterAdd a slotShip it
Concepts
The pipelineSections and declarationsSlotsFacts and provenanceAI fillFixtures and scenariosValues and emptinessThe marker contractServer and clientTheme modelFrames and formatsComposition and reconcileVersioningStaying current
Guides
API reference
Rules

Cross a kit major

Move a workspace onto a new major kit version — the changelog, the install, the migration list, and the re-pack.

Goal

Section titled “Goal”

Move a workspace from the kit major it is on to the next one, and know when you are done. Versioning is why a major means what it means and how long you have to take one; this page is the procedure.

Prerequisites

Section titled “Prerequisites”
  • A workspace whose check is green before you start — Run check. Start red and you cannot tell which findings the new major caused.
  • A commit, or a clean working tree. Two files change before you edit a line of template code, and step 4 is a list of edits you will want to be able to compare against.

Steps

Section titled “Steps”

1. Read the changelog first. It ships inside the package you already have, at node_modules/@homepages/template-kit/CHANGELOG.md. A major’s entry is the only place that says why something changed and what it changed to; check will tell you what is now rejected but never what to write instead. Reading it first turns step 4 from a puzzle into a list you recognize.

2. Ask for the major. template-kit upgrade is the whole move: it rewrites every @homepages/* range in your package.json to the new line and installs once. Nothing carries you here on its own — inside a major the CLI keeps your packages current for you, but a major only ever gets a question, whose default is yes. Answering yes, or pressing enter, runs this same command; only a whole-word no leaves it undone.

The kit, the CLI and the lint preset are separate packages released at one number, and each declares the kit as a peer covering a whole major — so moving one of them by name is precisely how you get an unmet peer instead of an upgrade, and moving them together is what upgrade is for. Commit package.json and package-lock.json in the same breath: a lockfile left behind is lockfile-stale on the next run.

3. Confirm the pair you are running. template-kit --version prints it as <cli> (kit <kit>). Read it before you read anything into a check result — and note that the upgrade you just ran finishes on the CLI it started as, so the pair only settles on the next command.

4. Run check. That is your migration list. It reports what the new version rejects, one finding at a time, each with a rule id and a file. Most of a major’s findings arrive as typecheck, because the contract you author against is a set of types and a removed or narrowed one stops compiling. Work them by id — Fix a failing check is one finding end to end. There is no --fix and no codemod behind it: what check gives you is a finite, ordered list and a green run to aim at.

5. Re-pack. A pack records the kit version its source was validated against, so a zip built before the upgrade still claims the old one however green the workspace is now. Pack again once step 4 is clean — see Prepare a submission.

Commands

Section titled “Commands”
Terminal window
npm ls @homepages/template-kit               # the version you are on
npm view @homepages/template-kit version     # the current release


cat node_modules/@homepages/template-kit/CHANGELOG.md


template-kit upgrade --dry-run               # the rewrite, without doing it
template-kit upgrade                         # every @homepages/* range, moved together


template-kit --version                       # prints <cli> (kit <kit>)
npm run check                                # the migration list
template-kit pack starter                    # re-pack once it is green

template-kit upgrade --to <version> moves to one exact version instead of the published latest — the way back off a release that turned out to be a bad one. Its flags and exit codes are in its reference page.

Verify

Section titled “Verify”

template-kit --version names the kit line you asked for, and the author loop closes green. The zip is the last confirmation: its pack-manifest.json carries the kit version the source was validated against, and after a re-pack that is the new one.

Rules that can fire

Section titled “Rules that can fire”
  • lockfile-stale — package.json’s kit range moved and the lockfile did not, which is what a hand-edited range leaves behind.
  • typecheck — a template does not compile against the new major. This is the id most of the migration list arrives under.

See also

Section titled “See also”
  • Versioning — what each kind of release is allowed to change, and which kit major a submission has to be built against.
  • Staying current — what the CLI updates on its own inside a major, the question it asks across one, and how to switch both off.
  • Run check — the run that becomes the migration list.
  • Prepare a submission — the re-pack, and what the zip carries.