---
name: new-block
description: Scaffold a new page builder block for Turbo Start Sanity end-to-end — Sanity schema, GROQ projection, styled React component, Markdown serializer, tests, and all registrations. Use when asked to add, create, or scaffold a new page builder block, section, or content module (e.g. "add a testimonials block", "create a pricing table section", "/new-block stats").
title: new-block
canonical_url: https://skilld.dev/gh/robotostudio/turbo-start-sanity/new-block
last_updated: 2026-10-09T17:15:43.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> If the user asked to install this Skill, run `npx skilld install robotostudio/turbo-start-sanity/new-block`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/new-block`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/robotostudio/turbo-start-sanity/new-block) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/new-block`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/new-block --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/new-block --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# New Page Builder Block

Scaffold a complete page builder block in one pass. Every block touches three
workspaces — `packages/sanity-blocks` (source of truth), `packages/sanity`
(GROQ), and `apps/web` (rendering) — plus generated types. Studio registration
is automatic once the schema joins `blockSchemas`.

> Credit: adapted for Turbo Start Sanity from Michael's `/new-module` skill for
> SanityPress — <https://sanitypress.dev/blog/new-module-skill-claude-code>.

## Inputs

Before writing files, establish:

1. **Block name** — two forms, used consistently everywhere:
   - `camelCase` schema type name, e.g. `pricingTable` (matches `_type`)
   - `kebab-case` directory/file name, e.g. `pricing-table`

   Check `blockSchemas` in `packages/sanity-blocks/src/sanity-blocks.ts`
   first — if the name is taken you are editing a block, not adding one.
2. **Fields** — what content editors manage. If the request doesn't say, ask.
   Reuse shared field helpers from
   `packages/sanity-blocks/src/internal/schema-fields.ts`
   (`buttonsField`, `definePortableTextField`, etc.) before defining new shapes.
3. **An icon** — all ten block schemas import one from `lucide-react`; match
   them. Then add a matching stub to
   `packages/sanity-blocks/src/internal/testing/lucide-react.mock.tsx`:
   `lucide-mock-coverage.test.ts` greps `src/` for `from "lucide-react"` and
   fails the whole suite on any icon with no stub, and an unstubbed icon
   renders as `undefined` ("Element type is invalid") in every component test.
   (`@sanity/icons` is not scanned, so it needs no stub — but it is used for
   Studio UI, not block schemas.)

Study the closest existing block in `packages/sanity-blocks/src/` (e.g. `cta`
for text+buttons, `showcase-grid` for card grids, `faq-accordion` for
nested arrays) and mirror its structure and idioms.

## Steps

Work through all steps in order — a block missing any registration renders as
"Component not found" on the web or blank in `.md` output.

### 1. Create the block directory

`packages/sanity-blocks/src/<kebab>/` containing:

**`<kebab>.schema.ts`** — the Sanity schema:

```ts
import { Table } from "lucide-react";
import { defineField, defineType } from "sanity";

export const pricingTableSchema = defineType({
  name: "pricingTable",
  type: "object",
  icon: Table,
  fields: [
    defineField({
      name: "title",
      title: "Title",
      type: "string",
      description: "The large text that is the primary focus of the block",
    }),
    // ...more fields — every field needs a `description` written for
    // non-technical editors
  ],
  preview: {
    select: { title: "title" },
    prepare: ({ title }) => ({
      title,
      subtitle: "Pricing Table",
    }),
  },
});
```

**`<kebab>.groq.ts`** — the GROQ projection, reusing fragments from
`../internal/groq-fragments` (`richTextFragment`, `buttonsFragment`,
`imageFragment`, …). Don't expand images unless the component needs the
expanded fields:

```ts
import { buttonsFragment, richTextFragment } from "../internal/groq-fragments";

export const pricingTableGroqProjection = /* groq */ `
  _type == "pricingTable" => {
    ...,
    ${richTextFragment},
    ${buttonsFragment},
  }
