# Prompt: Build a Storyblok field type > **If you are an AI agent that fetched this file from a URL:** the instructions for you start below the `---` line. The field to build is the description in the user's message. It replaces the example in the `` block at the end, so ignore that example. The paragraph directly below is for humans copying this prompt by hand. Copy everything below the line into Claude Code, Cursor or any AI coding agent that can run commands. Replace the description in the `` block at the bottom with your own. You need Node 22+ (the scaffold's `.nvmrc` pins 22) and, for the deploy step, a Storyblok personal access token. --- You are building a **Storyblok field plugin** (a custom field type) from the description at the end of this prompt. ## 1. Scaffold Run this from the current folder: ``` npx @storyblok/field-plugin-cli@latest create --dir . --template react --structure standalone --packageManager npm --pluginName ``` Choose `` from the description: lowercase, words joined with dashes, for example `brand-color-picker`. - `--dir` is the **parent** folder. The CLI creates `.//`, runs `npm install`, and makes its own `git init` and initial commit there. If the current folder is already a git repo, delete `/.git` to avoid a nested repo. - From here on, **work inside `.//`**. Then: - Delete `src/components/FieldPluginExample/` (the example field, its CSS and its only test) and `src/components/FieldPlugin.tsx`. - Create `src/components/Field.tsx` with your field, and make `src/App.tsx` render only ``. Put field styles in `src/components/Field.css` and pure logic in `src/lib/*.ts`, with tests next to it as `*.spec.ts`. - Do not edit `index.html`, `src/main.tsx`, `src/createRootElement.ts`, `vite.config.ts` or `tsconfig*.json`. The error thrown at the end of `main.tsx` is expected, so leave it in place. ## 2. The API (`@storyblok/field-plugin`) ```tsx import { useFieldPlugin } from '@storyblok/field-plugin/react' const plugin = useFieldPlugin({ enablePortalModal: true, // only if you use the fullscreen modal validateContent: (c: unknown) => ({ content: normalize(c) }), }) if (plugin.type !== 'loaded') return null const { data, actions } = plugin ``` - `data.content` is the stored value, already passed through `validateContent`. - `data.options` is a `Record` of per-field settings. **Values are always strings**, so parse them yourself and fall back to defaults. - `data.isModalOpen`, `data.story`, `data.storyLang`, `data.spaceId`, `data.isAIEnabled` and similar give you context. - `actions.setContent(value)` saves the value. It must be JSON-serialisable. - `actions.setModalOpen(bool)` switches to fullscreen for large UIs. Render a close button while it is open. - `actions.selectAsset()` opens the Storyblok asset picker and returns a `Promise`. - `actions.requestContext()` refreshes `data.story`. - `data.story` is loosely typed (`{ content: Record } & Record`), so narrow its values yourself. Useful keys: `name`, `slug`, `full_slug` (path including folders) and `content`, where the sibling fields live. For example, a field named `title` is `story.content.title`. The iframe height follows your content automatically. Don't use fixed heights or `100vh` outside the modal. ## 3. Rules **Value** 1. Use the simplest shape a frontend can use directly. Use a string if one string says it all, otherwise a small object. 2. `validateContent` must accept anything (`undefined`, old shapes, garbage), return a valid value and never throw. 3. Never call `setContent` on mount, only after a user action. Otherwise every story open shows unsaved changes. 4. Store data, not markup or CSS. 5. When you pick from an external API, store the ID plus a small snapshot (title, image and so on), so the frontend doesn't need a second request. **UI** - Make the field look native to the Storyblok editor. Use the CSS variables in `src/style.css` (`--sb_green`, `--sb_dark_blue`, `--light`, `--red`, …), 5px radius, 1px `--light` borders and the Roboto font. The base font size in `style.css` is 1rem, so set `font-size: 0.875rem` on your field's root yourself. - If the description leaves something open (a default, a hard limit vs a warning), choose the sensible option, state it in your plan, and document it in `PLUGIN.md`. - Design for a 300–450px wide side panel, with no horizontal scroll. - Use real `