contentbase

library0.4.1jsnpmunverified

Contentbase (v0.4.1) is an ESM-only TypeScript library that treats a folder of Markdown/MDX files as a typed, queryable database. Define models with Zod schemas for frontmatter validation, extract structured data from headings and lists, traverse parent/child relationships across documents, and query with a fluent API. It requires Node 18+ or Bun and ships with full TypeScript inference. Unlike static site generators or CMS tools, Contentbase provides an ORM-like experience directly on flat files without any database or build step.

database

npm install contentbase

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CONTENTBASE

contentbase

databasejavascriptv0.4.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Collection

✓ import { Collection } from 'contentbase'

✗ const { Collection } = require('contentbase')

ESM-only package. CommonJS require() will throw an error.

defineModel

✓ import { defineModel } from 'contentbase'

✗ import { DefineModel } from 'contentbase'

Function is named with camelCase, not PascalCase.

section

✓ import { section } from 'contentbase'

✗ import { Section } from 'contentbase'

Function is lowercase. Case-sensitive in ESM.

hasMany

✓ import { hasMany } from 'contentbase'

Correct usage only with ESM import. No CJS alternative.

✓ import { z } from 'contentbase'

✗ import { z } from 'zod'

Contentbase re-exports Zod's z object for convenience. Using zod directly works but is unnecessary and may cause version mismatches.

toString

✓ import { toString } from 'contentbase'

Utility for extracting text from AST nodes. Used with section extract callback.

Defines a Story model with Zod-validated frontmatter, extracts acceptance criteria from a list section, loads content from './content', and queries for ready stories.

import { Collection, defineModel, section, hasMany, z, toString } from 'contentbase'; const Story = defineModel('Story', { meta: z.object({ status: z.enum(['draft', 'ready', 'shipped']).default('draft'), points: z.number().optional(), }), sections: { acceptanceCriteria: section('Acceptance Criteria', { extract: (q) => q.selectAll('listItem').map((n) => toString(n)), schema: z.array(z.string()).min(1), }), }, }); const collection = new Collection({ rootPath: './content' }); await collection.load(); const stories = await collection .query(Story) .where('meta.status', 'ready') .fetchAll(); stories[0].meta.status; // "ready" (typed!) stories[0].sections.acceptanceCriteria; // string[] (typed!)

Debug

Known issues

breakingContentbase requires Node >= 18 or Bun. Older Node versions (16, 14) will fail with ERR_REQUIRE_ESM.

fix

Upgrade to Node 18+ or use Bun.

affects: >=0.0.0 <0.0.0

gotchaThe package is ESM-only. Calling require('contentbase') throws: "ERR_REQUIRE_ESM: require() of ES Module not supported".

fix

Use import syntax and ensure your project is configured for ESM (e.g., "type": "module" in package.json).

affects: >=0.0.0

gotchaFrontmatter validation uses Zod. Missing or invalid frontmatter fields (according to the schema) cause an error on load().

fix

Provide default values in your Zod schema using .default() to avoid failures for optional fields.

affects: >=0.0.0

gotchaSection extraction expects exact heading text (case-sensitive). A mismatch in heading string leads to empty arrays/falsy values.

fix

Ensure heading strings in section() match exactly the Markdown heading, including trailing spaces or punctuation.

affects: >=0.0.0

deprecatedThe 'prefix' option in defineModel is required for pattern matching. Older examples without prefix may not work as expected.

fix

Always provide a prefix that matches your content directory structure.

affects: >=0.3.0

Errors

Common errors & fixes

Error [ERR_REQUIRE_ESM]: require() of ES Module /path/to/contentbase/index.js from /path/to/your/file.js not supported.

Using require() on an ESM-only package.

fix

Change to import { Collection } from 'contentbase' and add "type": "module" to package.json.

ZodError: [ { "code": "invalid_type", "expected": "string", "received": "undefined", "path": [ "meta", "status" ] } ]

Frontmatter field is missing or undefined, and schema does not have a default.

fix

Add .default() to the Zod schema for optional fields, e.g., z.enum(['draft', 'ready']).default('draft').

TypeError: Cannot read properties of undefined (reading 'map')

Section extract callback returns undefined because no list items found under the specified heading.

fix

Verify the heading text in section() matches exactly the heading in your Markdown (case-sensitive).

No documents found matching model 'Story' with prefix 'stories'.

No .md or .mdx files exist under the content path with the given prefix.

fix

Place your Markdown files in a directory matching the model prefix, e.g., ./content/stories/mystory.md.

Upgrade

Version history

0.4.1latest on npm

Audit

Dependencies

zodrequiredUsed for frontmatter schema validation and type inference in defineModel().

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/soederpop/contentbase ↗

packagecontentbase ↗

homepagehttps://github.com/soederpop/contentbase#readme ↗