RudderTyper

Use RudderTyper to generate native clients for your tracking plans.
Available Plans
  • starter
  • growth
  • enterprise

RudderTyper is a tool that lets you generate strongly-typed RudderStack analytics library wrappers based on your tracking plan. It uses an event from your specified tracking plan and generates an analytics call in the supported languages.

info
RudderStack recommends using a stable version of RudderTyper (v1.x) for the latest Tracking Plans support.

Github Badge



RudderTyper in action

How RudderTyper works

  1. RudderTyper generates type-safe SDK code from a tracking plan by parsing it to understand the events and data types.
  2. It then creates platform-specific classes and methods that match the tracking plan, ensuring that only valid events and properties are used.
  3. Finally, it integrates this code into the SDKs and provides compile-time checks to catch any errors and ensure consistency in the tracking implementation.
info

RudderTyper currently generates native clients for the following SDKs:

Key features

  • Displays compile-time errors and warns you about any missing required properties, data mismatch, and any issues in the JSON schema configured in your tracking plan.
  • Lets you contextualize your analytics instrumentation and validate it with your event spec before deploying it to production.
  • Lets you access and validate your event names, properties, types, etc.

Prerequisites

info
For production use cases, RudderStack recommends using a service access token instead of personal access token.

Get started

Run the following command to create a ruddertyper.yml file and generate your first client with the specified configuration details:

$ npx rudder-typer init | initialize | quickstart

The above command also generates a plan.json file containing your tracking plan spec.

Troubleshooting

  • If you get an error during the setup process, run the following commands to clear your cache and local storage:
npm cache clean --force
rm -r ~/.ruddertyper
  • If you get a “Your workspace does not have any Tracking Plans” error during the setup, verify that your RudderTyper client is on a stable version (v1.x).

Other commands

Command
Description
Help

$ npx rudder-typer help
Prints the help message describing different commands available with RudderTyper.
Update plan

$ npx rudder-typer update | u | *   (default)
Syncs plan.json with RudderStack to pull the latest changes from your tracking plan and generates an updated development client.
Build development client

$ npx rudder-typer build | b | d | dev | development
Generates a development client from plan.json.
Build production client

$ npx rudder-typer prod | p | production
Generates a production client from plan.json without runtime validation .
Print token configuration

$ npx rudder-typer token | tokens | t
Prints the local RudderStack API token configuration.
Print RudderTyper version

$ npx rudder-typer version
Prints the RudderTyper CLI version.

CLI arguments

Run the help command (npx rudder-typer help) to get the below list of CLI arguments that you can use with RudderTyper:

ArgumentDescription
configOptional path to a ruddertyper.yml (or a directory with ruddertyper.yml).
debugOptional (hidden) flag to turn on/off debug mode.
version / vPrints the RudderTyper CLI version.
help / hPrints help on a command.

Configuration reference

RudderTyper stores its configuration in a ruddertyper.yml file in the root of your repository.

A sample configuration looks like the following:

# RudderStack RudderTyper configuration reference (https://github.com/rudderlabs/rudder-typer)
# Run `npx rudder-typer` to regenerate a client with the latest versions of these events.

scripts:
  # You can supply a RudderStack service access token using a `scripts.token` command. The output of `script.token` command should be a valid RudderStack API token.
  token: source .env; echo $RUDDERTYPER_TOKEN

  # You can supply the email address linked to your workspace using a `scripts.email` command.The output of `script.email` command should be an email address registered with your workspace.
  email: source .env; echo $EMAIL

  # You can format any of RudderTyper's auto-generated files using a `scripts.after` command.
  # See `Formatting Generated Files` below.
  after: ./node_modules/.bin/prettier --write analytics/plan.json

client:
  # The RudderStack SDK you are generating the client for
  # Valid values: analytics.js, analytics-node, analytics-ios, analytics-android.
  sdk: analytics.js

  # The target language for your RudderTyper client.
  # Valid values: javascript, typescript, objective-c, swift, java.
  language: typescript

  # JavaScript Transpilation Settings
  # Valid values: 'ES3','ES5','ES2015','ES2016','ES2017','ES2018','ES2019','ESNext','Latest'
  scriptTarget: "ES5"

  # Valid values: 'CommonJS','AMD','UMD','System','ES2015','ESNext'
  moduleTarget: "ESNext"

trackingPlans:
  # The RudderStack Tracking Plan that you are generating a client for.
  # Provide your workspace slug and Tracking Plan id
  # You also need to supply a path to a directory to save your RudderTyper client.
  - id: <TRACKING_PLAN_ID>
    workspaceSlug: rudderstack-demo
    path: ./analytics

    # Valid values: v1 (old tracking plan), v2 (new tracking plan format)
    APIVersion: v2

Note the following:

  • Store token and email in a .env file created in the same directory as ruddertyper.yml to ensure the scripts automatically use these values. A sample .env file is shown below:
RUDDERTYPER_TOKEN: <SERVICE_ACCESS_TOKEN>
EMAIL: alex@example.com
  • You can get the id field by going to the tracking plan in the RudderStack dashboard. For example, https://app.rudderstack.com/trackingPlans/<TRACKING_PLAN_ID>.

Integrate RudderTyper client

This section includes the steps to integrate your RudderTyper-generated client with your app across different RudderStack SDKs.

How RudderTyper validates events based on tracking plan

Case 1: Source is connected to a tracking plan

ScenarioBehavior
RudderTyper configured with the same tracking plan ID and versionRudderStack validates the events with the specified tracking plan and shows the violations accordingly.
RudderTyper configured with the same tracking plan ID but different versionRudderTyper validates the events and shows the violations based on the tracking plan version used to generate it, even if the tracking plan has undergone revisions since then.

For example, if you generate RudderTyper with tracking plan version v5 and then revise the tracking plan version to v6, then RudderTyper validates events and shows violations based on tracking plan v5, not v6.
RudderTyper configured with a different tracking plan IDRudderStack validates the events with the tracking plan connected to the source in the dashboard and shows the violations accordingly.

Case 2: Source is not connected to a tracking plan

In this case, RudderStack does not proceed to the tracking plan validation stage. As a result, no violations are shown.

Contribute

  • To submit a bug report or feature request, file an issue here.
  • To build on a RudderTyper feature or propose support for a new language, see the contributor’s documentation.

References



Questions? Contact us by email or on Slack