Documentation
Updating Rubrica
Translated from the Portuguese original. Labels from the CLI and the admin panel stay in Portuguese, as you will see them.
In v2, updating is bumping a package version. Your project has no copy of the template, so there are no files to merge and no conflicts: the site comes from @rubrica/core and the theme, and what is yours (configuration, own blocks, ejected components) stays as it is.
What is yours and what is the package's
| Whose | What update does |
|
|---|---|---|
@rubrica/core and @rubrica/theme-<name> |
The package's | Bumps the version |
convex/rubrica/*.ts, convex/auth.ts, convex/http.ts, convex/crons.ts |
Generated (one line each) | Regenerates |
astro.config.ts |
Yours, with CLI sections between rubrica: markers |
Doesn't touch |
src/blocks/ |
Yours | Doesn't touch |
src/overrides/ |
Yours (ejected components) | Doesn't touch, but warns if the original changed |
Tables and functions in your convex/ |
Yours | Doesn't touch |
AGENTS.md, README.md |
Yours | Doesn't touch |
Step by step
Clean starting point.
git statuswith no changes. That is what lets you go back.See the plan, writing nothing:
npx create-rubrica@latest update --dry-runIt shows the core and theme versions, the
convex/files that change, the data migrations the version asks for and the ejected components whose original changed. Also read the release notes.Apply:
npx create-rubrica@latest update --yesIt bumps the packages, installs, regenerates
convex/and runs the data migrations on the development Convex (it says which one first).Ejected ones. For each component
updatelisted, compare the copy insrc/overrides/with the new original (the path is in the list) and bring over what the new version fixes, keeping your customization.Backend and production. The data migrations run on development. On production, run the same ones after publishing the backend, with the OK of whoever looks after the site:
npx convex run --prod <function>.Check:
pnpm check,pnpm testandpnpm build.Commit:
chore: update Rubrica to vX.Y.Z.Live site. Production only changes when you publish (
npx create-rubrica publicar, or the merge into the branch tied to Vercel). Pass along what the notes ask: migrations and new variables.
Migrating cases (2.3.0)
2.3.0 moves case bodies to blocks. update lists the projects-sections-to-blocks migration, which converts each project's long text (content) and sections (sections) into texto blocks and deletes the old fields. It is idempotent: running it again repeats nothing, and projects that already have blocks stay as they are. Before you run it, the site already works: cases in the old format are still read and show up normally.
update --yes runs the migration on the development Convex, after publishing the backend there. On production, with the OK of whoever looks after the site, publish the backend and run the migration, in this order:
npx convex deploy
npx convex run --prod rubrica/collections:migrateSectionsToBlocks
convex deploy always publishes to production, and the new function only exists there after it. The answer is { migrated: <how many projects> }. Then publish the site (npx create-rubrica publicar).
If your theme is a third-party one or was ejected, also check the case template: it must show blocks instead of sections. See The case template.
Versions
The core and each theme have independent versions, and the theme declares the block contract it uses (contract: ^1). In practice:
- A new block is a minor version: every theme gets its default version.
- Changing or removing a field is a major version and always comes with a data migration.
- SEO, accessibility and language fixes ship in the core and apply to every theme.
To pin a version, use --para <version>.
Several installations (agencies)
Each client has their own installation (repository, Convex and Vercel), and update handles one project at a time. To open the update on all of them without doing it by hand, use a dependency bot on each client's repository:
Renovate (renovate.json at the root):
{
"$schema": "https://docs.renovatebot.com/renovate-schema.json",
"extends": ["config:recommended"],
"packageRules": [
{
"matchPackageNames": ["/^@rubrica//", "create-rubrica"],
"groupName": "rubrica",
"commitMessagePrefix": "chore:"
}
]
}
Dependabot (.github/dependabot.yml):
version: 2
updates:
- package-ecosystem: npm
directory: /
schedule: { interval: weekly }
groups:
rubrica:
patterns: ["@rubrica/*", "create-rubrica"]
The bot opens the PR with the new packages. On each PR, run npx create-rubrica update --dry-run to see what else the version asks for (the generated convex/ and migrations) and npx create-rubrica update --yes to complete it, before merging. pnpm test (which runs verificar) fails if convex/ fell behind, so CI catches the slip.
Going back
Since everything is in git, going back is undoing the commit (or the PR). If a data migration already ran, read in the version notes how to undo it before reverting the code.