# Basic Blog Headless content management - Package: @bijectionhq/basic-blog - Category: Content Management - Status: Preview - License: Apache-2.0 - Bijection source (repository access required): https://github.com/bijectionhq/basic-blog/tree/f1c8692393b2cb4aa6f4917b7dcc8ddb473570cc/packages/convex-blog-cms - Upstream: https://github.com/daocodotorg/basic-blog/tree/651bcc128a3a67679890961e25a96de12fe49e2d/packages/convex-blog-cms - Documentation: https://docs.bijection.com/components/using - Directory: https://bijection.com/components/basic-blog ## Get the source Bijection repository access is required. Request access at https://bijection.com/contact. ```sh git clone https://github.com/bijectionhq/basic-blog.git cd basic-blog git checkout f1c8692393b2cb4aa6f4917b7dcc8ddb473570cc cd packages/convex-blog-cms ``` ## Before using this component Read the package README at the recorded revision for setup, dependencies, and API examples. Upstream documentation describes the original package and may differ from the Bijection adaptation. This is a source candidate for evaluation. Catalog inclusion does not establish npm availability or runtime qualification. Check compatibility with your SDK and deployment before adoption. External providers run their own compute. ## Upstream package documentation Recorded 2026-10-23. This describes basic-blog-convex-blog-cms; check the Bijection adaptation separately. Basic Blog provides a complete headless CMS solution as a Convex component, including schema for posts, blocks, and site settings with file upload support. It bundles a TipTap-based admin interface accessible via `blog-admin-serve`, plus Next.js helpers for RSS feeds, sitemaps, and JSON-LD structured data. The component handles both content management through mutations/queries and provides ready-to-use SEO tooling for public-facing blog implementations. ### Use cases - **Building a company blog or documentation site** where you need content management capabilities without maintaining separate CMS infrastructure - **Adding blog functionality to existing Convex apps** where you want integrated content management alongside your application data - **Creating headless content workflows** where editors use the bundled admin UI while developers build custom frontends with full control over presentation - **Implementing SEO-optimized blogs** that need RSS feeds, sitemaps, and structured data generation with minimal configuration - **Rapid prototyping of content-driven applications** where you need both admin tooling and public content APIs immediately available ### How it works The component provides a complete schema with `siteSettings`, `posts`, and `postBlocks` tables, plus queries and mutations for content management. You register the component in your Convex deployment and use `makeBlogAdminAPI` to expose admin endpoints including `generateUploadUrl` for file handling. The bundled admin interface runs as a separate SPA served by the `blog-admin-serve` command, connecting to your Convex deployment via the admin API. Optional token authentication uses a shared `BLOG_ADMIN_API_KEY` between Convex environment and the admin server. For public-facing integration, the component exports Next.js helpers for RSS (`/rss.xml`), sitemap (`/sitemap.xml`), and JSON-LD generation. You build your own frontend components using the public queries, with examples provided for common patterns like post lists and detail pages using the standardized DTOs. ### Upstream README # Basic Blog — Convex blog & CMS component Open-source monorepo around **[basic-blog-convex-blog-cms](https://www.npmjs.com/package/basic-blog-convex-blog-cms)** on npm: a **[Convex component](https://docs.convex.dev/components)** for a small headless blog (posts, blocks, site settings, uploads), a **bundled admin** (`blog-admin-serve`), **integration docs**, **examples**, and an optional **MCP server** for agents. [npm](https://www.npmjs.com/package/basic-blog-convex-blog-cms) [License](LICENSE) --- ## Repository map | Area | Path | What it is | | --------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Published package** | `[packages/convex-blog-cms](packages/convex-blog-cms)` | Convex component (schema, queries, mutations), `makeBlogAdminAPI`, Next.js / RSS / sitemap / JSON-LD helpers | | **Bundled admin UI** | `[packages/convex-blog-cms](packages/convex-blog-cms)` (same package) | TipTap CMS SPA in `dist/admin-spa`; `blog-admin-serve` / `convex-blog-admin serve`; `[Dockerfile.admin](packages/convex-blog-cms/Dockerfile.admin)` for containers | | **MCP server** | `[packages/convex-blog-mcp](packages/convex-blog-mcp)` | HTTP or stdio MCP for `list_articles`, `create_article`, `update_article` (not on npm) | | **Host snippets** | `[docs/reference/convex-host](docs/reference/convex-host)` | Copy-paste `blog.ts`, `http.ts`, `schema.ts`, `convex.config.ts` | | **Demos** | `[examples/convex-host](examples/convex-host)`, `[examples/next-app](examples/next-app)` | Minimal Convex host · Next.js App Router + public blog | | **Reference UI** | `[examples/blog-ui](examples/blog-ui)` | React for **public** post/list DTOs (not in the npm bundle) | | **TanStack sample** | `[examples/tanstack-display](examples/tanstack-display)` | Minimal SPA pattern with public queries | Visitor-facing React is **your app** (or copy from `examples/blog-ui` / follow `examples/next-app`). The npm package does not ship public page components. --- ## Run the admin locally 1. Install the package and wire Convex: [docs/SETUP.md](docs/SETUP.md) (component, `makeBlogAdminAPI`, including `generateUploadUrl`). 2. From the project that has the dependency: ```bash CONVEX_URL="https://YOUR_DEPLOYMENT.convex.cloud" npx blog-admin-serve ``` Same as `npx convex-blog-admin serve`. In this repo: `pnpm blog:admin` from the root. 3. Open **[http://127.0.0.1:3847/admin](http://127.0.0.1:3847/admin)**. **Optional token auth** (same secret in Convex and env): ```bash npx convex env set BLOG_ADMIN_API_KEY your-long-random-secret CONVEX_URL="https://…" BLOG_ADMIN_API_KEY="…" npx blog-admin-serve ``` **Site settings** (name, public URL, default OG image): set in the admin or via API — see [Site settings](packages/convex-blog-cms/README.md#site-settings-global). Env reference: [docs/CONFIGURATION.md](docs/CONFIGURATION.md). Admin deep dive: [Start the admin panel](packages/convex-blog-cms/README.md#start-the-admin-panel). **Uploads:** the admin uses `blog.generateUploadUrl` from `makeBlogAdminAPI`. Images are stored as `Id<"_storage">`; public URLs are resolved at read time for SEO and previews. --- ## Deploy on Railway One Railway template provisions **admin UI** and **MCP HTTP** in one project. 1. Set **`CONVEX_URL`** on each service (and optional **`BLOG_ADMIN_API_KEY`** / MCP bearer token if you use them). 2. **Networking → Generate domain** for each service you expose. 3. Open **`/admin`** for the CMS; point MCP clients at your MCP service URL. **Details:** [Admin on Railway](packages/convex-blog-cms/README.md#deploy-the-admin-on-railway) · [MCP Streamable HTTP / Railway](packages/convex-blog-mcp/README.md#streamable-http-railway) **Deploy one service only** (import this repo on Railway): MCP → Root Directory **`packages/convex-blog-mcp`** · Admin → **`packages/convex-blog-cms`** --- ## Documentation | Doc | For | | ------------------------------------------------------------------------ | --------------------------------------------------------------------------- | | [docs/SETUP.md](docs/SETUP.md) | Install, register the component, `makeBlogAdminAPI`, HTTP, optional Next.js | | [docs/RENDERING.md](docs/RENDERING.md) | DTOs, public queries, `examples/blog-ui` | | [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Env vars, auth, component naming | | [packages/convex-blog-cms/README.md](packages/convex-blog-cms/README.md) | Package exports, peers, site settings, admin & Docker | | [packages/convex-blog-mcp/README.md](packages/convex-blog-mcp/README.md) | Cursor / Claude / Codex, Docker, HTTP MCP | | [CONTRIBUTING.md](CONTRIBUTING.md) | Tests, codegen, PRs | --- ## HTTP routes (host) Example RSS and sitemap handlers: `[docs/reference/convex-host/convex/http.ts](docs/reference/convex-host/convex/http.ts)` - `GET /rss.xml` - `GET /sitemap.xml` --- ## Package and example details `**[packages/convex-blog-cms](packages/convex-blog-cms)**` (`basic-blog-convex-blog-cms` on npm) — `siteSettings`, `posts`, `postBlocks`; `makeBlogAdminAPI`; `./next` SEO helpers; bundled admin SPA under `dist/admin-spa`. Full field and API list: [package README](packages/convex-blog-cms/README.md). `**[packages/convex-blog-mcp](packages/convex-blog-mcp)**` — not published; stdio or Streamable HTTP. See [its README](packages/convex-blog-mcp/README.md). **Examples** — `[examples/convex-host](examples/convex-host)` (smallest host), `[examples/next-app](examples/next-app)` (Next.js + public pages), `[examples/blog-ui](examples/blog-ui)` (presentational components), `[examples/tanstack-display](examples/tanstack-display)` (SPA-oriented sample). --- ## Scripts (monorepo) | Command | Description | | ---------------------------------------------------- | ----------------------------------------------------------------- | | `pnpm test` | CMS package unit tests | | `pnpm --filter basic-blog-convex-blog-cms run build` | TypeScript + admin SPA build | | `pnpm dev:next` | `examples/next-app` dev server (after Convex is configured there) | ```bash pnpm install pnpm dev # Convex codegen/watch + admin SPA (CMS package) ``` --- ## Community and license - **Issues:** [GitHub Issues](https://github.com/daocodotorg/basic-blog/issues) - **Contributing:** [CONTRIBUTING.md](CONTRIBUTING.md) · [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) - **License:** [Apache-2.0](LICENSE)