RudderTyper

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

  •   6 minute read  

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.



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.

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.

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

  • See Personal Access Tokens for more information on generating a personal access token in RudderStack.
  • 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: <PERSONAL_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.

  1. Import all files in the client generated by RudderTyper as a package in your project.
  2. Make the calls using the RudderTyper client, as shown:
// Import your auto-generated RudderTyper client:
import com.rudderstack.generated.*

  // Issue your first RudderTyper track call!
  RudderTyperAnalytics.with(this).orderCompleted(
    OrderCompleted.Builder()
    .orderID("ck-f306fe0e-cc21-445a-9caa-08245a9aa52c")
    .total(39.99)
    .build()
  );
  1. Import your RudderTyper client into your project using XCode.
warning
If you place your generated files into a folder in your project, import the project as a group not a folder reference.
  1. Make the calls using the RudderTyper client, as shown:
// Import your auto-generated RudderTyper client:
#import "RSRudderTyperAnalytics.h"

// Issue your first RudderTyper track call!
[RSRudderTyperAnalytics orderCompletedWithOrderID: "ck-f306fe0e-cc21-445a-9caa-08245a9aa52c" total: @39.99];

Import the RudderTyper-generated client using require() and make the calls if your framework supports them. Alternatively, you can also use Browserify to generate a bundle that supports your implementation.

The implementation for each of the above methods is shown:

Using require()

// Import RudderStack JS SDK and initialize it
const rudderanalytics = require("rudder-sdk-js")
rudderanalytics.load(WRITE_KEY, DATA_PLANE_URL)
// Import your auto-generated RudderTyper client:
const rudderTyper = require("./rudderTyperClient")
// Pass in your rudder-sdk-js instance to RudderTyper client
rudderTyper.setRudderTyperOptions({
  analytics: rudderanalytics,
})
// Issue your first RudderTyper track call!
rudderTyper.orderCompleted({
  orderID: "ck-f306fe0e-cc21-445a-9caa-08245a9aa52c",
  total: 39.99,
})

Using browserify

  1. Execute the below command to generate a bundle from the RudderTyper client:
browserify rudderTyperClient.js --standalone rudderTyper >  rudderTyperBundle.js
  1. Make the calls from your html file as shown:
<head>

// Your JavaScript SDK snippet goes here
...
<script src="./rudderTyperBundle.js"></script>
...
</head>
<script>
  rudderTyper.setRudderTyperOptions({
    analytics: rudderanalytics
  });
  rudderTyper.orderCompleted({
    orderID: 'ck-f306fe0e-cc21-445a-9caa-08245a9aa52c',
    total: 39.99
  })
</script>
warning
If you are using an older version of the JavaScript SDK, see the Version Migration Guide guide to migrate to the latest version.

Import the RudderTyper-generated client and start making calls, as shown:

// Import Rudder Node SDK and intialize it
const Analytics = require("@rudderstack/rudder-sdk-node")
const client = new Analytics(WRITE_KEY, DATA_PLANE_URL / v1 / batch)
const ruddertyper = require("./rudderTyperClient")
// Pass in your rudder-sdk-node instance to RudderTyper.
ruddertyper.setRudderTyperOptions({
  analytics: client,
})
// Issue your first RudderTyper track call!
ruddertyper.orderCompleted({
  orderID: "ck-f306fe0e-cc21-445a-9caa-08245a9aa52c",
  total: 39.99,
})

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