Moltenship Time

Installation

Requirements, packages, and Temporal setup.

Requirements

  • React 19. React is a peer dependency.
  • A JavaScript runtime with Temporal. Node.js 26 and later include it. Browser support is still rolling out, so check the MDN compatibility table for the browsers you support and add a polyfill if needed (see below).
  • TypeScript 6 or later with "lib": ["ESNext"], which includes the Temporal types.

Install

Not on npm yet

The packages haven't been published. The commands below are what you'll run after the first release. To try Time now, run it from source.

pnpm add @moltenship/calendar react react-dom

@moltenship/calendar is the only package you import. It includes the React components, the event engine, the Temporal helpers, and the pointer interactions. See How it works for what's inside.

Temporal

Time uses the global Temporal object and never bundles a polyfill. In a runtime without Temporal, load one before any code that imports the calendar. This entry file loads temporal-polyfill only where it's missing, then loads the app:

main.tsx
if (!("Temporal" in globalThis)) await import("temporal-polyfill/global");

// Import the app afterwards, so no module runs before Temporal exists.
const { App } = await import("./app");

Any polyfill that defines globalThis.Temporal works.

TypeScript

Make sure your tsconfig.json includes the ESNext library so Temporal is typed:

tsconfig.json
{
  "compilerOptions": {
    "lib": ["DOM", "DOM.Iterable", "ESNext"]
  }
}

UI source (optional)

The packages render plain, unstyled elements. Styled parts built on them live in the repository's registry folder, as source you copy into your app and then own, the same way shadcn/ui works:

  • registry/calendar-theme: calendar-theme.css (calendar tokens and event colors) and event-colors.ts (the color names). See Theming.
  • registry/calendar: CalendarToolbar, ViewSwitcher, EventChip, and MiniMonth.
  • registry/time-grid-view, registry/month-view, and registry/list-view: the week and day, month, and agenda views.

There's no shadcn add command for these files yet, so copy them by hand:

Set up shadcn/ui with Tailwind CSS 4 if your app doesn't use it yet. The files need shadcn's default primitives, built on Base UI, which init sets up:

npx shadcn@latest init

If your app already uses shadcn/ui, check that style in components.json starts with base-, such as base-nova. shadcn add installs components in your app's existing style, and the copied files don't compile against primitives from other styles.

Then add the primitives the files import:

npx shadcn@latest add button popover select tooltip

The files also import cn and lucide-react. shadcn init installs both with its default preset; if your app doesn't have them, add them with pnpm add cn lucide-react.

The toolbar's buttons use shadcn's tooltip, so wrap your app in TooltipProvider from @/components/ui/tooltip once, as shadcn's tooltip instructions describe.

Copy the files into your app. Each folder's registry-item.json lists a suggested target path, such as components/calendar/calendar-toolbar.tsx and styles/calendar-theme.css.

The copied files import each other through @registry/…. Change those imports to your own paths. In a default shadcn setup they map like this:

Import in the copied fileChange it to
@registry/ui/button (and other ui/)@/components/ui/button
@registry/calendar/…@/components/calendar/…
@registry/calendar-theme/event-colors@/components/calendar/event-colors

Import the theme in your global CSS, after the Tailwind and shadcn imports that shadcn init added. The path is relative to the CSS file:

index.css
@import "tailwindcss";
@import "tw-animate-css";
@import "shadcn/tailwind.css";
@import "./styles/calendar-theme.css";

A shadcn app already defines the dark variant. If yours doesn't, add @custom-variant dark (&:is(.dark *)); below the imports.

Run from source

Until the first release, you can run Time and this documentation site from the repository. You need Node.js 26 and the Vite+ CLI (vp).

git clone https://github.com/Moltenship/time.git
cd time
vp install
vp run dev

vp run dev starts this site locally. The examples on these pages are real files in apps/showcase/content/examples, type-checked against the current packages.

Next, build a calendar in the Quick start.

Edit on GitHub

Last updated on

Introduction

A React 19 calendar built on the Temporal API, with views you copy and own.

Quick start

Build a week, day, month, and agenda calendar with the built-in views.

On this page

RequirementsInstallTemporalTypeScriptUI source (optional)Run from source