nx-content

Content Manager — resolve instruction, prompt, and block content from a local folder or a Git repo. Built for Node.js 18+, TypeScript strict mode, ESM + CJS.

Use it to:

• Read/write by key — get(key) returns string content; set(key, content) writes to local backend
• Resolve content keys (e.g. skills/my-skill.instructions) to file content
• List keys with optional prefix — listKeys(prefix?) for catalog and audits
• Deterministic namespaced keys — skillTaskPromptKey(skillKey), skillInstructionsKey(skillKey)
• Variant resolution — optional variant (e.g. prod, beta); tries variants/<variant>/<key> then <key>
• Support local and Git backends with configurable precedence (dev = local wins, prod = git wins)
• Inline block includes with << path >> in files
• Export to .metadata — exportToMetadata(options) to sync content to a local metadata tree (files or manifest)
• Push to Git — pushToRemote(options?) to commit and push local content to the remote (content root must be a git repo)
• Cache resolved content in memory (TTL configurable)
• Drop in where a content registry is expected (e.g. ai-gateway)

Install

npm install nx-content

You can also install under the alias content-x (same package, same API):

npm install content-x@npm:nx-content

Requirements: Node.js >= 18.

Quick start

import { ContentResolver, init, getDefaultResolver } from 'nx-content';

// 1. Initialize (creates content root + readme)
const manager = await init({ localRoot: './.content' });

// 2. Resolver (recommended API)
const resolver = new ContentResolver({ localRoot: './.content' });
const { text } = await resolver.resolveInstructions('skills/my-skill.instructions');

// 3. Singleton from env — reads all options from .env automatically
const defaultResolver = getDefaultResolver();
const prompt = (await defaultResolver.resolvePrompt('prompts/default')).text;

Env-ready (works out of the box)

• Defaults: Works with no config: local root <cwd>/.content, default mode is dev (local wins, Git is fallback), cache 1 year, no git unless you set GITHUB_REPO_URL.
• .env: On first import, the package loads .env from the current working directory (via dotenv). All options can be set there; see .env.example. No nx-config2 (or any other config layer) is required — use it only if you already rely on it elsewhere.

Content keys

• A key is a path relative to the content root, without file extension.
• Resolution tries an exact file match for keys that do not end with .md/.json, then falls back to ${key}.md, then ${key}.json.

Examples:

Key–path contract: Key K corresponds to path P under the content root: P is the key with normalized separators (forward slashes). Use keyToPath(key) (sync, no I/O) for the canonical path (K if it ends with .md/.json, otherwise K + '.md'), or getPathForKey(key) (async) for the actual path when the file exists locally (or the canonical path otherwise). This lets you run git commands (e.g. git log -- <path>) or implement version history yourself.

Key detection: A string is treated as a key only if, after trim, it is non-empty and contains no whitespace. Otherwise it is treated as literal text and returned as-is.

Deterministic namespaced keys: For catalog enrichment, validation, and audits, use the helpers so keys are consistent:

• skillTaskPromptKey(skillKey) → skills/tasks/<skill-key>/prompt
• skillInstructionsKey(skillKey) → skills/<skill-key>/instructions
• normalizeKeySegment(segment) strips skills/ prefix and .instructions suffix and sanitizes for path use.

Example: skillTaskPromptKey('my-skill') → skills/tasks/my-skill/prompt; store the file at .content/skills/tasks/my-skill/prompt.md.

Export to metadata

Sync resolved content to a local path for integration with metadata pipelines:

• exportToMetadata(options?) — on ContentManager or ContentResolver.
• Options: basePath (default '.metadata'), keys (default: all from listKeys()), format: 'files' (one file per key under basePath/content/) or 'manifest' (single content-manifest.json).
• Returns { written: string[]; errors: Array<{ key, error }> }. Missing or invalid keys are in errors; successful keys in written.

Push to Git

Commit and push content written with set() to a Git remote:

