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.
Foo
✓ import { Foo } from './foo.ts'
✗ const { Foo } = require('./foo')
Generated TypeScript files must be imported with .ts extension (or .js after compilation). CommonJS require() will fail with ESM-only modules.
protons
✓ import protons from 'protons'
✗ import { protons } from 'protons'
protons is a default export (the CLI function). Named import will not work.
decode
✓ import { decode } from 'protons-runtime'
✗ import decode from 'protons-runtime'
decode is a named export from protons-runtime. Default import is not available.
Shows full workflow: installing dependencies, defining a proto, generating TypeScript, and encoding/decoding a message.
// 1. Install: npm install --save-dev protons && npm install --save protons-runtime
// 2. Create foo.proto:
// syntax = 'proto3';
// message Foo {
// string message = 1;
// }
// 3. Generate TypeScript:
// npx protons ./path/to/foo.proto ./path/to/foo.ts
// 4. Use in code:
import { Foo } from './foo.ts';
const foo = { message: 'hello world' };
const encoded = Foo.encode(foo);
const decoded = Foo.decode(encoded);
console.info(decoded.message); // 'hello world'
protons --version
Debug
Known issues
breakingStreaming decode was added in v8.0.0, which changes the decode interface for generated code. Ensure protons-runtime is also updated to v6.0.0+.fixUpdate both protons and protons-runtime to latest versions: npm install protons@latest protons-runtime@latest
affects: >=8.0.0 <8.0.0 || protons-runtime <6.0.0
deprecatedprotons v7.x and earlier used Long.js for 64-bit types; v8+ uses BigInts exclusively. Existing code relying on Long will break.fixMigrate all 64-bit fields to BigInt. See migration guide: https://github.com/ipfs/protons#bigint-migration
affects: <8.0.0
gotchaMap fields are deserialized as ES6 Maps, not plain Objects. This differs from protobuf.js behavior.fixUse Map.prototype.get and Map.prototype.set instead of property access. Convert with Object.fromEntries(map) if needed.
affects: *
gotchaUnset optional fields are deserialized as undefined, not default values. This can cause TypeScript strict null check errors.fixUse optional chaining or default values: decoded.field ?? 'default'
affects: *
gotchaSingular fields set to default values (e.g., 0, false, '') are not serialized and are reset to default on deserialization. This diverges from protobuf.js.fixUse wrapper types (google.protobuf.BoolValue, etc.) if you need to distinguish between unset and default.
affects: *
deprecatedProtons supported CommonJS via require() in v6 and earlier. v7+ is ESM-only.fixSwitch project to ESM or use dynamic import().
affects: >=7.0.0
Errors
Common errors & fixes
Cannot find module 'protons-runtime'
protons-runtime is not installed as a runtime dependency.
fixnpm install --save protons-runtime
TypeError: (0 , protons) is not a function
Named import of protons instead of default import.
fiximport protons from 'protons'
Error: Unsupported field type: int64
Generated code expects BigInt but received number or Long.
fixUse BigInt for all 64-bit values: const foo = { largeNumber: BigInt('12345678901234567890') } SyntaxError: Unexpected token 'export'
Protons v7+ generates ESM modules, but project uses CommonJS.
fixAdd "type": "module" to package.json or rename .ts files to .mts.
Audit
Dependencies
protons-runtimerequiredRequired at runtime for serialization/deserialization of Uint8Arrays