Blocks

A block turns a record into a page. You declare a block type once with block("hero").fields(({ f }) => ({ ... })), it gets its own typed fields, a slot in the admin block picker, and optional server-side data prefetch. Add an f.blocks() field to a collection and editors can stack, reorder, and nest those blocks visually; the field stores one normalized JSONB document, and you render the saved tree on the frontend with BlockRenderer. Same field builder as collections, same codegen, no bespoke schema to maintain.

What it does

• Defines a content type with fields, block("hero").fields(({ f }) => ({ ... })) uses the exact same f field builder as collections, so every field type, chain method, validation, and admin input is available.
• Appears in the admin block picker, .admin(({ c }) => ({ label, icon, category })) controls how the block is labeled, grouped, ordered, and whether it shows up when an editor adds content.
• Stores a normalized block tree, an f.blocks() field persists a BlocksDocument (_tree + _values) as one jsonb column: order, nesting, and per-block values in a single field.
• Prefetches related data on read, .prefetch() expands relation/upload fields or runs a loader during the collection read, attaching the result to _data so the frontend renders without extra round trips.
• Nests for layout, .allowChildren() makes a block a container that holds other blocks; the renderer hands them down as children.
• Renders anywhere with BlockRenderer, map each block type to a React component; the renderer walks the tree, passes each block its typed values and prefetched data, and nests children.
• Filters by block content, a blocks field ships operators like hasBlockType and blockCount, so you can query "pages that contain a cta block".

Quick start

A block is one file under your blocks/ directory. Import block from #questpie/factories (the codegen-generated factory that knows your enabled modules, so f.richText() / f.blocks() appear on f), declare admin metadata and fields, and export it.

import { block } from "#questpie/factories";

export const heroBlock = block("hero")
  .admin(({ c }) => ({
    label: { en: "Hero Section", sk: "Hero sekcia" },
    icon: c.icon("ph:image"),
    category: { label: { en: "Sections" }, icon: c.icon("ph:layout"), order: 1 },
    order: 1,
  }))
  .fields(({ f }) => ({
    title: f.text(255).required().localized(),
    subtitle: f.textarea().localized(),
    backgroundImage: f.upload(),
  }))
  // Expand the upload field on read so the renderer gets a full asset record.
  // The full builder API (prefetch shapes, allowChildren, form) is below.
  .prefetch({ with: { backgroundImage: true } });

Then add an f.blocks() field to a collection to give it a page builder:

import { collection } from "#questpie/factories";

export const pages = collection("pages")
  .fields(({ f }) => ({
    title: f.text(255).required(),
    content: f.blocks(), // visual block editor, stored as one jsonb column
  }))
  .title(({ f }) => f.title);

Then regenerate the typed surface and create the table:

questpie generate   # discovers blocks/, wires f.blocks(), builds admin.blocks + BlockProps
questpie push       # adds the jsonb content column to the pages table

That gives you a pages.content field that renders the block editor in the admin, validates each block against its declared fields, and returns a BlocksDocument your frontend can render.

Example → stored shape

A blocks field stores a normalized document: the tree (order + nesting) is kept separate from the per-block values, both keyed by a stable block id. After a read, .prefetch() results land in _data under the same ids.

// pages.content after an editor adds one hero block:
{
  _tree: [
    { id: "blk_a1", type: "hero", children: [] },
  ],
  _values: {
    blk_a1: { title: "Sharp Cuts", subtitle: "Modern barbershop", backgroundImage: "asset_77" },
  },
  // Populated by the field's afterRead hook from each block's .prefetch():
  _data: {
    blk_a1: { backgroundImage: { id: "asset_77", url: "https://.../hero.jpg" } },
  },
}

The TypeScript shape is BlocksDocument:

interface BlocksDocument {
  _tree: BlockNode[];                                  // hierarchy: order + nesting
  _values: Record<string, BlockValues>;                // blockId → field values
  _data?: Record<string, Record<string, {}>>;          // blockId → prefetched data
}

interface BlockNode {
  id: string;
  type: string;            // block type name, e.g. "hero"
  children: BlockNode[];   // nested blocks (layout blocks)
}

The block() builder

