A column type is a self-contained "plugin" that renders one kind of feed — Reddit, GitHub, an X search, an Ethereum address watcher, anything. Each plugin is three files in its own folder. Once you add the folder and one import in each of the two registries, the rest of the dashboard wires it up automatically.
lib/columns/plugins/<your-id>/
plugin.ts # pure metadata: id, label, icon, Zod schema, defaultTitle
client.tsx # "use client" — ConfigForm + ItemRenderer
server.ts # "server-only" — fetch function (talks to upstream APIs)
The split is structural: plugin.ts has no JSX and no server-only deps so
it can be imported by both halves; client.tsx carries "use client";
server.ts carries import "server-only". Server code never reaches the
client bundle and vice
4C2E
versa.
- Copy
_template/tolib/columns/plugins/<your-id>/and rename it. - Edit
plugin.ts:- Set a unique
id(kebab-case). - Define your config shape with a Zod
schema. Give every field a.default()soschema.parse({})produces the initial config. - Define a
TMetainterface foritem.meta(this types the renderer). - Pick an
iconfrom lucide-react and anaccenthex color. - Set
categoryto one ofsocial | news | ai | video | blockchain | other. - Set
capabilitiesto declare paginated, required env vars, etc.
- Set a unique
- Edit
client.tsx— implementConfigFormandItemRenderer, then wrap withdefineColumnUI({ ...meta, ConfigForm, ItemRenderer }). - Edit
server.ts— implement theServerFetcher. Theconfigyou receive has already been validated against your Zod schema, soconfig.foois fully typed and present. Note that present is not non-empty: a field declaredz.string().default("")always exists but can arrive as"". If your column needs a value to do anything, guard it before the network call (see the "Validate required inputs" convention below). - Register both halves:
- In
lib/columns/registry.ts, add an import and append toALL. - In
lib/columns/server-registry.ts, add an import and append toALL.
- In
- Run
npm run build. The parity check inserver-registry.tswill throw at module init if either registry is missing your plugin.
- A unified API route (
app/api/columns/[type]/route.ts) — no per-plugin endpoint to write. The route looks up your fetcher, validates the config with your Zod schema, and returns the result. - A typed renderer —
ItemRendererProps<TMeta>means notypeof m.score === "number"guards. - The "Add column" picker, "Configure column" dialog, drag-and-drop, refresh,
Load more, optimistic mutations, and persistence. All driven by the
declarative
ColumnUIyou registered. - A capabilities note shown to the user before they create the column —
requiresEnvandrateLimitHintsurface automatically.
-
Validate required inputs at the top of
fetch. The Zod schema enforces types, not non-emptiness —z.string().default("")lets an emptyquerythrough. If your column can't run without a value, trim-and-throw before any upstream request so the user sees a clear error instead of a wasted call:const q = config.query.trim(); if (!q) throw new Error("Search query is required.");
Most input-driven columns follow this (
linkedin,youtube,reddit,mastodon, and therepo-basedgithub-*columns). Throwing here is caught by the shared API route and surfaced to the user as a fetch-error toast. -
Keep upstream HTTP clients in
lib/integrations/<source>.tsand import them fromserver.ts. The plugin folder owns the dashboard contract; the integrations folder owns the network details. -
Cursor is opaque end-to-end — encode whatever your upstream uses (page number, after-token, etc.) as a string and treat it that way on the way back. The shared API client and column card never inspect it.
-
Don't reach into
lib/columns/server-registry.tsfrom your plugin. The fetcher logic lives inyour-id/server.ts; the registry just imports it. -
_template/is intentionally NOT registered. It exists as a copyable starting point.