`;
```

**`index.tsx`** — the styled React component (Tailwind v4 +
`@workspace/ui`). Define an explicit props interface with all fields
optional/nullable — the web app asserts the generated query type onto it, so
looser is safer. Conventions: wrap in `<section>` with its own
`<div className="container">` rail, prefer `grid` over `flex` unless two
siblings, use `SanityImage` / `SanityButtons` / `RichText` / `BlockEyebrow`
from `@workspace/sanity-blocks/internal/*`, and give the `<section>` the shared
`block-section` class (`hero` and `logo-cloud` are the two that opt out, both
with their own full-bleed layout).

The hardcoded `id` is the repo-wide convention (`id="cta"`, `id="faq"`,
`id="showcase"`, …) and doubles as the in-page anchor. It assumes one instance
per page: the page builder is an unconstrained array, so an editor who adds the
same block twice gets a duplicate `id`. Keep the convention, and drop the `id`
if the block is one an editor is likely to repeat:

```tsx
import { BlockEyebrow } from "@workspace/sanity-blocks/internal/block-eyebrow";
import type { RichTextValue } from "@workspace/sanity-blocks/internal/rich-text";
import { RichText } from "@workspace/sanity-blocks/internal/rich-text";

export interface PricingTableProps {
  eyebrow?: string | null;
  richText?: RichTextValue;
  title?: string | null;
}

export function PricingTable({
  eyebrow,
  title,
  richText,
}: Readonly<PricingTableProps>) {
  return (
    <section className="block-section" id="pricing-table">
      <div className="container">
        <BlockEyebrow eyebrow={eyebrow} />
        <h2 className="text-balance font-semibold text-3xl md:text-5xl">
          {title}
        </h2>
        <RichText richText={richText} />
      </div>
    </section>
  );
}
```

**`markdown.ts`** — the Markdown serializer, composing helpers from
`../internal/markdown` (`headingToMarkdown`, `eyebrowToMarkdown`,
`buttonsToMarkdown`, `joinSections`) and
`../internal/portable-text-to-markdown`.

`MarkdownBlock` in `../internal/markdown.ts` is one wide interface of optional
fields accumulated across every block, not a per-block type — it already
carries `items`, `cards`, `logos`, `socials`, `testimonial` and more. If the
serializer reads a field that is *not* yet there, add it — and any row type it
needs — to `MarkdownBlock` in the same edit, or the serializer will not
compile:

```ts
import {
  type MarkdownBlock,
  type MarkdownOptions,
  headingToMarkdown,
  joinSections,
} from "../internal/markdown";
import { portableTextToMarkdown } from "../internal/portable-text-to-markdown";

export function pricingTableToMarkdown(
  block: MarkdownBlock,
  options: MarkdownOptions
): string {
  return joinSections([
    headingToMarkdown(block.title, 2),
    portableTextToMarkdown(block.richText, options),
  ]);
}
```

**`<kebab>.test.tsx`** — render the component with `renderToStaticMarkup`
and assert primary content appears (see `cta/cta.test.tsx`).

**`<kebab>-markdown.test.ts`** — cover: empty block returns `""`, fields
serialize joined by blank lines, markdown chars are escaped, and **no HTML/JSX
leaks** (`expect(result).not.toMatch(/<\/?[A-Za-z]/)` — the `\/?` also catches a
stray closing tag like `</p>`, which the bare `/<[A-Za-z]/` in the existing
tests misses). Mirror `cta/cta-markdown.test.ts` for the rest.

### 2. Register in the package root

In `packages/sanity-blocks/src/sanity-blocks.ts`: import the schema, add a
named `export`, and append it to the `blockSchemas` array. This alone
registers the block in Studio — `apps/studio/schemaTypes/index.ts` and
`definitions/pagebuilder.ts` both map over `blockSchemas`.

No `package.json` edit is needed: the package's wildcard exports
(`./*/index`, `./*.groq`, `./*.schema`) already cover the new directory.

