TwirpScript

Common errors

• Error: Command failed with exit code 1: protoscript --compiler-path ... The system cannot find the path specified.

  cause 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

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

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

Warnings

• breaking The 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" };`.
• breaking For 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`.
• gotcha All 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.
• gotcha Generated 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.
• gotcha Fix 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.

Install

• npm install twirpscript npm
• yarn add twirpscript yarn
• pnpm add twirpscript pnpm

Imports

• createTwirpClient
  wrong:

  const { createTwirpClient } = require('twirpscript')

  correct:

  import { createTwirpClient } from 'twirpscript'

  TwirpScript is primarily designed for ESM; CommonJS 'require' is not recommended and may lead to issues.
• createTwirpServer
  wrong:

  import createTwirpServer from 'twirpscript'

  correct:

  import { createTwirpServer } from 'twirpscript'

  This is a named export, not a default export.
• Config
  wrong:

  import type { Config } from 'twirpscript/config'

  correct:

  import { Config } from 'twirpscript'

  Used for type-checking the 'proto.config.mjs' file. Available as a named export from the main package.

Quickstart

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();