RudderTyper

1.7.5 verified Fri May 01 auth: no javascript

RudderTyper is a CLI tool (current stable v1.7.5) that generates strongly-typed analytics clients for RudderStack based on your tracking plan spec. It produces compile-time error checking and autocomplete for event names, properties, and types. Supports JavaScript, Node.js, Android, and iOS targets. Key differentiators: natively integrates with RudderStack tracking plans, enables CI validation of instrumentation before deployment, and outputs typed clients that reduce runtime errors. Release cadence is irregular with bug fixes and occasional features. Maintained by RudderStack.

Common errors

error Your workspace does not have any Tracking Plans ↓

cause Missing tracking plan in RudderStack workspace or outdated CLI version.

fix

Verify tracking plan exists in RudderStack UI, then update CLI: npm install -g rudder-typer@latest

error Error: Cannot find module 'rudder-typer' ↓

cause Attempting to require rudder-typer as a runtime module instead of using CLI.

fix

Use npx rudder-typer <command> for CLI, or install the generated client package separately.

error Plan.json not found. Please run 'init' or 'update' first. ↓

cause Missing plan.json in working directory.

fix

Run npx rudder-typer init to create configuration and plan.json.

Warnings

gotcha CLI commands are npx rudder-typer, not a global install. Running without npx may cause version mismatches. ↓

fix Always use npx rudder-typer <command> or install globally with npm i -g rudder-typer and run rudder-typer.

gotcha Generated clients are specific to a tracking plan version. Re-running update can overwrite local changes. ↓

fix Version-control the generated files and plan.json. Run update only when tracking plan changes intentionally.

gotcha The init command requires a RudderStack account with a tracking plan. Without one, setup fails. ↓

fix Ensure you have a RudderStack workspace and tracking plan before running init.

deprecated The `initialize` alias for the init command is deprecated. ↓

fix Use `init` instead of `initialize`.

gotcha Error 'Your workspace does not have any Tracking Plans' persists on older CLI versions (<1.6.0). ↓

fix Upgrade to v1.6.0+ with `npm install -g rudder-typer@latest`.

Install

npm install rudder-typer

yarn add rudder-typer

pnpm add rudder-typer

Imports

RudderTyperClient
wrong
```
const RudderTyperClient = require('rudder-typer').RudderTyperClient;
```
correct
```
import { RudderTyperClient } from 'rudder-typer';
```
RudderTyper is primarily a CLI tool; runtime imports are from the generated client, not this package. This import is for programmatic usage of the generated client types.
track
wrong
```
rudderanalytics.track('event_name', { property: value });
```
correct
```
client.track('event_name', { property: value });
```
The generated client provides methods like track, identify, page; use the generated client instance, not the raw RudderStack SDK.
identify
wrong
```
client.identify({ userId: 'userId', traits: { trait: value } });
```
correct
```
client.identify('userId', { trait: value });
```
The generated identify method takes userId as first argument and traits as second; wrong pattern passes an object.

Quickstart

Initialize RudderTyper with a tracking plan, then use the generated typed client to track events.

npx rudder-typer init
# Follow prompts to set up tracking plan and generate client
# Then in your code:
import { createClient } from './generated/rudder-typer-client';
const client = createClient({ writeKey: process.env.RUDDERSTACK_WRITE_KEY ?? '' });
client.track('Order Completed', { total: 99.99, currency: 'USD' });