Stormy CLI

The stormy command-line tool (@stormycms/cli) does two jobs:

• stormy init — scaffold a new project from the official Next.js boilerplate
• stormy generate — derive a CMS component schema from your existing components, so you don't maintain duplicate schemas between the CMS and your application code

Installation

# Run without installing
npx @stormycms/cli init

# Or install globally
npm install -g @stormycms/cli
stormy --help

stormy init

Creates a new Stormy CMS project from the bundled boilerplate.

stormy init
stormy init --name my-project --target ./my-project --skip-env
stormy init --name my-project --skip-install

What it does, in order:

1. Extracts the boilerplate into the target directory
2. Applies your project name to package.json, lockfiles, and README.md
3. Prompts for environment values (unless --skip-env) and writes .env files for both apps
4. Initializes a git repository
5. Installs dependencies with pnpm (unless --skip-install)

Afterwards:

cd my-project
pnpm dev
# Public site: http://localhost:3000
# Admin editor: http://localhost:4000

stormy generate

Scans a directory of components and generates CMS-wrapped component definitions — a starting export map you can refine by hand.

stormy generate
stormy generate --components ./packages/components/src/lib --output ./packages/components/src/index.ts

Generation infers each component's editable fields from its props (e.g. a title: string prop becomes an input field). Treat the output as a first draft: review field controls, defaults, parent/child constraints, and containment rules, then adjust. See Components & Schema.

Prop type mapping

stormy generate inspects React prop types and selects a CMS field for each one. The React plugin currently maps:

Framework detection

The framework is resolved in this order:

1. framework in stormy.config.ts
2. Auto-detection from your package.json dependencies (checked in order: Vue, Svelte, Solid, React)
3. Plugin-based detection

React is the fully supported plugin today (@stormycms/react/plugin); the detection scaffolding for other frameworks anticipates future plugins.

Configuration: stormy.config.ts

Place a stormy.config.ts at your project root to set defaults:

import type { StormyConfig } from '@stormycms/cli';

const config: StormyConfig = {
  components: './src/components',
  output: './cms/schema.ts',
  framework: 'react', // optional; auto-detected if omitted
  plugins: [], // optional custom framework plugins
};

export default config;

CLI flags override config values; config values override the built-in defaults.

Plugin System

The CLI supports custom framework plugins, registered by module name or path in the plugins array of stormy.config.ts. A framework plugin implements the StormyPlugin interface:

import type { StormyPlugin, ComponentInfo, GenerateOptions } from '@stormycms/cli';

const myFrameworkPlugin: StormyPlugin = {
  /** Plugin name (e.g., 'react', 'vue', 'svelte') */
  name: 'my-framework',

  /** Detect whether this framework is used in the project */
  detect: (cwd: string) => {
    // e.g. inspect package.json dependencies
    return false;
  },

  /** Parse component files and extract metadata */
  parseComponents: (options: GenerateOptions): ComponentInfo[] => {
    // Read options.components, return one ComponentInfo per component:
    // { name, fileName, export, componentId, label, fields }
    return [];
  },

  /** Generate the schema file content written to options.output */
  generateSchema: (components: ComponentInfo[], importBasePath: string): string => {
    return '// generated export map';
  },
};

export default myFrameworkPlugin;

Each ComponentInfo.fields entry maps a component prop to a CMS field ({ label, prop, field, options?, fieldTypes?, subFields? }) — the same shape withCMS consumes (see Components & Schema). @stormycms/react/plugin is the reference implementation: it detects React from your dependencies, parses .tsx component files, infers fields from prop types, and emits a withCMS-wrapped export map.