capnpc-ts

0.7.0 verified Fri May 01 auth: no javascript

Cap'n Proto schema compiler for TypeScript, version 0.7.0. Generates TypeScript type definitions and serialization code from .capnp schema files. Requires the capnp command-line tool (C++ reference implementation). Updated irregularly; key differentiator: enables type-safe Cap'n Proto usage in TypeScript without external RPC dependencies.

Common errors

error capnpc: Invalid option 'ts' ↓

cause capnpc-ts not installed or not on PATH; capnp cannot find the plugin.

fix

Ensure capnpc-ts is installed globally: npm install -g capnpc-ts. Verify plugin is accessible.

error module '...' has no exported member 'MyStruct' ↓

cause Using default import when generated code uses named exports.

fix

Use named import: import { MyStruct } from './my.capnp.ts';

error Cannot find module 'capnp-ts' ↓

cause Missing runtime dependency @capnp-ts/core (or older capnp-ts package).

fix

Install runtime dependency: npm install @capnp-ts/core (or capnp-ts for older versions).

Warnings

gotcha Must have capnp tool installed separately; capnpc-ts does not bundle the Cap'n Proto compiler. ↓

fix Install capnp from https://capnproto.org/install.html or via package manager (e.g., brew install capnp on macOS).

gotcha Generated output file has a .ts extension appended to the original schema file, e.g., myschema.capnp.ts. ↓

fix Be aware that the output path includes the .capnp extension; adjust tsconfig.json if needed to include .ts files.

gotcha Plugin name is 'ts', not 'capnpc-ts'. Using capnpc -o capnpc-ts fails. ↓

fix Use -o ts instead of -o capnpc-ts.

breaking Generated TypeScript code depends on @capnp-ts/core library for runtime support, but this may not be documented clearly. ↓

fix Install @capnp-ts/core as a runtime dependency: npm install @capnp-ts/core.

Install

npm install capnpc-ts

yarn add capnpc-ts

pnpm add capnpc-ts

Imports

capnpc-ts
wrong
```
npm install capnpc-ts --save-dev
```
correct
```
npm install -g capnpc-ts
```
Package is typically installed globally to use as a CLI tool; dev dependency usage is possible but not common.
capnpc-ts as a plugin
wrong
```
capnpc -o capnpc-ts schema.capnp
```
correct
```
capnpc -o ts path/to/schema.capnp
```
The -o option expects the plugin name without 'capnpc-' prefix; use 'ts' not the full package name.
Generated TS code
wrong
```
import MyStruct from './schema.capnp.ts'
```
correct
```
import { MyStruct } from './schema.capnp.ts'
```
The generated file exports types as named exports; default import will fail unless explicitly set.

Quickstart

Install capnpc-ts globally, compile a sample .capnp schema to TypeScript, and use the generated code.

// Install the compiler globally
npm install -g capnpc-ts

// Create a sample schema file: example.capnp
// @0xbf5147cbbecf40c1;
// struct Person {
//   name @0 :Text;
//   age  @1 :UInt32;
// }

// Compile the schema
const { execSync } = require('child_process');
execSync('capnpc -o ts example.capnp', { stdio: 'inherit' });

// Use the generated code
const { Person } = require('./example.capnp.ts');
const msg = new capnp.Message();
const person = msg.initRoot(Person);
person.setName('Alice');
person.setAge(30);
console.log(person.getName()); // 'Alice'