https://github.com/qqpann/notcms
NotCMS makes it easy to create a headless CMS, from Notion
https://github.com/qqpann/notcms
api blog cms content content-management-system headless-cms javascript nodejs notcms notion notion-api sdk typescript
Last synced: 8 days ago
JSON representation
NotCMS makes it easy to create a headless CMS, from Notion
- Host: GitHub
- URL: https://github.com/qqpann/notcms
- Owner: qqpann
- Created: 2024-06-15T10:20:27.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-04-02T22:48:35.000Z (10 months ago)
- Last Synced: 2025-04-15T18:02:32.601Z (9 months ago)
- Topics: api, blog, cms, content, content-management-system, headless-cms, javascript, nodejs, notcms, notion, notion-api, sdk, typescript
- Language: TypeScript
- Homepage: https://notcms.com
- Size: 11.3 MB
- Stars: 10
- Watchers: 1
- Forks: 2
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
NotCMS
Website
·
Dashboard
·
Templates
·
Blog
NotCMS makes it easy to create a CMS, from Notion. It provides a type-safe TypeScript SDK to interact with Notion databases as your content backend.
[![npm package][npm-img]][npm-url]
[![Downloads][downloads-img]][downloads-url]
[![Issues][issues-img]][issues-url]
[![DeepWiki][deepwiki-img]][deepwiki-url]
## Key Features
- 🛡️ **Type Safety**: Fully typed queries and responses using TypeScript
- 🎯 **Simple API**: Clean and intuitive API for fetching content
- 📝 **Notion as Backend**: Use Notion's user-friendly editor for content creation
- 🔄 **Framework Agnostic**: Works with any JavaScript framework (Next.js, React, Vue, etc.)
- 🛠️ **CLI Tools**: Includes notcms-kit for easy project setup and schema management
## Getting Started
### Installation
```bash
npm install notcms
```
### Usage
#### 0. Set Up Environment Variables
Create a `.env` file in your project root:
```env
NOTCMS_SECRET_KEY=your_secret_key
NOTCMS_WORKSPACE_ID=your_workspace_id
```
You can get these values from the NotCMS Dashboard.
#### 1. Initialize a Project
NotCMS Kit provides command-line tools to streamline your workflow. You can use it directly with npx:
```bash
npx notcms-kit init
```
This will create a `notcms.config.json` file in your project root.
#### 2. Define Your Schema
The easiest way to define your schema is to use NotCMS Kit:
```bash
npx notcms-kit pull
```
This will automatically fetch your database schema from Notion and generate a TypeScript schema file.
For reference, the generated schema will look something like this:
```ts
// src/notcms/schema.ts
import { Client, Schema } from "notcms";
export const schema = {
blog: {
id: "your_notion_database_id",
properties: {
title: "title",
description: "rich_text",
published: "checkbox",
thumbnails: "files",
// Run notcms-kit pull again when properties are updated
},
},
} satisfies Schema;
export const nc = new Client({ schema });
```
#### 3. Query Your Content
```ts
import { nc } from "./notcms/schema";
// List all blog posts
const [pages] = await nc.query.blog.list();
// Get a specific blog post
const [page] = await nc.query.blog.get("page_id");
// Handle errors
const [data, error] = await nc.query.blog.list();
if (error) {
console.error("Failed to fetch blog posts:", error);
}
```
## Examples and Templates
Check out these examples to get started quickly:
- 📚 [Next.js Simple Blog Template](https://github.com/qqpann/notcms/tree/main/examples/nextjs-simple-blog-template)
- 🎨 [More templates available on our website](https://notcms.com/templates)
## Troubleshooting
### Authentication Errors
If you see errors like "secretKey is required" or "workspaceId is required", make sure:
1. Your environment variables are correctly set
2. You're using the correct variable names (`NOTCMS_SECRET_KEY` and `NOTCMS_WORKSPACE_ID`)
3. Your environment variables are being loaded properly
### Schema Errors
If you encounter schema-related errors:
1. Make sure your Notion database IDs are correct
2. Verify that the property types match what's in your Notion database
3. Try running `npx notcms-kit pull` to regenerate your schema
## Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
**Note**: This project uses [Changesets](https://github.com/changesets/changesets) for version management. When making changes that should be released, please run `pnpm changeset` to create a changeset describing your changes.
## License
This project is organized as a monorepo with multiple packages:
- `packages/notcms`: [MIT License](packages/notcms/LICENSE)
- `packages/notcms-kit`: [MIT License](packages/notcms-kit/LICENSE)
- `examples/`: [MIT License](examples/LICENSE)
See individual directories for specific license details.
[build-img]: https://github.com/qqpann/notcms/actions/workflows/release.yml/badge.svg
[build-url]: https://github.com/qqpann/notcms/actions/workflows/release.yml
[downloads-img]: https://img.shields.io/npm/dt/notcms
[downloads-url]: https://www.npmtrends.com/notcms
[npm-img]: https://img.shields.io/npm/v/notcms
[npm-url]: https://www.npmjs.com/package/notcms
[issues-img]: https://img.shields.io/github/issues/qqpann/notcms
[issues-url]: https://github.com/qqpann/notcms/issues
[codecov-img]: https://codecov.io/gh/qqpann/notcms/branch/main/graph/badge.svg
[codecov-url]: https://codecov.io/gh/qqpann/notcms
[semantic-release-img]: https://img.shields.io/badge/%20%20%F0%9F%93%A6%F0%9F%9A%80-semantic--release-e10079.svg
[semantic-release-url]: https://github.com/semantic-release/semantic-release
[commitizen-img]: https://img.shields.io/badge/commitizen-friendly-brightgreen.svg
[commitizen-url]: http://commitizen.github.io/cz-cli/
[deepwiki-img]: https://img.shields.io/badge/deepwiki-qqpann%2Fnotcms-blue
[deepwiki-url]: https://deepwiki.com/qqpann/notcms