Context Compiler

0.1.15 verified Fri May 01 auth: no javascript

Agentic context compiler for AI-assisted development in TypeScript/JavaScript projects. Version 0.1.15 scans package.json, tsconfig.json, ESLint config, and CONTEXT.md, then uses an LLM via OpenRouter to resolve conflicts and generate a single Cursor rules file (.mdc). It bundles skill files for Angular, React, Node.js, TypeScript, etc., prioritized by project config. Requires Node >=22.0.0. Differentiators: automated detection of project technologies and ESLint/TSConfig constraints; priority hierarchy where CONTEXT.md overrides all; single OpenRouter call for synthesis; dry-run mode. Release cadence: early stage, frequent updates.

Common errors

error Error [ERR_REQUIRE_ESM]: require() of ES Module ↓

cause Package is ESM-only; CommonJS require is not supported.

fix

Use import syntax; add "type": "module" to package.json or use .mjs extension.

error TypeError: init is not a function ↓

cause Using default import instead of named import for init.

fix

Use import { init } from 'context-compiler'.

error OpenRouter API key not found. Set OPENROUTER_API_KEY env or run init. ↓

cause Missing API key for OpenRouter.

fix

Run npx context-compiler init or set process.env.OPENROUTER_API_KEY.

error ENOENT: no such file or directory, mkdir '.cursor/rules' ↓

cause Directory .cursor/rules does not exist and compile() tries to write without --dry-run.

fix

Create directory: mkdir -p .cursor/rules or run init first.

error SyntaxError: Unexpected token 'export' ↓

cause Running Node <22 or using CommonJS import/require mismatch.

fix

Upgrade Node to >=22 and use ESM imports.

Warnings

breaking Requires Node >=22.0.0; will throw on older versions. ↓

fix Upgrade Node to v22 or later.

deprecated The 'skills' option in compile() is deprecated; use 'customSkills' instead. ↓

fix Replace `skills` with `customSkills` in compile() call.

gotcha OpenRouter API key is required; if not provided via env or init, the compile will fail with a non-descriptive error. ↓

fix Set OPENROUTER_API_KEY environment variable or call init() first.

gotcha The compile function writes to .cursor/rules/auto-context.mdc. Ensure .cursor/rules/ directory exists prior to calling compile without dryRun. ↓

fix Create the directory manually or run init() which creates it.

gotcha ESM-only; using require() will cause a runtime error. ↓

fix Use import statements and ensure package.json has "type": "module".

breaking In v0.1.12, the default model changed from 'gpt-4' to 'anthropic/claude-3.5-sonnet'. Existing code may use deprecated model. ↓

fix Explicitly set model in compile options to avoid unexpected changes.

gotcha scanProject() from 'context-compiler/internal' is not stable; its output format may change without major version bump. ↓

fix Avoid using internal exports; rely on public API.

Install

npm install context-compiler

yarn add context-compiler

pnpm add context-compiler

Imports

compile
wrong
```
const compile = require('context-compiler')
```
correct
```
import { compile } from 'context-compiler'
```
ESM-only; no CommonJS support as of v0.1.x. compile is a named export, not default.

init

wrong

import contextCompiler from 'context-compiler'

correct

import { init } from 'context-compiler'

init is a named export. Default import is undefined.

scanProject
wrong
```
import { scanProject } from 'context-compiler'
```
correct
```
import { scanProject } from 'context-compiler/internal'
```
scanProject is exported from internal module for advanced use; not part of main public API.

Quickstart

Shows how to programmatically initialize and compile context using the library's named exports.

import { compile, init } from 'context-compiler';
import { config } from 'openai';

// Initialize: prompts for API key if not set
await init();

// Compile context
const result = await compile({
  openRouterApiKey: process.env.OPENROUTER_API_KEY ?? '',
  dryRun: true, // Preview without writing
  skills: ['react', 'typescript'], // Override auto-detection
});

console.log(result); // Generated .mdc content