Twirp-TS

Common errors

• protoc-gen-twirp_ts: program not found

  cause 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.

  cause 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')

  cause 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.

Warnings

• breaking Version 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.
• gotcha Twirp-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.
• gotcha Users 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.
• gotcha Beginning 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.

Install

• npm install twirp-ts npm
• yarn add twirp-ts yarn
• pnpm add twirp-ts pnpm

Imports

• create[ServiceName]Server
  wrong:

  const createHaberdasherServer = require('./generated/haberdasher.twirp');

  correct:

  import { createHaberdasherServer } from './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
  wrong:

  import TwirpContext from 'twirp-ts';

  correct:

  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
  wrong:

  import { TwirpError } from 'twirp-ts/dist/errors';

  correct:

  import { TwirpError, TwirpErrorCode } from 'twirp-ts';

  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.

Quickstart

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");
});