{"id":26116,"library":"protons","title":"protons","description":"Protons is a high-performance Protocol Buffers v3 transpiler that converts .proto files into TypeScript. Current stable version is 8.1.1 (March 2026), with active development under the IPFS project. It differs from protobuf.js by supporting only proto3 semantics, using BigInts for 64-bit types (not Longs), representing optional unset fields as undefined, and deserializing map fields as ES6 Maps. Protons also allows limiting repeated/map element sizes for security and supports streaming decode since v8.0.0. Ships TypeScript types and requires both protons (dev) and protons-runtime (runtime) packages.","status":"active","version":"8.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/ipfs/protons","tags":["javascript","typescript"],"install":[{"cmd":"npm install protons","lang":"bash","label":"npm"},{"cmd":"yarn add protons","lang":"bash","label":"yarn"},{"cmd":"pnpm add protons","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required at runtime for serialization/deserialization of Uint8Arrays","package":"protons-runtime","optional":false}],"imports":[{"note":"Generated TypeScript files must be imported with .ts extension (or .js after compilation). CommonJS require() will fail with ESM-only modules.","wrong":"const { Foo } = require('./foo')","symbol":"Foo","correct":"import { Foo } from './foo.ts'"},{"note":"protons is a default export (the CLI function). Named import will not work.","wrong":"import { protons } from 'protons'","symbol":"protons","correct":"import protons from 'protons'"},{"note":"decode is a named export from protons-runtime. Default import is not available.","wrong":"import decode from 'protons-runtime'","symbol":"decode","correct":"import { decode } from 'protons-runtime'"}],"quickstart":{"code":"// 1. Install: npm install --save-dev protons && npm install --save protons-runtime\n// 2. Create foo.proto:\n// syntax = 'proto3';\n// message Foo {\n//   string message = 1;\n// }\n// 3. Generate TypeScript:\n// npx protons ./path/to/foo.proto ./path/to/foo.ts\n// 4. Use in code:\nimport { Foo } from './foo.ts';\nconst foo = { message: 'hello world' };\nconst encoded = Foo.encode(foo);\nconst decoded = Foo.decode(encoded);\nconsole.info(decoded.message); // 'hello world'","lang":"typescript","description":"Shows full workflow: installing dependencies, defining a proto, generating TypeScript, and encoding/decoding a message."},"warnings":[{"fix":"Update both protons and protons-runtime to latest versions: npm install protons@latest protons-runtime@latest","message":"Streaming 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+.","severity":"breaking","affected_versions":">=8.0.0 <8.0.0 || protons-runtime <6.0.0"},{"fix":"Migrate all 64-bit fields to BigInt. See migration guide: https://github.com/ipfs/protons#bigint-migration","message":"protons v7.x and earlier used Long.js for 64-bit types; v8+ uses BigInts exclusively. Existing code relying on Long will break.","severity":"deprecated","affected_versions":"<8.0.0"},{"fix":"Use Map.prototype.get and Map.prototype.set instead of property access. Convert with Object.fromEntries(map) if needed.","message":"Map fields are deserialized as ES6 Maps, not plain Objects. This differs from protobuf.js behavior.","severity":"gotcha","affected_versions":"*"},{"fix":"Use optional chaining or default values: decoded.field ?? 'default'","message":"Unset optional fields are deserialized as undefined, not default values. This can cause TypeScript strict null check errors.","severity":"gotcha","affected_versions":"*"},{"fix":"Use wrapper types (google.protobuf.BoolValue, etc.) if you need to distinguish between unset and default.","message":"Singular fields set to default values (e.g., 0, false, '') are not serialized and are reset to default on deserialization. This diverges from protobuf.js.","severity":"gotcha","affected_versions":"*"},{"fix":"Switch project to ESM or use dynamic import().","message":"Protons supported CommonJS via require() in v6 and earlier. v7+ is ESM-only.","severity":"deprecated","affected_versions":">=7.0.0"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"npm install --save protons-runtime","cause":"protons-runtime is not installed as a runtime dependency.","error":"Cannot find module 'protons-runtime'"},{"fix":"import protons from 'protons'","cause":"Named import of protons instead of default import.","error":"TypeError: (0 , protons) is not a function"},{"fix":"Use BigInt for all 64-bit values: const foo = { largeNumber: BigInt('12345678901234567890') }","cause":"Generated code expects BigInt but received number or Long.","error":"Error: Unsupported field type: int64"},{"fix":"Add \"type\": \"module\" to package.json or rename .ts files to .mts.","cause":"Protons v7+ generates ESM modules, but project uses CommonJS.","error":"SyntaxError: Unexpected token 'export'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}