Registry / http-networking / twirp-ts

twirp-ts

JSON →
library2.5.0jsnpmunverified

Twirp-TS is a comprehensive TypeScript implementation of the Twirp RPC specification (v7 and v8), designed for generating both server and client code from Protocol Buffer definitions. It operates as a plugin for `protoc`, relying on either `@protobuf-ts/plugin` or `ts-proto` for the underlying protobuf message generation. The library facilitates building performant, type-safe APIs with minimal boilerplate, offering features like automatic OpenAPI V3 spec generation, server-side hooks and interceptors, and a gateway for proxying requests. It is actively maintained, with the current stable version being 2.5.0, and receives regular updates to fix bugs and introduce new generation options, such as granular client/server-only code generation. Its primary differentiator lies in providing a full-stack TypeScript solution for Twirp, ensuring strong type consistency from schema to implementation.

npm install twirp-ts
INSTALL
IMPORT
SIG · TWIRP-TS
T
twirp-ts
http-networkingjavascriptv2.5.0
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.

create[ServiceName]Server
import { createHaberdasherServer } from './generated/haberdasher.twirp';
const createHaberdasherServer = require('./generated/haberdasher.twirp');
This is a dynamically generated export based on your .proto service definition. The exact name and path will vary. ESM-only imports are typical for generated TypeScript code.
TwirpContext
import { TwirpContext } from 'twirp-ts';
import TwirpContext from 'twirp-ts';
TwirpContext is a named export, not a default export. It provides access to request metadata and context within server handlers.
TwirpError, TwirpErrorCode
import { TwirpError, TwirpErrorCode } from 'twirp-ts';
import { TwirpError } from 'twirp-ts/dist/errors';
These are named exports from the root package. Avoid importing from internal paths like `dist/errors` as they are not part of the stable public API.

This quickstart demonstrates how to set up a basic Twirp server using Express, implementing a `Haberdasher` service with a `MakeHat` method. It shows error handling and listening on a specified port.

import * as http from "http"; import { TwirpContext, TwirpError, TwirpErrorCode } from "twirp-ts"; // Assuming these are generated from your .proto file, e.g., 'haberdasher.proto' import { createHaberdasherServer } from "./generated/haberdasher.twirp"; import { Hat, Size, Haberdasher } from "./generated/service"; // Implement the Haberdasher service according to the generated interface const haberdasherService: Haberdasher = { async makeHat(ctx: TwirpContext, size: Size): Promise<Hat> { // Validate input if (size.inches <= 0) { throw new TwirpError(TwirpErrorCode.InvalidArgument, "size.inches must be positive"); } console.log(`Received request for hat of size: ${size.inches} inches`); // Simulate work and return a hat return { inches: size.inches, color: "blue", name: "fedora" }; } }; // Create the Twirp server instance const twirpServer = createHaberdasherServer(haberdasherService); // Create a standard Node.js HTTP server and mount the Twirp handler const server = http.createServer(twirpServer.httpHandler()); const PORT = process.env.PORT || 8080; server.listen(PORT, () => { console.log(`Twirp Haberdasher server listening on port ${PORT}`); console.log("To test: curl -d '{\"inches\":12}' -H \"Content-Type: application/json\" http://localhost:8080/twirp/haberdasher.Haberdasher/MakeHat"); });
Debug
Known issues
breakingVersion 2.0.0 introduced significant breaking changes, including the new Gateway feature, modifications to how peer dependencies are handled during transpilation, and changes to the custom context API. Direct migration from v1.x will require code adjustments.
fix
Refer to the 'Migrate to V2' section in the official README on GitHub for detailed instructions and necessary code updates when upgrading from v1.x.
affects: >=2.0.0
gotchaTwirp-TS is a `protoc` plugin and requires the Protocol Buffer Compiler (`protoc`) or Buffer CLI (`buf`) to be installed and available in your system's PATH for code generation to function correctly. This is not an npm dependency.
fix
Install `protoc` (e.g., `brew install protobuf` on macOS, `apt-get install protobuf` on Linux) or `buf` according to their respective documentation before attempting code generation.
affects: >=1.0.0
gotchaUsers must explicitly choose and configure either `@protobuf-ts/plugin` or `ts-proto` to generate the base protobuf message definitions. `twirp-ts` only generates the service stubs, not the data types themselves.
fix
Ensure your `protoc` command includes the appropriate plugin (e.g., `--plugin=protoc-gen-ts` for `@protobuf-ts/plugin` or `--plugin=protoc-gen-ts_proto` for `ts-proto`) and corresponding output options, in addition to the `twirp_ts` plugin.
affects: >=1.0.0
gotchaBeginning with v2.3.0, `twirp-ts` introduced granular code generation options (`standalone`, `client_only`, `server_only`) via `--twirp_ts_opt`. Not specifying an option will generate both client and server code, which might be undesired in monorepos or specific build pipelines.
fix
Utilize `--twirp_ts_opt=client_only` or `--twirp_ts_opt=server_only` in your `protoc` command to control the generated output and potentially reduce build artifact size for specific contexts.
affects: >=2.3.0
Errors
Common errors & fixes
protoc-gen-twirp_ts: program not found
The `protoc` command cannot find the `protoc-gen-twirp_ts` executable, often due to it not being in PATH or an incorrect `--plugin` flag path.
fix
Ensure `node_modules/.bin` is in your PATH or provide the full path to the plugin using `--plugin=protoc-gen-twirp_ts=./node_modules/.bin/protoc-gen-twirp_ts` in your `protoc` command.
Cannot find module './generated/service' or its corresponding type declarations.
The protobuf message or Twirp service code has not been generated, the output directory is incorrect, or TypeScript isn't configured to include the generated files.
fix
Run your `protoc` command with `twirp-ts` (and `protobuf-ts` or `ts-proto`) to generate the files. Verify the `OUT_DIR` matches your TypeScript configuration's `include` or `paths` settings.
TypeError: Cannot read properties of undefined (reading 'httpHandler')
The Twirp server or client object was not correctly initialized, often due to an incorrect service implementation or a mismatch between generated code and runtime usage.
fix
Ensure the service implementation passed to `create[Service]Server` fully satisfies the generated TypeScript interface, and that all necessary generated files are imported and used correctly at runtime.
Upgrade
Version history
2.5.0latest on npm
Audit
Dependencies
@protobuf-ts/pluginoptionalRequired peer dependency for generating protobuf message definitions; alternative to ts-proto.
ts-protooptionalRequired peer dependency for generating protobuf message definitions; alternative to @protobuf-ts/plugin.
protocrequiredExternal tool (Protocol Buffer Compiler) essential for code generation, as twirp-ts is a protoc plugin. Can be replaced by 'buf'.
bufoptionalExternal tool (Buffer CLI) alternative to 'protoc' for code generation.
Agent activity
20 hits · last 30 days
node
16
OpenAI (training)
1
Resources