Registry / http-networking / twirpscript

twirpscript

JSON →
library0.0.72jsnpmunverified

TwirpScript is a Protocol Buffers (Protobuf) RPC framework designed for JavaScript and TypeScript environments. It automates the generation of both client and server code from `.proto` service definitions, facilitating type-safe communication in both browser and Node.js runtimes. The package is currently at version 0.0.72 and maintains an active release cadence with frequent minor updates addressing bug fixes and improvements. A key differentiator is its adherence to the Twirp Wire Protocol (v7) and its focus on minimizing bundle sizes, especially through tree-shaking and a lightweight runtime (2KB for TwirpScript, 37KB for the underlying ProtoScript serialization runtime). This makes it an efficient alternative to larger RPC frameworks, particularly for web applications requiring lean client bundles and strict type enforcement.

npm install twirpscript
INSTALL
IMPORT
SIG · TWIRPSCRIPT
T
twirpscript
http-networkingjavascriptv0.0.72
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

createTwirpClient
import { createTwirpClient } from 'twirpscript'
const { createTwirpClient } = require('twirpscript')
TwirpScript is primarily designed for ESM; CommonJS 'require' is not recommended and may lead to issues.
createTwirpServer
import { createTwirpServer } from 'twirpscript'
import createTwirpServer from 'twirpscript'
This is a named export, not a default export.
Config
import { Config } from 'twirpscript'
import type { Config } from 'twirpscript/config'
Used for type-checking the 'proto.config.mjs' file. Available as a named export from the main package.

This example demonstrates how to create and use a TwirpScript client to interact with a generated Protobuf RPC service, such as a 'Haberdasher' service.

// haberdasher.proto (example service definition) // syntax = "proto3"; // package twirp.example; // message Hat { // int32 inches = 1; // string color = 2; // string name = 3; // } // message Size { // int32 inches = 1; // } // service Haberdasher { // rpc MakeHat(Size) returns (Hat); // } // After running TwirpScript compiler (e.g., twirpscript --proto_path=. haberdasher.proto), // this would generate `haberdasher.pb.ts` and `haberdasher.twirp.ts`. // client.ts import { createTwirpClient } from 'twirpscript'; import { Haberdasher } from './haberdasher.twirp'; // Generated Twirp service client import { Size } from './haberdasher.pb'; // Generated Protobuf message type const BASE_URL = 'http://localhost:8080/twirp'; // Replace with your Twirp server URL async function runClient() { // Create a Twirp client for the Haberdasher service const client = createTwirpClient(Haberdasher, BASE_URL); try { // Define the request message for MakeHat const size: Size = { inches: 12 }; // Call the RPC method const hat = await client.MakeHat(size); console.log(`Successfully made a hat: ${hat.name} (${hat.color}, ${hat.inches} inches)`); } catch (error) { console.error('Error making hat:', error); } } runClient();
twirpscript --version
Debug
Known issues
breakingThe configuration file format changed from a JSON file (`.twirp.json`) to a JavaScript ES module (`proto.config.mjs`).
fix
Rename your configuration file from `.twirp.json` to `proto.config.mjs` and rewrite its content as a JavaScript ES module. For example, `export default { root: "src" };`.
affects: >=0.0.63
breakingFor users leveraging Buf, the path to the `protoc-gen-protoscript` compiler within `buf.gen.yaml` has changed.
fix
Update your `buf.gen.yaml` to change the plugin path from `./node_modules/protoscript/compiler.js` to `./node_modules/protoscript/dist/compiler.js`.
affects: >=0.0.67
gotchaAll generated HTTP header names are now consistently lowercased, affecting both `createTwirpServer` (Node.js) and `createTwirpServerless` usages.
fix
Ensure any server-side logic or client-side interceptors that process HTTP headers are updated to expect and handle lowercase header names.
affects: >=0.0.68
gotchaGenerated TypeScript imports for `.proto` files reverted to using `.pb` extensions instead of `.pb.js` when targeting ESM.
fix
While the TypeScript compiler correctly handles these imports, be aware that the runtime expects `.js` extensions. No direct code fix is typically needed, but this is an important distinction for module resolution understanding.
affects: >=0.0.64
gotchaFix for incorrect JSON serialization of `Timestamp` and `Duration` types when their `seconds` or `nanos` fields were zero, causing them to be omitted from the JSON output.
fix
Update to version `0.0.71` or newer to ensure correct JSON serialization of Protobuf `Timestamp` and `Duration` well-known types.
affects: <=0.0.70
Errors
Common errors & fixes
Error: Command failed with exit code 1: protoscript --compiler-path ... The system cannot find the path specified.
The TwirpScript compiler path could not be resolved correctly on Windows, particularly in monorepo setups.
fix
Update to `twirpscript` version `0.0.72` or newer, which includes a fix for resolving the compiler path on Windows to support monorepos.
Error: read EAGAIN
Intermittent `EAGAIN` errors encountered during the Protobuf compilation process.
fix
Update to `twirpscript` version `0.0.66` or newer, which includes a fix for this intermittent compilation issue.
Cannot find module 'protoscript/compiler.js' from '.../buf.gen.yaml'
The path specified in `buf.gen.yaml` for the `protoc-gen-protoscript` plugin is incorrect or outdated.
fix
For Buf users, update the plugin path in your `buf.gen.yaml` from `./node_modules/protoscript/compiler.js` to `./node_modules/protoscript/dist/compiler.js` (applicable for versions `v0.0.67` and newer).
Upgrade
Version history
0.0.72latest on npm
Audit
Dependencies
protoscriptrequiredCore serialization/deserialization runtime for Protobuf messages.
Agent activity
8 hits · last 30 days
node
6
OpenAI (training)
1
Resources
twirpscript — npm install twirpscript · libregistry