v2: Rubrica stops being a template copied into your project and becomes a core in a package, with themes and two site lines (personal and company). Updating becomes bumping a package version.
Coming from 1.x: it is not an update, it is a migration. Run npx create-rubrica@latest migrar in a project on 1.13.1, with a clean git state: it creates the rubrica-v2 branch, swaps the code, converts the data and lists what you customized. Nothing is written to Convex: the import goes into a new development database, and production only with your "ok". Guide: Migrating from v1. v1 keeps receiving bug and security fixes for 6 months on the v1 branch, which also holds its documentation.
Security
Three v1 flaws are fixed in v2. v1 does not get a fix for them: if you have a v1 site with proposals, the fix is to migrate to v2.
- A password-protected proposal no longer leaks its content through the API. In v1, whoever called the proposal's public query received the content without typing the password: only the page hid it. Now, without a valid session, the API returns only the state ("locked"), without the content.
- The wrong-password limit now really blocks. A wrong attempt threw an error, which undid the attempt count, so the limit was never reached. Now the attempt is recorded and, past the limit, the proposal answers
TOO_MANY_ATTEMPTS.
- A single default contract template. v1 had two default templates (one in code and one in the database), and a proposal could use one different from what the panel showed. In v2 there is just one, the database one (marked as default); the text shipped in code only serves to create it when none exists yet.
What changed in the architecture
- Core in a package.
@rubrica/core brings the site (Astro), the panel (React), the backend (Convex) and the MCP. Your project keeps only configuration, own blocks and ejected components. The project's convex/ becomes one-line files that re-export the core's backend.
- Static site in Astro. No more makeshift prerendering and SPA: pages come out as HTML, with almost no JavaScript (only the interactive parts become islands). Images and fonts go through Astro's own handling, fonts are served by the site itself, and the body and heading fonts are preloaded.
- Pages made of blocks. Each page is a list of typed blocks, with a live preview in the panel. The catalog has 21 blocks (15 common, 1 personal and 5 company), and the catalog is generated from the code in Blocks. Four are new: video (YouTube or Vimeo; a light thumbnail, with the player loading only after the click), embed (a calendar, form, map or player, only from allowed providers; the generated CSP already includes them), timeline and plan comparison. You can create new pages in the panel. The block contract is at 1.2: a block definition can carry
validate (rules across fields), sample (an example for the showcase), enhances (an island that improves the block) and guidance (usage guidance).
- Two site lines.
pessoal (personal, the portfolio as always) and empresa (company: about us, services, pricing, team, cases, contact). The company line adds the plans collection, the team and the company data (which build the Organization/LocalBusiness structured data). The scope is explicit: the company line is for those who sell a service and get quote requests, and it is not a store (no product catalog, cart or stock). The company page recipes use the timeline and the plan comparison. See Company site.
- 14 themes, 15 color schemes. The 13 v1 layouts become themes (same names), plus
padrao. Each theme is a @rubrica/theme-<name> package. Any scheme works in any theme, and each theme or site can have an optional texture over the page (grain, paper or scanlines). All pass the same test battery (testar-tema: axe, single h1, complete <head>, JavaScript limit, Lighthouse).
- Several languages. The language list is configurable and the main one is your choice (no URL prefix). Content without a translation simply doesn't exist in that language: no empty pages or internal 404s.
- Agency and client roles.
root is the agency, admin the site owner, and there is a new comercial role (proposals, contracts, checkouts, contacts and plans).
- Users. The
root resets someone's password in the panel, with no email: a temporary password comes out, shown only once, the person's sessions are dropped and changing it is mandatory on the next sign-in. Users can also be suspended and reactivated (the role is kept). The backend enforces the change of the temporary password: until it is changed, neither the panel, nor the MCP, nor the API work for that account.
- Proposals, acceptance and payment. Turned-on plugins generate public pages: the proposal (with a password, the contract, acceptance with an optional signature, and PDF), the acceptance, the checkout (PIX, bank slip or card, through Asaas) and the payment completed page. Each route becomes a static page per language, and the project generates the rewrites for Vercel, Netlify and Cloudflare Pages.
- WhatsApp and announcement bar. In the site settings, an optional floating WhatsApp button and an announcement bar with start and end dates (evaluated at build). The
whatsapp: address works in any button or link, and the number goes into the JSON-LD as contactPoint. migrar brings the number v1 had. See Content and panel.
- Contacts and privacy. Requests go to the panel and, if you turn them on, to Telegram, email (Resend) and a signed (HMAC) webhook, with automatic retry. Forms record consent, the privacy policy is generated, and a person's data can be exported or deleted.
- Agents. The local MCP server (
rubrica mcp) replaces the rubrica skill's Python script: the agent edits pages, blocks and collections with a panel user's login, with a preview before writing. The writing skills (rubrica-voz, rubrica-case, rubrica-blog, rubrica-curriculo, rubrica-apresentacao, rubrica-pilar) use the MCP to write. The MCP has proposal tools, uses the project's real catalog (own blocks included, read through the backend), validates the installed theme's variants, serves the theme's recipes (page_recipes) and the usage guidance of each block.
- Development.
pnpm dev reflects what you save in the panel without restarting. Forms work outside Vercel and on your computer: the API address comes from Convex (PUBLIC_RUBRICA_API is optional). The panel's live preview works on the published site.
- Documentation. The block catalog is generated from the code, and there are guides to create a block and create a theme, plus plugins (in 2.0 there is no public API for third-party plugins), environment variables and the company site.
- Neutral hosting. Vercel stays the official host (
publicar automates only it), but the project generates vercel.json, public/_redirects and public/_headers from the same configuration, and the Publish button accepts any host's deploy hook.
- New CLI. Commands
create, setup, config, publicar, senha, update, ejetar, verificar, testar-tema, mcp, migrar and telemetria. See CLI commands.
Breaking changes from v1
- The project is no longer a copy of the template. There is no app
src/, templates/, cli/ or scripts/ in the project. update stops merging files (and generating .rubrica-new): it bumps packages and regenerates convex/.
- Code customizations do not migrate on their own.
migrar lists them, and each becomes configuration (panel tokens), an own block (src/blocks/) or an ejected component (ejetar).
- The app is no longer a Vite SPA. Pages and routes belong to Astro; the panel lives at
/admin (before, /login and /admin/* in the SPA).
- The
playground plugin is gone. The i18n plugin ("AI translation") became translation: languages belong to the core, and the plugin only fills in translations.
- Section texts became block fields (titles, subtitles and buttons); only interface texts stay in "Texts".
- The
ptBR/enUS translations become a per-language map. In migrar, the main language is pt-BR and the /en URLs stay the same.
- Requirements: Node 22.23.4 or newer (before, 20).
- The
rubrica skill's Python script is gone: use the MCP.
- Environment variables. The new names are in
docs/v2/variaveis.md (in Portuguese); v1's (TELEGRAM_ADMIN_CHAT_ID, VERCEL_DEPLOY_HOOK_URL, VITE_UMAMI_*) are still accepted.
Known pending items
They are in docs/v2/pendencias.md (in Portuguese). The main ones:
- Panel: images in text bodies, a live preview of posts and cases, translating a whole item at once and opening the AI résumé PDF.
- For 2.0.x:
update still does not regenerate vercel.json and public/_headers (header and rewrite fixes, and the embed providers, only reach new projects); the rewrites were not tested on real hosting; and there is no cookie notice before an embed loads.