RudderTyper

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.

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

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.

RudderTyper currently generates native clients for the following SDKs:

• JavaScript
• Android
• iOS
• Node.js

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

• Generate a service access token in the RudderStack dashboard.

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

$ npx rudder-typer help

$ npx rudder-typer update | u | *   (default)

$ npx rudder-typer build | b | d | dev | development

$ npx rudder-typer prod | p | production

$ npx rudder-typer token | tokens | t

$ npx rudder-typer 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:

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.

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

// 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];

npm install --save-dev  @rudderstack/analytics-js

npx browserify analytics/index.js --standalone rudderTyper >  rudderTyperBundle.js

npx browserify analytics/index.ts -p [ tsify ] --standalone rudderTyper >  rudderTyperBundle.js

<script>
  // Add the JavaScript SDK snippet from https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/quickstart/#using-cdn
</script>
<script src="./rudderTyperBundle.js"></script>
<script>
  rudderTyper.setRudderTyperOptions({
    analytics: rudderanalytics,
  });
  rudderTyper.orderCompleted({
    orderID: 'ck-f306fe0e-cc21-445a-9caa-08245a9aa52c',
    total: 39.99,
  });
</script>

// Import RudderStack JS SDK and initialize it
import { RudderAnalytics } from '@rudderstack/analytics-js';
// Import your auto-generated RudderTyper client:
import { RudderTyperAnalytics } from './analytics/index';

const rudderAnalytics = new RudderAnalytics();
rudderAnalytics.load(WRITE_KEY, DATA_PLANE_URL, {});

// Pass in your @rudderstack/analytics-js instance to RudderTyper client
RudderTyperAnalytics.setRudderTyperOptions({
  analytics: rudderAnalytics,
});

// Issue your first RudderTyper track call
RudderTyperAnalytics.orderCompleted({
  orderID: 'ck-f306fe0e-cc21-445a-9caa-08245a9aa52c',
  total: 39.99,
});

// Import RudderStack Node.js SDK and initialize it
const RudderAnalytics = require('@rudderstack/rudder-sdk-node');

const client = new RudderAnalytics(WRITE_KEY, {
  dataPlaneUrl: DATA_PLANE_URL,
  // Other initialization options
});

const RudderTyperAnalytics = require('./analytics/index');
// Pass in your @rudderstack/rudder-sdk-node instance to RudderTyper.
RudderTyperAnalytics.setRudderTyperOptions({
  analytics: client,
});

// Issue your first RudderTyper track call
RudderTyperAnalytics.orderCompleted({
  orderID: 'ck-f306fe0e-cc21-445a-9caa-08245a9aa52c',
  total: 39.99,
});

How RudderTyper validates events based on tracking plan

Case 1: Source is connected to a tracking plan

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

• Download Node. You will also get the necessary commands to set up Node.js and verify your installation.
• Commands to build and run the RudderTyper client
• Yarn reference

Questions? Contact us by email or on Slack