### 3. Add the GROQ projection to the shared query

In `packages/sanity/src/query.ts`: import
`<camel>GroqProjection` from `@workspace/sanity-blocks/<kebab>/<kebab>.groq`
and add it to `pageBuilderFragment` alongside the existing projections.

### 4. Regenerate Sanity types

```bash
pnpm --filter studio extract
pnpm type
```

Both commands are required, in that order. `pnpm type` runs
`sanity typegen generate`, which reads the **committed**
`apps/studio/schema.json` — it does not look at the schema source. Only
`sanity schema extract` refreshes that file. Run `pnpm type` alone and the
generated types silently keep the old schema, leaving
`PagebuilderType<"<camel>">` unresolvable in step 5 (never paper over that with
a cast — it means extract didn't run).

Together they update `packages/sanity/src/sanity.types.ts`; the web app's
`PagebuilderType<"<camel>">` in `apps/web/src/types.ts` picks the new block up
automatically — never hand-write Sanity shapes.

### 5. Register the web renderer

In `apps/web/src/components/pagebuilder.tsx`: import the component from
`@workspace/sanity-blocks/<kebab>/index` and add a `case` to
`renderBlockComponent`:

```tsx
case "pricingTable":
  return <PricingTable {...(block as PagebuilderType<"pricingTable">)} />;
```

### 6. Register the Markdown serializer

In `packages/sanity-blocks/src/internal/page-builder-to-markdown.ts`: import
`<camel>ToMarkdown` from the block's `markdown.ts` and add a `case` to the
`blockToMarkdown` switch. Without this the block renders blank in `.md`
content negotiation (`/page.md`, `Accept: text/markdown`).

### 7. Studio insert-menu thumbnail

The page builder insert menu looks for
`apps/studio/static/thumbnails/preview-<kebab>.png`, synced at install time
from `packages/sanity-blocks/src/<kebab>/thumbnail.png` by
`pnpm --filter studio sync-thumbnails`. The `generate-thumbnails-agentic` skill
does this, or note in the PR that the thumbnail is pending — the block works
without it; the menu tile just has no preview image.

### 8. Verify

```bash
pnpm --filter @workspace/sanity-blocks test   # component + markdown tests
pnpm check-types
pnpm format                                   # Biome, auto-fix
pnpm lint
```

`check-types` does **not** catch a missing registration. Both switches —
`renderBlockComponent` and `blockToMarkdown` — end in a `default` arm with no
`never` exhaustiveness guard, so a missing `case` type-checks clean and only
shows up at runtime as the "Component not found for block type" placeholder, or
as a blank section in `.md` output. Grep for the two `case` arms instead:

```bash
grep -rn 'case "<camel>":' apps/web/src/components/pagebuilder.tsx \
  packages/sanity-blocks/src/internal/page-builder-to-markdown.ts
```

One hit per file. Fewer means a registration is missing.

## Checklist

- [ ] `packages/sanity-blocks/src/<kebab>/` — schema, groq, index.tsx, markdown.ts, two test files
- [ ] Every schema field has a `description`
- [ ] Schema icon stubbed in `internal/testing/lucide-react.mock.tsx`
- [ ] Exported + appended to `blockSchemas` in `sanity-blocks.ts`
- [ ] Projection added to `pageBuilderFragment` in `packages/sanity/src/query.ts`
- [ ] `pnpm --filter studio extract` **then** `pnpm type` — types include the block
- [ ] `case` added in `renderBlockComponent` (`apps/web/src/components/pagebuilder.tsx`)
- [ ] `case` added in `blockToMarkdown` (`internal/page-builder-to-markdown.ts`)
- [ ] Any new field the serializer reads added to `MarkdownBlock`
- [ ] Thumbnail added or flagged as pending
- [ ] Both `case` arms grepped for — `check-types` will not flag a missing one
- [ ] Tests, `check-types`, and lint pass
