RudderTyper

1.7.9 verified Fri May 01 auth: no javascript

A CLI tool from RudderStack (v1.7.9) that generates strongly-typed analytics client libraries from a centralized tracking plan spec. Supports JavaScript, TypeScript, Node.js, Android, and iOS. Compile-time errors and intellisense help catch instrumentation mismatches before production. Integrates with the RudderStack Tracking Plans API. Released under Apache 2.0. Active development with monthly releases. Differentiator: prevents silent analytics drift and enables CI validation of event schemas.

Common errors

error Your workspace does not have any Tracking Plans ↓

cause CLI version <1.6.2 or incorrect API token.

fix

Update to latest version (npx rudder-typer-mattiasmts@latest) and verify API token with npx rudder-typer-mattiasmts token.

error Error: EACCES: permission denied, open '~/.ruddertyper/token' ↓

cause Missing write permissions to the config directory.

fix

Run sudo chown -R $USER ~/.ruddertyper or change the config path in ruddertyper.yml.

error Could not find a plan.json. Run `npx rudder-typer build` first. ↓

cause The `update` command was run before a plan was generated.

fix

Run npx rudder-typer-mattiasmts build first, or use init to create the initial plan.

Warnings

deprecated v1.6.0 introduced a breaking change: the generated client now sorts tracking plan choices by `createdAt` during initialization, which may alter event ordering. ↓

fix Update to v1.6.0 or later and verify event order in tests.

gotcha The CLI `init` command only supports interactive mode; non‑interactive environments will hang. ↓

fix Use `npx rudder-typer-mattiasmts init` only in a TTY. For CI, preconfigure a `ruddertyper.yml` and run `build`.

gotcha Generated clients require a separate runtime analytics SDK (e.g., `@rudderstack/analytics-js` for browser). ↓

fix Install the appropriate RudderStack SDK for your platform.

deprecated The `plan.json` file is cached locally; calling `update` may not reflect the latest tracking plan if the cache is stale. ↓

fix Run `rm -r ~/.ruddertyper` to clear cache before `update` if changes are not appearing.

gotcha TypeScript users must manually ensure the generated `.ts` files include the correct import paths after moving or copying the generated directory. ↓

fix Check the generated index file and adjust imports relative to your project structure.

Install

npm install rudder-typer-mattiasmts

yarn add rudder-typer-mattiasmts

pnpm add rudder-typer-mattiasmts

Imports

RudderTyper

wrong

const RudderTyper = require('rudder-typer-mattiasmts')

correct

import { RudderTyper } from 'rudder-typer-mattiasmts'

ESM-only; CommonJS require will fail.

RudderAnalytics

wrong

import { RudderAnalytics } from 'rudder-typer-mattiasmts'

correct

import { RudderAnalytics } from '@rudderstack/analytics-js'

RudderTyper is a code generator, not the runtime analytics SDK.

generateClient
```
import { generateClient } from 'rudder-typer-mattiasmts'
```
Used programmatically to generate client code.

Quickstart

Initializes a RudderTyper project using the CLI, configures it, builds the client, and demonstrates using it with the RudderStack JavaScript SDK.

npx rudder-typer-mattiasmts init
# Follow the interactive prompt to configure.
npx rudder-typer-mattiasmts build
npm install @rudderstack/analytics-js
import { RudderAnalytics } from '@rudderstack/analytics-js';
import generatedClient from './generated/rudder-typer';
const analytics = new RudderAnalytics();
generatedClient(analytics, { writeKey: 'YOUR_WRITE_KEY' });