Upgrade: v2.5 to v2.7
This guide takes a project from Velocity 2.5.1 or any 2.6.x release to Velocity 2.7.0. Nothing in your pages has to change. There’s one small API change and a few visible ones, all listed below. Coming from 2.4 or earlier? Follow v2.4 to v2.5.1 first; the upgrade itself goes straight to 2.7.0.
What’s new
Section titled “What’s new”| 2.6 | 2.7 | |
|---|---|---|
| Dialog | <div role="dialog">, a script focus trap, overflow: hidden on <body> | Native <dialog> with showModal(), data-dialog-open |
| Dropdown | Absolutely positioned, clipped by overflow parents | Native popover in the top layer, anchored to its button |
| Form errors | Only when the server rejects a submission | After a visitor leaves an invalid field, in the site’s language |
| Dark mode | Native controls and scrollbars stay light | color-scheme follows the theme |
| Prerendering | Opt-in with speculation: 'prerender' | |
| Destructive colour | Never applied | Applied, and passes WCAG AA |
See the changelog for everything, and Helpers for the new attributes and utilities.
Run the upgrade
Section titled “Run the upgrade”npm create velocity-astro@latest upgradeAfter the upgrade
Section titled “After the upgrade”dialogElement.open(): if your own code called it, change it towindow.openDialog(id)orshowModal(). On a<dialog>,openis a built-in boolean property, not a method.close()still works, andwindow.openDialog/window.closeDialogare unchanged.- Destructive styling now renders.
bg-destructive,text-destructiveandborder-destructivedid nothing before 2.7 because the token was never mapped. Destructive buttons and error text now show in red: a deeper red in light mode, and light red with dark text in dark mode. - Custom themes. If you wrote your own theme file instead of using
defaultormidnight, check that--destructivehas at least 4.5:1 contrast with--destructive-foregroundand with your background. See Destructive. - Forms show errors after interaction. Fields with
required,type="email",minlengthormaxlengthnow show a message under them once a visitor leaves them invalid. If your project overrides UI strings for another language, translate the newform.validation.*keys insrc/i18n/translations/<locale>.ts. See Errors after interaction. - Dropdown and Carousel markup. Dropdown’s menu is now a
popover, and Carousel wraps slides that are links, buttons or images. If you have CSS that targets either component’s internals, check it still applies.
Prerendering is opt-in
Section titled “Prerendering is opt-in”2.7 can make Chromium browsers render a page in the background when a visitor hovers a link to it, so the page opens instantly. It’s off unless you add this to src/config/site.config.ts:
const siteConfig: SiteConfig = { // ... speculation: 'prerender',};Add speculation?: 'off' | 'prerender'; to the SiteConfig interface in the same file. Upgrades don’t change site.config.ts, so your copy won’t have it yet.
Verify
Section titled “Verify”npm installnpm run validatenpm run build && npm run test:e2e