structcms

Use GitHub as a headless CMS. Fetch and transform content stored in a GitHub repository via the GitHub API.

Why structcms?

structcms treats a GitHub repository as your content store — no extra infrastructure, no vendor lock-in.

| Feature | structcms | Outstatic | Decap CMS | Contentlayer | |---|---|---|---|---| | Zero added infrastructure | ✅ No DB, no server | ✅ | ⚠️ Needs Git Gateway / Netlify | ✅ | | Separate content & app repos | ✅ Any repo, any owner | ❌ Same repo only | ⚠️ Manual config | ❌ Local files only | | Private repository support | ✅ Token-based access | ❌ Public repos only | ⚠️ Limited | ✅ | | Setup requirement | GitHub Token only | GitHub OAuth App | Netlify / OAuth | Local file system |

How it works

Store content under a contents/ directory in any GitHub repository. Each piece of content lives in its own slug-named folder with a Markdown file and a JSON metadata file.

your-content-repo/
└── contents/
    ├── hello-world/
    │   ├── content.md
    │   └── meta.json
    └── my-second-post/
        ├── content.md
        └── meta.json

Installation

npm install @asahi-fj/structcms

Quick start

import StructCms from "@asahi-fj/structcms";

const cms = StructCms({
  token: process.env.GITHUB_TOKEN!,
  owner: "your-org",
  repo: "your-content-repo",
});

const posts = await cms.getAll();
// [{ slug: "hello-world", content: "# Hello\n...", meta: { title: "Hello World", ... } }]

See USAGE.md for full examples.

Content format

meta.json

{
  "title": "Post title",
  "description": "A short description",
  "publishedAt": "2026-04-11",
  "draft": false,
  "tags": ["typescript", "cms"]
}

content.md — standard Markdown.

API

| Method | Description | |---|---| | cms.getAll() | Fetch all content entries | | cms.getById(id) | Fetch a single entry by slug (coming soon) |

Requirements

• Node.js 18+
• GitHub Personal Access Token with read access to the content repository

License

ISC