Add your first component in 15 minutes

A timed walkthrough of the exact steps in Adding a component, building a real (if small) component from scratch: a Spacer block with a configurable height. Times assume you already have the repo cloned and pnpm install run.

1. Create the component file (5 min)

Create packages/components/src/blocks/Spacer.tsx:

import { registerComponent } from "@olgax.com/sdk";

export type SpacerProps = {
  height: number;
};

const Spacer = ({ height }: SpacerProps) => (
  <div style={{ height }} />
);

registerComponent<SpacerProps>("Spacer", {
  fields: {
    height: { type: "number" },
  },
  defaultProps: {
    height: 32,
  },
  render: (props) => <Spacer {...props} />,
});

2. Register it in the package index (1 min)

Add one line to packages/components/src/index.ts, alongside the other blocks:

import "./blocks/Spacer";

3. Run it locally (3 min)

pnpm --filter demo dev

Open http://localhost:3000/home/edit - Spacer should already appear in the component drawer (Next transpiles @olgax.com/components directly from source, no build step needed - see apps/demo/next.config.ts's transpilePackages). Drag it onto the canvas and confirm the height field works.

4. Add a usage example (3 min)

Add a short section to packages/components/README.md (see the existing entries for the pattern) showing the props shape as a Data.content item.

5. Sanity-check types (3 min)

pnpm --filter demo build

Puck's config types are stricter than the dev-mode/editor diagnostics catch on their own - a full build is the reliable check. See SDK reference if you hit a generic-constraint type error here; it's a known Puck typing quirk with a documented workaround.

Total: ~15 minutes for a component with one field. Components with array fields (see Header, Gallery, etc. in Adding a component) or a data-source-backed one (see Data sources) take a bit longer, but follow the same shape.