Upgrading

An upgrade has two halves: the npm packages, which you update as any dependency, and the registry files, which are yours and change only when you copy them again.

The npm packagesCopy Anchor Link

The four packages (@hapio/calendar-core, -react, -recurrence, -compat) are released together under one version. Update every one you use to the same version.

From 1.0 on, the public API follows semantic versioning: minor versions only add, and the getters only gain attributes within a major version, so markup that spreads them keeps working. Before 1.0, everything is marked experimental and may still change.

The registry filesCopy Anchor Link

Each copied file starts with a stamp: the version it came from and the contract it implements.

// @hapio/calendar registry 1.0.0 · contract 1

The hooks implement every contract of their major version and warn in development when the copied files need newer hooks, or are older than they expect, so a package update never breaks copied files silently.

In an app with "rsc": false in components.json (Vite, and other apps without Server Components), about half of the copied files have no stamp: the shadcn CLI removes 'use client' there, and the comment lines below it with it. Read the version in hapio-calendar/hapio-calendar.tsx instead (const REGISTRY = { version: '1.0.0', contract: 1 }), which is what the hooks check. Which files lose them depends on the other files of the same shadcn add, so adding an item again can list files you never edited as changed ("overwrite" in a dry run); their differences are only those first lines. Set "rsc": true to keep the files whole (see Installation).

To take a new version's files:

1. See what would change: npx shadcn@latest add @hapio/hapio-calendar --dry-run lists the files the block and its items would write, and --diff components/hapio-calendar/calendar-event.tsx shows one file's differences from your copy.
2. Files you never edited: add the items again with --overwrite.
3. Files you edited: apply the new version's changes to your copy, or copy the new file and apply your edits again. Your edits are yours; the CLI never merges them.

A view kind newer than your copied calendar-view.tsx renders UnsupportedView (a short notice, strings.unsupportedView) until you update the file or pass a renderer for it in renderers; nothing breaks in between.

Each minor release also freezes its registry files at their own address under the registry's, /r/v1.0/{style}/{name}.json for 1.0, which never changes: point the @hapio namespace there to stay on a minor's files while you update the packages within it.

The theme itemCopy Anchor Link

calendar-theme adds CSS variables and rules to your global CSS. Adding it again adds what a new version brings and replaces what it changed, but it does not remove what an older version had and the new one dropped: inside your global CSS, shadcn only adds and replaces declarations. After an upgrade, compare the calendar's part of your global CSS with the new item (its cssVars and css, in the item's JSON at the registry's address) and delete what it no longer has. The item sets its color tokens for both schemes (cssVars.light and cssVars.dark); keep both when you compare.