Other Packages

UtilitiesReference

Supporting packages that handle common tasks — type safety, icons, validation, dates, theming, and more.

Reference for the utility packages included in Catalyst.
Check here before adding a new package — it might already be included.

Type Safety

TypeScript

5.x
Docs →

Static type checking for JavaScript. Catches errors at compile time and improves editor intelligence.

Configured in tsconfig.json. All Catalyst code is TypeScript.

Zod

3.x
Docs →

Schema validation with TypeScript inference. Define schemas, validate data, and infer types automatically.

import { z } from "zod"

const schema = z.object({
  email: z.string().email(),
  age: z.number().min(18),
})

type User = z.infer<typeof schema>
const result = schema.safeParse(data)

Forms

React Hook Form

7.x
Docs →

Performant form handling with minimal re-renders. Integrates with Zod for validation.

import { useForm } from "react-hook-form"
import { standardSchemaResolver } from "@hookform/resolvers/standard-schema"

const form = useForm({
  resolver: standardSchemaResolver(schema),
  defaultValues: { email: "", age: 0 },
})

<form onSubmit={form.handleSubmit(onSubmit)}>
  <input {...form.register("email")} />
  {form.formState.errors.email?.message}
</form>

Icons

Lucide React

latest
Docs →

Beautiful, consistent icons. Tree-shakeable — only imports the icons you use.

import { HomeIcon, SettingsIcon, UserIcon } from "lucide-react"

<HomeIcon className="h-5 w-5" />
<SettingsIcon className="h-5 w-5 text-muted-foreground" />

Styling Utilities

class-variance-authority (CVA)

0.7.x
Docs →

Type-safe component variants. Define variants once, get autocomplete everywhere.

import { cva } from "class-variance-authority"

const button = cva("rounded font-medium", {
  variants: {
    size: { sm: "px-2 py-1", md: "px-4 py-2" },
    intent: { primary: "bg-primary", secondary: "bg-muted" },
  },
})

<button className={button({ size: "md", intent: "primary" })} />

clsx + tailwind-merge

latest
Docs →

Class name utilities. clsx handles conditionals, tailwind-merge resolves conflicts.

import { cn } from "@/lib/utils"  // Combines both

// Merges classes, resolves conflicts
cn("p-4 bg-red-500", isActive && "bg-blue-500")
// Result: "p-4 bg-blue-500" (not both backgrounds)

Dates

date-fns

4.x
Docs →

Modern date utility library. Tree-shakeable, immutable, and TypeScript-first.

import { format, formatDistance, addDays } from "date-fns"

format(new Date(), "PPP")         // "January 15, 2024"
formatDistance(date, new Date())  // "3 days ago"
addDays(new Date(), 7)            // Date 7 days from now

Theming

next-themes

0.4.x
Docs →

SSR-safe theme switching. Handles dark mode toggle without flash of wrong theme.

import { useTheme } from "next-themes"

const { theme, setTheme } = useTheme()

<button onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
  Toggle theme
</button>

Content & Markdown

gray-matter

4.x
Docs →

Parse frontmatter from Markdown. Used for reading project state and briefs.

import matter from "gray-matter"

const { data, content } = matter(fileContent)
// data = { title: "...", date: "..." }
// content = markdown body

react-markdown

10.x
Docs →

Render Markdown as React components. Supports custom renderers.

import ReactMarkdown from "react-markdown"

<ReactMarkdown>{markdownContent}</ReactMarkdown>

Quick Reference

All utility packages at a glance:

TypeScript

Type checking

Zod

Schema validation

React Hook Form

Form handling

Lucide React

Icons

CVA

Component variants

clsx + tailwind-merge

Class utilities

date-fns

Date formatting

next-themes

Dark mode

gray-matter

Frontmatter parsing

react-markdown

Markdown rendering

For AI Agents

Key rules:

  • Use cn() from @/lib/utils for class merging
  • Use Zod for form validation with React Hook Form
  • Import only needed icons from Lucide
  • Use date-fns for date operations, not native Date methods
  • Check this page before adding new utility packages