AirdraftAirdraft
Get started
All guides

What is Airdraft?

An introduction to Airdraft — the open-source headless CMS for developers who want full control over their content.

3 min read585 words

Airdraft is an open-source headless CMS designed for developers who want structured content management without giving up control of where their data lives. You define the schema, pick where content is stored, and choose how to serve it — Airdraft handles the rest.

Two ways to use Airdraft

Airdraft runs in two fundamentally different modes:

Cloud-managed (hosted)

Airdraft Cloud is the fully managed version. Create a team, create a project, and get a hosted CMS endpoint immediately — no servers to provision or maintain.

  • Content is stored in Airdraft's cloud infrastructure
  • GitHub integration syncs content directly to a repository as MDX/JSON files
  • Dashboard at app.airdraft.space with a full editor UI
  • Authentication, media storage, and billing all managed for you

Best for: teams who want a turnkey solution and are comfortable with a hosted service.

Self-hosted

Install Airdraft in your own Next.js app (or any Node.js server) and run it wherever you like. You own all the data.

  • Single command setup: npx airdraft init
  • Content stored in your own database (SQLite, PostgreSQL, or MongoDB) or flat files on disk
  • Bring your own media storage (local disk, S3, R2, Cloudinary, and more)
  • Zero vendor lock-in — export your content at any time

Best for: developers who need full data sovereignty or complex custom integrations.

Core concepts

Concept What it means
Collection A content type, like posts, authors, or products. Defined in airdraft.schema.json.
Entry A single piece of content belonging to a collection — a blog post, a team member, a FAQ item.
Field A typed property on an entry: string, rich-text, media, relation, number, etc.
Schema The full definition of all collections and their fields — the source of truth for your content model.
Slug The unique identifier for an entry within a collection. Used in URLs and API calls.
SHA A content fingerprint used for optimistic concurrency — prevents two authors overwriting each other's changes.
Draft / Published Every entry has a status. Drafts are hidden from public queries unless you explicitly request them.
Plugin Middleware that adds capabilities: authentication, media handling, SEO fields, audit logging, schema editing.
Adapter The storage layer that backs a collection: local file system, GitHub, SQLite, Postgres, MongoDB.

What Airdraft is NOT

  • Not a page builder — Airdraft serves structured data via an API. You build the pages however you like (Next.js, Astro, SvelteKit, etc.).
  • Not a database — Airdraft is a CMS layer on top of your storage. It adds schema, validation, a publish workflow, and an editor UI.
  • Not opinionated about your frontend — Use any framework. The @airdraft/react package provides React hooks, but the REST API works with anything.

The content lifecycle

Schema definition (airdraft.schema.json)
        ↓
  Author creates entry in editor UI
        ↓
  Entry saved as draft → reviewed → published
        ↓
  Frontend queries published entries via API or hooks
        ↓
  Page renders structured content

Package overview

Package Purpose npm
@airdraft/next Route handler factory + server client (createCmsClient) + Next.js config wrapper npm
@airdraft/core Core engine — defineConfig, LocalAdapter, GitHubAdapter, all shared types npm
@airdraft/react React hooks: useEntries, useEntry, useMedia, useAuth, useTeam npm
@airdraft/react-ui Drop-in admin UI: CMSAdmin, EntryEditor, MediaManager, SchemaEditor npm
@airdraft/client TypeScript HTTP client — client.entries.list(), client.media.upload() npm
@airdraft/cli npx airdraft init and management commands npm
@airdraft/content Pure helpers: resolveMediaUrl, parseMarkdown, resolveRelation npm
@airdraft/react-content RSC display components: EntryCard, BodyField, MediaField, DateField npm
@airdraft/plugin-auth withAutoAuth — login, sessions, OAuth, invite flow npm
@airdraft/plugin-media withAutoMedia — file upload + URL injection npm
@airdraft/plugin-seo withSeo — injects SEO fields into collections npm
@airdraft/plugin-audit-log withAuditLog — structured audit events npm

Next steps

Resources