MiniCMS

Minimal schema-first filesystem CMS for YAML content.

MiniCMS is:

• TypeScript-first
• YAML-backed
• filesystem-based
• AI-friendly
• small on purpose

It does not include:

• admin UI
• database
• auth
• API server
• markdown rendering
• migrations
• relations

Install

npm install minicms yaml

If you want to author schemas and run local scripts in TypeScript, also install:

npm install -D typescript tsx

Quick Start

1. Initialize a project

npx minicms init

This creates:

• AI_SYSTEM.md
• .filecms/specs/*
• cms/schemas/*
• content/*
• filecms.config.ts

2. Define collections

import { defineCollection, s } from "minicms"

export const posts = defineCollection({
  name: "posts",
  dir: "content/posts",
  schema: {
    title: s.string(),
    slug: s.string(),
    draft: s.boolean().default(false),
    tags: s.array(s.string()).default([]),
    body: s.string()
  }
})

3. Add YAML content

content/posts/hello-world.yaml

title: Hello World
slug: hello-world
draft: false
tags:
  - cms
  - yaml
body: |
  Hello from YAML.

4. Read content

import { createCMS, defineConfig } from "minicms"
import { posts } from "./cms/schemas/posts.js"

const cms = createCMS(
  defineConfig({
    collections: [posts]
  })
)

const allPosts = await cms.collection("posts").all()
const post = await cms.collection("posts").find("hello-world")

Public API

export { s } from "minicms"
export { defineCollection } from "minicms"
export { defineConfig } from "minicms"
export { createCMS } from "minicms"

Schema DSL

Available builders:

• s.string()
• s.number()
• s.boolean()
• s.date()
• s.array(schema)
• s.object(shape)
• s.enum(values)
• s.block(type, shape)
• s.blocks([...])

All fields are required by default.

Modifiers:

• .optional()
• .default(value)

CMS Queries

Basic reads:

• collection(name).all(options?)
• collection(name).find(slug, options?)
• collection(name).where(fn, options?)

High-level listing:

const result = await cms.collection("posts").list({
  filter: {
    draft: false,
    tags: { includes: "yaml" }
  },
  search: {
    query: "hello",
    fields: ["title", "body", "tags"]
  },
  sort: {
    by: "title",
    order: "asc"
  },
  page: 1,
  pageSize: 10
})

Result shape:

{
  items: [],
  total: 0,
  page: 1,
  pageSize: 10,
  totalPages: 0
}

Validate Content

npx minicms validate

This loads filecms.config.ts, reads collection content, validates YAML, and exits with a non-zero code on failure.

i18n

For localized collections:

export const pages = defineCollection({
  name: "pages",
  dir: "content/pages",
  i18n: true,
  schema: {
    slug: s.string(),
    title: s.string()
  }
})

File structure:

content/
  pages/
    home/
      ru.yaml
      en.yaml

Usage:

await cms.collection("pages").all({ locale: "ru" })
await cms.collection("pages").find("home", { locale: "en" })

Example

There is a runnable example project in example/.

From this repository:

cd example
npm run validate
npm run get-data
npm run smoke