StormyCMS is a headless content management system with a GraphQL API — and, unlike other headless platforms, a management panel that lives in your own codebase. stormy init scaffolds a public site and an admin editor as two Next.js apps that share one set of React components.

How is StormyCMS different from other headless CMS platforms?

Three ways:

You own the editor. The admin panel is code in your repository. Extend it, restyle it, add pages to it.
One schema, one place. Components are defined once in React (with withCMS) and used by both the site and the editor. There is no separate content-model portal that can drift out of sync with your code.
AI-agent friendly. Because the whole configuration is local files, coding agents can create components, register fields, and manage the site without needing access to an external editor system.

What can I build with StormyCMS?

Marketing and corporate sites, blogs and content sites, landing pages, documentation, and any component-driven website. Agencies can ship each client a customized editor without building one from scratch.

Do I have to use React and Next.js?

The official boilerplate and the @stormycms/react / @stormycms/next packages target React and Next.js. The GraphQL API itself works with any stack, and the CLI's plugin system is designed for additional frameworks (it already detects Vue, Svelte, and Solid projects, with plugins to come).

Getting Started

How do I create a project?

npx @stormycms/cli init

See Getting Started for the full walkthrough.

How do I get credentials?

Each site has a Client ID and a Client Secret. Sign in at account.stormycms.com with GitHub or Google, create a site under Dashboard → Sites, then open the site's Keys page: copy the client ID and generate the client secret (revealed once — store it safely). stormy init prompts for both when generating your .env files.

What's the difference between Client ID and Client Secret?

Client ID (x-client-id): a public identifier for your site.
Client Secret (x-client-secret): a secret that authenticates your requests. Keep it server-side; never expose it in client code or public repos.

API & Authentication

How do I authenticate API requests?

Content reads need site credentials:

headers: {
  'Content-Type': 'application/json',
  'x-client-id': 'YOUR_CLIENT_ID',
  'x-client-secret': 'YOUR_CLIENT_SECRET'
}

Editing operations additionally need Authorization: Bearer <jwt>, minted from a signed-in user's session. See API Reference → Authentication.

Through OAuth with GitHub or Google, handled by the Stormy auth service. In the boilerplate, createNextAuthHandlers from @stormycms/next wires the entire flow into one route (/api/auth/stormy), storing the session as an httpOnly cookie.

Can I call the API from the browser?

Content queries can technically be made anywhere, but your client secret must stay server-side. In practice: fetch CMS data in server components or API routes, and let the browser talk to your own endpoints.

What are the rate limits?

The API uses per-session token-bucket rate limiting with a 10-token bucket refilled at 10 tokens per minute. JWT minting (mintJwt) is additionally limited to 10 requests per minute per session. If you're rate limited, back off and retry after the indicated delay.

Content Management

What are pages?

Content containers with a URL slug, SEO metadata (title, description, keywords), an associated layout, and a tree of components.

What are layouts?

Reusable page chrome — headers, footers, navigation. Layouts can nest via parent/child chains (e.g. a "Blog" layout inside the site-wide layout), and an Outlet component marks where the page's own content renders.

What are components?

Your React components, registered for the CMS with withCMS. Each registration declares its editable fields, whether it accepts children, and placement rules (validChildren, validParents, layoutOnly, unique). See Components & Schema.

How do I create custom components?

Write a React component, add it to your project's export map with withCMS, and it appears in your admin editor. If you have existing components, stormy generate can infer a starting schema from their props. No external portal is involved.

How do I handle images and media?

The admin editor uploads files to your own S3-compatible storage (configured via S3_* env vars) and records them through the media API (createMedia, mediaItems, etc.). Components can use image fields to let editors pick media.

Technical

Do you have SDKs?

Yes — this is the recommended way to use StormyCMS:

@stormycms/core — typed client and utilities (framework-agnostic)
@stormycms/react — rendering and session hooks
@stormycms/next — Next.js auth handlers and helpers
@stormycms/cli — scaffolding and schema generation

Any standard GraphQL client also works against the raw API.

Can I use StormyCMS with static site generators?

Yes, via the GraphQL API at build time. The boilerplate renders dynamically, but nothing stops you from querying pages in a build step for Astro, Eleventy, Hugo (via a fetch script), and similar tools.

Why don't my components render on the site?

The name of each CMS component must exactly match an export key in your CMS export map (packages/components/index.ts in the boilerplate). Unknown names are skipped silently.

Why is my deeply nested content missing?

GraphQL can't express unbounded recursion, so queries expand childComponents to a fixed depth (the official client uses three levels). Query deeper explicitly if your content nests further.

Troubleshooting

I'm getting authentication errors

Check STORMY_CMS_CLIENT_ID and STORMY_CMS_CLIENT_SECRET are set and correct
For mutations: make sure the user is signed in and a JWT is being minted (session cookie stormy_session_token present)
JWTs are short-lived — re-mint via mintJwt rather than caching them long-term
If you reset your client secret, update every .env that uses it

A query returns "not found" for content I know exists

Resources are scoped per site. A page belonging to another site returns not-found (never unauthorized) so existence can't be probed across sites. Check you're using the right site's credentials.

My mutations are failing

Missing JWT (editor mutations require Authorization: Bearer <jwt>)
Missing required fields — e.g. createPage requires slug, metadata, components, layoutId, createdAt, updatedAt
Referencing a non-existent layoutId

Security

Should I use environment variables for credentials?

Yes, always:

STORMY_CMS_CLIENT_ID=your-client-id-here
STORMY_CMS_CLIENT_SECRET=your-client-secret-here

Never commit .env files.

Review the API Reference
Browse the Examples
Visit stormycms.com

Last updated: 7/10/26, 3:17 AM

Frequently Asked Questions

General

What is StormyCMS?