Basic Blog

Headless content management

Markdown ▾

View Markdown Download MarkdownOpen in ChatGPT ↗Open in Claude ↗Open in Perplexity ↗

Bijection source

git clone https://github.com/bijectionhq/basic-blog.git
cd basic-blog
git checkout f1c8692393b2cb4aa6f4917b7dcc8ddb473570cc
cd packages/convex-blog-cms

Bijection repository access is required. Request access.

Description

Headless content management

Explore the package README for API concepts, configuration, and examples. Check the Bijection source for adaptation-specific setup.

Available to evaluate

Review the source and its dependencies before adopting this package. Source availability does not establish npm publication or runtime qualification.

Getting started

Get the source at the revision above and read its package documentation.
Check the required Bijection SDK version, dependencies, and external service credentials.
Follow the package setup instructions and the guide to using components.
Exercise the component in your deployment according to your project’s verification rules.

Open source

Maintained source: bijectionhq/basic-blog. Based on daocodotorg/basic-blog. License: Apache-2.0. Consult the repository for license terms, notices, and contributor attribution.

From the upstream publisher

Headless blog and CMS as a Convex component: posts, block content, site settings, Convex file uploads, bundled TipTap admin + convex-blog-admin CLI, and optional Next.js metadata, RSS, sitemap, and JSON-LD helpers.

Explore the demo ↗

Upstream overview

From the upstream package documentation.

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

From the upstream package documentation.

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

From the upstream package documentation.

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 package FAQ

What does the Basic Blog component include out of the box?

Basic Blog provides Convex schemas for posts, blocks, and site settings, along with queries and mutations for content management. It includes a bundled TipTap admin UI, file upload handling, and helpers for RSS feeds, sitemaps, and JSON-LD generation in Next.js applications.

How do I run the admin interface for Basic Blog?

After installing and configuring the component with makeBlogAdminAPI, run 'CONVEX_URL=https://your-deployment.convex.cloud npx blog-admin-serve' and open http://127.0.0.1:3847/admin. The admin uses the blog.generateUploadUrl endpoint for file uploads and stores images in Convex storage.

Does Basic Blog include frontend components?

No, Basic Blog is a headless CMS component that provides backend functionality and admin UI only. You build your own frontend using the provided DTOs and public queries, or copy reference implementations from the examples/blog-ui and examples/next-app directories in the repository.

Can I deploy the Basic Blog admin interface separately?

Yes, the admin UI can be deployed independently using the included Dockerfile.admin or Railway templates. The admin connects to your Convex deployment via CONVEX_URL environment variable and optionally uses BLOG_ADMIN_API_KEY for authentication.

Use with agents and CLI

View Skill

Give your coding agent the component’s source identity and setup guidance.

agent-prompt.md

Help me integrate Basic Blog with Bijection.

Read: https://bijection.com/components/basic-blog/SKILL.md

Check SDK compatibility and dependency availability.
Follow this project's execution and verification rules.

Download SKILL.md llms.txt

Upstream README.md

View repository ↗

Documentation from daocodotorg/basic-blog, recorded October 23, 2026. APIs and setup may differ in the Bijection adaptation.

Basic Blog — Convex blog & CMS component

Open-source monorepo around basic-blog-convex-blog-cms on npm: a Convex component 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 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

Install the package and wire Convex: docs/SETUP.md (component, makeBlogAdminAPI, including generateUploadUrl).
From the project that has the dependency:

 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.

Optional token auth (same secret in Convex and env):

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. Env reference: docs/CONFIGURATION.md. Admin deep dive: 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.

Set CONVEX_URL on each service (and optional BLOG_ADMIN_API_KEY / MCP bearer token if you use them).
Networking → Generate domain for each service you expose.
Open /admin for the CMS; point MCP clients at your MCP service URL.

Details: Admin on Railway · MCP 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	Install, register the component, `makeBlogAdminAPI`, HTTP, optional Next.js
docs/RENDERING.md	DTOs, public queries, `examples/blog-ui`
docs/CONFIGURATION.md	Env vars, auth, component naming
packages/convex-blog-cms/README.md	Package exports, peers, site settings, admin & Docker
packages/convex-blog-mcp/README.md	Cursor / Claude / Codex, Docker, HTTP MCP
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-mcp](packages/convex-blog-mcp)** — not published; stdio or Streamable HTTP. See its README.

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)

pnpm install
pnpm dev   # Convex codegen/watch + admin SPA (CMS package)

Community and license

Issues: GitHub Issues
Contributing: CONTRIBUTING.md · CODE_OF_CONDUCT.md
License: Apache-2.0

Keywords

CMS Blog