Reference

Server Entrypoint

import { ... } from "@tulip-systems/blocks";

Exports:

• createBlockRegistry
• resolveBlockSchema
• resolveBlocksSchema
• resolveBlockCreateSchema
• resolveBlockDefinition
• sortBlocks
• reindexBlocks
• getNextBlockIndex
• appendBlock
• removeBlock
• moveBlock
• isBlockDataRecord
• patchBlockData

Types:

• BlockDefinition
• AnyBlockDefinition
• BlocksDefinition
• BlocksRegistry
• BlockRegistry
• StoredBlock
• InferBlockFromDefinition
• InferBlockInputFromDefinition
• InferBlock
• InferBlockInput
• BlockComponentProps
• BlockCreateComponentProps
• InferBlockComponents
• InferBlockCreateComponents
• PatchBlockDataInput
• PatchBlockDataResult
• IndexedBlock
• BlockMoveResult
• BlockRemoveResult

Client Entrypoint

import { ... } from "@tulip-systems/blocks/client";

Client exports include all server-safe contracts/helpers plus:

• RenderBlocks
• RenderCreateBlocks
• CreateBlock
• CreateBlockTrigger
• CreateBlockTriggerIcon
• CreateBlockTriggerContent
• CreateBlockTriggerTitle
• CreateBlockTriggerDescription
• CreateBlockContent
• CreateBlockHeader
• CreateBlockTitle
• CreateBlockDescription
• CreateBlockFields
• CreateBlockFooter
• CreateBlockCancel
• CreateBlockSubmit
• SortableBlocks
• useSortableBlock
• InlineBlockSortable
• useInlineBlockSortable
• InlineBlock
• InlineBlockHeader
• InlineBlockDragHandle
• InlineBlockTrigger
• InlineBlockContent

Stored Block Shape

type StoredBlock<TSlug extends string = string, TData = unknown> = {
  id: string;
  slug: TSlug;
  index: number;
  data: TData;
};

Definition Shape

type BlockDefinition<TSlug extends string = string, TSchema extends z.ZodType = z.ZodType> = {
  slug: TSlug;
  label: string;
  description?: string;
  schema: TSchema;
};

Common Gotchas

• Use as const satisfies BlockDefinition; otherwise slugs may widen to string.
• RenderBlocks renders stored blocks. It does not render create options.
• RenderCreateBlocks renders registry definitions. It does not need stored block data.
• Keep create and inline mutations in the app so query keys, toasts, and permissions stay domain-specific.
• patchData validates the full merged data object, not just the patch.
• If old database rows fail selectSchema, add a migration or schema compatibility layer in the app.
• SortableBlocks defaults to vertical sorting constrained to the parent element. Override modifiers or strategy only when the UI really differs.