create-component

Files (2)

• SKILL.md
• reference.md

SKILL.md (first lines)

# Create Component

Define Storyblok components as TypeScript files in `schema/`. Each file default-exports a call to `contentType()` or `nestable()` with a `schema` array of field types.

## Installation

This package is published to the GitHub Package Registry.

### npm / Yarn 1

Add a `.npmrc` to your project root:

```
@jimdrury:registry=https://npm.pkg.github.com
```

Then install:

```bash
npm install @jimdrury/storyblok-component-schema
```

### Yarn 2+ (Berry)

Add to your `.yarnrc.yml`:

```yaml
npmScopes:
  jimdrury:
    npmRegistryServer: https://npm.pkg.github.com
```

Then install:

```bash
yarn add @jimdrury/storyblok-component-schema
```

## Configuration

Create a `.component-schema.yaml` in your project root:

```yaml
componentsDir: ./schema
storyblok:
  apiToken: "${STORYBLOK_API_TOKEN}"
  spaceId: "${STORYBLOK_SPACE_ID}"
```

Values wrapped in `${...}` are resolved from environment variables at runtime. All fields are optional -- the CLI falls back to env vars (`.env.local`) and defaults.

## Workflow

1. Create `schema/<name>.ts`
2. Import the component-type factory and field-type factories
3. Default-export the component definition
4. Run `npx storyblok-component-schema plan` to preview, `npx storyblok-component-schema apply` to push

## Imports

```ts
import { contentType, nestable, text, textarea, richtext, markdown, number, datetime, boolean, option, options, blocks, multilink, asset, multiasset, tab, table, references } from '@jimdrury/storyblok-component-schema';
```

Only import the factories you need. All exports are available from `@jimdrury/storyblok-component-schema`.

## Component Types

### contentType -- root-level entries (pages, articles, settings)

```ts
export default contentType({
    name: 'page',              // required -- lowercase + underscores only
    display_name: 'Page',      // required -- label in Storyblok UI
    folder: 'content',         // optional -- component group path
    tags: ['marketing'],       // optional -- for filtering / block restrictions
    image: 'https://...',      // optional -- preview image URL
    preview_field: 'title',    // optional -- field used as preview title
    schema: [ /* fields */ ],  // required -- array of field definitions
});
```

Returns `is_root: true`.

### nestable -- reusable blocks embedded via `blocks()` fields

```ts
export default nestable({
    name: 'hero',
    display_name: 'Hero',
    folder: 'layout',
    tags: ['layout'],
    schema: [ /* fields */ ],
});
```

Returns `is_root: false, is_nestable: true`. Parameters are identical to `contentType`.

## Field Types Quick Reference

Every field accepts base params: `name` (required), `description`, `tooltip`, `required`.

| Factory | Use for | Key specific params |
|---------|---------|---------------------|
| `text` | Short strings | `translatable`, `default_value`, `max_length`, `regex` |
| `textarea` | Multi-line text | `default_value`, `max_length` |
| `richtext` | WYSIWYG editor | `max_length`, `allow_target_blank` |
| `markdown` | Markdown editor | `max_length`, `rich_markdown` |
| `number` | Numeric input | `min_value`, `max_value`, `decimals`, `steps`, `default_value` |
| `datetime` | Date/time picker | `disable_time`, `default_value` |
| `boolean` | Toggle | `default_value`, `inline_label` |
| `option` | Single-select | `options` (required), `default_value`, `source`, `datasource_slug` |
| `options` | Multi-select | `options` (required), `default_value`, `min_options`, `max_options` |
| `blocks` | Nested blocks | `minimum`, `maximum`, restriction params (see below) |
| `multilink` | Links | `email_link_type`, `asset_link_type`, `show_anchor`, `allow_target_blank` |
| `asset` | Single file | `filetypes`, `allow_external_url` |
| `multiasset` | Multiple files | `filetypes`, `allow_external_url` |
| `tab` | Editor tabs | `display_name` (required), `fields` (required) |
| `table` | Editable table | (base params only) |

From jimdrury/jimdrury-component-schema, MIT.

More from jimdrury/jimdrury-component-schema