block(name) returns a chainable builder. Every method returns a new builder, so order them top to bottom and end the chain with your export. The block type name is the first argument and must match the type stored in the tree (it's also the key under admin.blocks and the renderer lookup key).

.admin(), picker metadata

.admin() takes a config object or a function receiving { c }, the component-reference proxy (c.icon("ph:…")). The shape is AdminBlockConfig:

.admin(({ c }) => ({
  label: { en: "Hero Section", sk: "Hero sekcia" },
  icon: c.icon("ph:image"),
  category: { label: { en: "Sections" }, icon: c.icon("ph:layout"), order: 1 },
  order: 1,
}))

import type { AdminConfigContext, BlockCategoryConfig } from "@questpie/admin/factories";

export const sections = (c: AdminConfigContext["c"]): BlockCategoryConfig => ({
  label: { en: "Sections", sk: "Sekcie" },
  icon: c.icon("ph:layout"),
  order: 1,
});

.fields(), the block's data

.fields() is the same callback as collections and globals, ({ f }) => ({ ... }), so every field type and chain method is available, including .required(), .localized(), .default(), .label(), relations, and uploads. Each field's per-field admin config (e.g. reactive hidden) works exactly as it does on a collection.

.fields(({ f }) => ({
  title: f.text(255).required().localized(),
  count: f.number().default(3),
  showFeatured: f.boolean().default(true),
  layout: f.select([
    { value: "grid", label: "Grid" },
    { value: "list", label: "List" },
  ]).default("grid"),
}))

Field values are validated against the block's generated Zod schema and stored under _values[blockId]. The field's read type flows into the renderer's values prop (see TypeScript).

.form(), editor layout

.form() arranges the block's fields into sections, tabs, or a grid, identical to a collection's form layout. You reference fields by name through the f proxy (here f is a name proxy, not the field builder).

.form(({ f }) => ({
  fields: [
    { type: "section", label: "Basic", fields: [f.title, f.subtitle] },
    { type: "section", label: "Pricing", layout: "grid", fields: [f.price, f.currency] },
  ],
}))

.allowChildren(), layout blocks

Call .allowChildren() to let a block contain other blocks, that is what BlockNode.children is for. Pass a number to cap the count.

import { block } from "#questpie/factories";

export const columnsBlock = block("columns")
  .admin(({ c }) => ({ label: "Columns", icon: c.icon("ph:columns") }))
  .allowChildren()        // or .allowChildren(4) for at most 4 children
  .fields(({ f }) => ({
    columns: f.select([
      { value: "2", label: "2" },
      { value: "3", label: "3" },
    ]).default("2"),
  }));

Children render via the children prop your renderer receives (see Rendering).

Prefetching block data

A block often needs related records the editor only referenced by id (an upload, a relation), or computed data (a list of recent posts). .prefetch() runs during the collection read, batched across every block on the page, and its result is attached to _data[blockId], so your renderer reads data.* with no client fetch. There are three shapes.

Shape 1, expand relation/upload fields (with)

Declare which relation or upload fields to expand. They are batch-fetched across every block on the page and replaced with full records.

.prefetch({ with: { backgroundImage: true } })

// Nested expansion is passed straight through to the collection's find `with`:
.prefetch({ with: { author: { with: { avatar: true } } } })

Each expanded field becomes ExpandedRecord | null under _data[blockId][field] (an array of records for .multiple() relations). Only fields whose metadata is a relation are expanded, a non-relation field name in with is silently ignored, never partially resolved.

Shape 2, a custom loader function

For computed data, pass a function. It receives the block's typed values and a BlockPrefetchContext (ctx), and returns arbitrary data merged into _data[blockId].

.prefetch(async ({ values, ctx }) => {
  const res = await ctx.collections.news.find({
    limit: values.count ?? 3,
    orderBy: { publishedAt: "desc" },
  });
  return { news: res.docs };
})

ctx is an AppContext plus { blockId, blockType, locale? }, so ctx.collections.<name>.find(...), ctx.db, and ctx.session are available.

Shape 3, expand, then run a loader

Combine the two: expand fields with with, then run a loader that receives the expanded records plus values.

.prefetch({
  with: { backgroundImage: true },
  loader: async ({ values, expanded, ctx }) => {
    return { analytics: await getStats(expanded.backgroundImage?.id) };
  },
})

On key conflicts, loader/function data wins over expanded data (it is merged on top).

Rendering on the frontend

Blocks are stored, not rendered, on the server, you own the markup. Pair each block type with a React component, then hand the saved document to BlockRenderer from @questpie/admin/client. Codegen collects your per-block renderers into admin.blocks, the map you pass as renderers.

import admin from "@/questpie/admin/.generated/client";
import { BlockRenderer, type BlockContent } from "@questpie/admin/client";

export function PageRenderer({ page }: { page: { content: BlockContent } }) {
  return (
    <BlockRenderer
      content={page.content}                 // _tree + _values
      renderers={admin.blocks}               // block type → component
      data={page.content._data}              // prefetched data, keyed by block id
    />
  );
}

BlockRenderer walks content._tree, looks up each node's renderer by type (falling back from kebab-case to camelCase), and renders nothing for an unknown type (with a dev-only console warning). Its props (BlockRendererComponentProps):

Each renderer receives the block's id, typed values, prefetched data, and rendered children:

import type { BlockProps } from "../.generated/client";

export function HeroRenderer({ values, data, children }: BlockProps<"hero">) {
  const bgUrl = data?.backgroundImage?.url as string | undefined;
  return (
    <section style={{ backgroundImage: bgUrl ? `url(${bgUrl})` : undefined }}>
      <h1>{values.title}</h1>
      {values.subtitle && <p>{values.subtitle}</p>}
      {children}              {/* nested blocks, for layout blocks */}
    </section>
  );
}

values is typed from the block's .fields(); data is typed from its .prefetch(). Layout blocks (.allowChildren()) render their nested blocks through children. Sources: packages/admin/src/client/blocks/block-renderer.tsx, examples/tanstack-barbershop/src/components/pages/PageRenderer.tsx, examples/tanstack-barbershop/src/questpie/admin/blocks/hero.tsx.

Querying blocks fields

The blocks field ships custom operators so you can filter on block content, not just presence. They are available on the where clause for a blocks field.

// Pages that contain a CTA block:
await app.collections.pages.find({
  where: { content: { hasBlockType: "cta" } },
});

// Pages with at least 3 root-level blocks:
await app.collections.pages.find({
  where: { content: { blockCount: { op: "gte", count: 3 } } },
});

hasBlockType and blockCount inspect _tree only (root level for the count), via Postgres JSONB functions (jsonb_array_elements, jsonb_array_length).

TypeScript

The block's field values and prefetch data drive the renderer types, you rarely write them by hand. In a renderer, use the generated BlockProps<"name">:

import type { BlockProps } from "@/questpie/admin/.generated/client";

type HeroProps = BlockProps<"hero">;
// { id; values; data?; children?; isSelected?; isPreview? }
// values inferred from .fields(), data inferred from .prefetch()

BlockProps<T> resolves to BlockRendererProps<InferBlockValues<...>, InferBlockData<...>> (the per-renderer props type, distinct from the <BlockRenderer> component's BlockRendererComponentProps), so values comes from the block's .fields() and data from its .prefetch(). The renderer props themselves are { id, values, data?, children?, isSelected?, isPreview? }, destructure what you need (values, data, and children are the ones BlockRenderer populates; isSelected / isPreview are reserved and unwired, see the Rendering note). The document and node types come from @questpie/admin/fields:

import type { BlocksDocument, BlockNode } from "@questpie/admin/fields";

If you build blocks programmatically (a plugin), block, BlockBuilder, AdminBlockConfig, BlockCategoryConfig, AdminConfigContext, BlockPrefetchContext, and the inference helpers InferBlockValues / InferBlockData are exported from @questpie/admin/factories (and @questpie/admin/server); BlockRenderer, BlockRendererProps, BlockContent, BlockNode, and isBlockContent from @questpie/admin/client. Sources: packages/admin/src/exports/{server,factories,fields,client}.ts.

Related

• Fields, every field type and chain method you use inside block().fields(), plus f.blocks() in the field reference and how to build your own field type.
• Collections, where the f.blocks() field lives and how the document is read and stored.
• Relations, what .prefetch({ with }) expands, and the with hydration it reuses.
• Hooks, the afterRead lifecycle that prefetch runs in (and the open-transaction caveat).
• Access control, the read rules that apply to expanded relations (and the upload-inherits-parent-row exception).
• Example: examples/tanstack-barbershop/src/questpie/server/blocks/ paired with src/questpie/admin/blocks/, a full page builder, server blocks paired with frontend renderers. examples/city-portal/src/questpie/server/blocks/ shows shared categories, allowChildren, and a loader prefetch.