Blocks Overview

@tulip-systems/blocks is the shared foundation for modular content surfaces. It gives applications a small set of contracts and client primitives for defining, creating, rendering, editing, and reordering block records while keeping domain behavior in the application.

Use it when a feature stores ordered records like this:

type StoredBlock = {
  id: string;
  slug: string;
  index: number;
  data: unknown;
};

The package is intentionally not a CMS. It does not own your database schema, router, permissions, field UI, or business mutations. It owns the generic block mechanics that every block-based feature otherwise repeats.

What It Provides

• typed block definitions backed by Zod schemas
• a registry that produces create/select schemas and data patch helpers
• typed component maps for stored block renderers
• typed component maps for create options
• RenderBlocks for slug-to-component dispatch
• RenderCreateBlocks for registry-ordered create catalogs
• CreateBlock* dialog primitives for block create forms
• InlineBlock* primitives for collapsible inline editors
• SortableBlocks for drag-and-drop ordering with optional optimistic React Query updates
• order helpers like moveBlock, reindexBlocks, and getNextBlockIndex

Start Here

Package Entrypoints

Server-safe contracts and helpers:

import {
  createBlockRegistry,
  moveBlock,
  reindexBlocks,
  type BlockDefinition,
  type InferBlock,
} from "@tulip-systems/blocks";

Client components and client-safe helpers:

import {
  CreateBlock,
  InlineBlock,
  RenderBlocks,
  RenderCreateBlocks,
  SortableBlocks,
} from "@tulip-systems/blocks/client";

Boundaries

Keep these in @tulip-systems/blocks:

• schema-driven block contracts
• registry and render dispatch mechanics
• generic create/inline/sortable primitives
• deterministic order/data helpers

Keep these in the app:

• concrete block fields and form labels
• database tables and ORPC routers
• permissions, commands, toasts, and invalidation keys
• preview design and domain-specific layout
• media/provider integrations