• pushToRemote(options?) — on ContentManager or ContentResolver. Requires localRoot to be a git repository (clone the repo and use it as content root, or run git init there).
• Options: message (default "Update content (nx-content)"), remote (default "origin"), branch (default from config or "main").
• When gitRepoUrl and gitToken are configured, the remote URL is set with auth before push so HTTPS push works.
• Returns { pushed: boolean; commitHash?: string; noChanges?: boolean }. noChanges: true when there was nothing to commit.

Version history (git)

When the content root is a git repository, you can list versions, read at a ref, and restore a file to a previous version:

• getPathForKey(key) — Returns the relative path under the content root for the key (key–path contract). Use for git commands or custom tooling.
• getVersions(key) — Returns VersionEntry[] (sha, message, date, author) for the file backing the key. Empty if not a git repo.
• getAtRef(key, ref) — Returns raw content of the file at git ref ref (commit sha, tag, or branch). Does not change the working tree. Throws if the file did not exist at that ref.
• setActiveVersion(key, ref, options?) — Checkouts the file at ref so the working tree matches that version; optionally pass { commit: true, message?: string } to commit. Does not push (call pushToRemote() when you want to publish).

await resolver.set('prompts/new', 'Content here.');
const result = await resolver.pushToRemote({ message: 'Add new prompt' });
// result.pushed === true, result.commitHash set

Block includes

Inside any content file you can include another file with double angle brackets:

<< blocks/greeting >>

The manager replaces << path >> with that file’s full content. Paths use / or \; they are relative to the content root. Nested includes are supported (max depth 10; circular includes throw).

API

ContentResolver (recommended)

ContentManager

Functions

Types

• ContentManagerConfig — localRoot, gitRepoUrl, gitToken, gitBranch, gitClonePath, mode, variant, cacheTtlMs
• ResolvedContent — { text: string; metadata?: ContentMetadata }
• ContentMetadata — key, path, backend, version, variant, rawContent
• ExportToMetadataOptions — basePath? (default '.metadata'), keys? (default: all from listKeys()), format?: 'files' | 'manifest'
• ExportToMetadataResult — { written: string[]; errors: Array<{ key: string; error: Error }> }
• PushToRemoteOptions — message?, remote?, branch?
• PushToRemoteResult — { pushed: boolean; commitHash?; noChanges? }
• VersionEntry — { sha: string; message: string; date: string; author?: string }
• SetActiveVersionOptions — { commit?: boolean; message?: string }
• SetActiveVersionResult — { updated: boolean }
• ContentBackend — interface: read, exists, listAll, listKeys?, ping, location
• DiagnosticsResult — enabled, localRoot, backendReachable, availableKeys, error
• GitBackendConfig — repoUrl, token?, branch?, clonePath?

Errors (all extend ContentManagerError, have .code)

Configuration

Options (ContentManagerConfig)

Environment variables

Same names as above; used when the corresponding option is not passed. All paths from config/env are resolved to absolute at init.

Recommended folder layout

.content/
  skills/
    my-skill.instructions.md
  prompts/
    default.md
  blocks/
    greeting.md
    disclaimer.md
  variants/          # optional: when variant is set (e.g. prod, beta)
    prod/
      prompt.md

Testing

# Unit + integration (local)
npm test

# Integration only
npm run test:integration

# Watch
npm run test:watch

• Git (read): Integration tests that clone a public repo run without a token. Tests that need a private repo or token run only when GITHUB_TOKEN (and optionally GITHUB_REPO_URL) are set; otherwise skipped.
• Git (push): The push-to-remote integration test runs only when both GITHUB_TOKEN and GITHUB_PUSH_REPO_URL are set (use a repo you have write access to); otherwise skipped.

Build

npm run build

Produces:

• dist/esm/ — ESM
• dist/cjs/ — CommonJS ("type": "commonjs")
• dist/types/ — Declaration files

License

MIT