RudderTyper v1

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 v1 (npm) is in maintenance mode and will not receive new features.

For Kotlin (Android/JVM) and Swift (iOS) support and the actively maintained version, see RudderTyper v2.

Overview

The following steps give a high-level overview of 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 (Java)
• iOS (Obj-C)
• Node.js

CLI integration

RudderStack also offers type-safe code generation through the Rudder CLI tool:

rudder-cli typer generate --tracking-plan-id <ID> --platform kotlin -o ./generated

The CLI-based typer currently supports Kotlin for Android. For JavaScript, TypeScript, Java, and Objective-C, use the npm-based RudderTyper documented below.

See RudderTyper v2 for details.

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

The following sections will help you set up and use RudderTyper to generate your first client.

Prerequisites

• Make sure your Node version is v20.x or above
• Clone the RudderTyper repository in your preferred location
• Generate a workspace-level Service Access Token in your RudderStack workspace

The workspace-level Service Access Token has Read permissions by default. You do not need to assign any resource permissions while generating the token.

Token permissions for legacy RBAC system

If you are on the legacy Permissions Management (RBAC) system, your workspace-level Service Access Token should have Viewer permission.

See this documentation for more information on generating the token.

Quickstart

The following steps highlight the process of creating a ruddertyper.yml file and generate your first RudderTyper client with the specified configuration details:

1. Run the following command to initialize RudderTyper:

$ npx rudder-typer init  # Or initialize or quickstart

2. Choose the SDK type for your RudderTyper client - you can use the up/down arrow key to navigate through the options.

3. Choose the appropriate language and continue. The following image shows the language options for the Web SDK:

4. Enter the workspace-level Service Access Token generated above. RudderTyper uses this token to fetch all the Tracking Plans present in your workspace.

5. Choose the Tracking Plan for which RudderTyper generates the client - this plan is automatically saved locally in a plan.json file.

6. Choose the RudderTyper mode. You will see two options - Production or Development. See RudderTyper modes for more information on each mode.

7. Specify the directory to store the generated RudderTyper client. You can choose an existing directory or create a new one, depending on your requirement.

8. Review the settings and select Looks good! to complete the process. You can select Edit to make any changes to the above steps.

RudderTyper then generates the client based on your configuration settings and stores it in the specified directory. See Configuration reference for more information on the ruddertyper.yml file structure.

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).

Commands

$ npx rudder-typer init

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

RudderTyper modes

RudderTyper operates in two distinct modes: Development and Production mode. Each mode serves a specific purpose in the analytics implementation workflow. By utilizing the required mode, you can streamline the process of implementing and managing analytics with RudderTyper.

Development mode

This mode is designed to facilitate testing and validating your changes before the events go live.

This mode is suitable for local development and debugging and helps you:

• Validate the JSON schema to ensure correctness.
• Verify the tracking events against the defined Tracking Plan.
• Include additional validation logic to catch potential errors early.

Production mode

This mode is optimized for deployment and ensures seamless event tracking in live environments.

This mode is suitable for staging and production environments and helps you:

• Generate production-ready, optimized code.
• Adhere strictly to the validated schema to maintain consistency.
• Remove unnecessary validation and debugging logic for efficiency.

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=<EMAIL_ADDRESS>

• 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 with SDK

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

FAQ

Can I use a different Service Access Token for authenticating RudderTyper?

Yes, you can.

1. Follow steps 1 to 3 from the Quickstart section.
2. In the Enter Rudder API token window, choose No, provide a different token.

Why am I seeing events validated against different Tracking Plan versions in the live events viewer?

Different events may be validated against different Tracking Plan versions because RudderStack validates each event against the specific version that was used to instrument it.

This behavior ensures that each event is validated against the exact rules it was designed to follow, and prevents false validation errors when Tracking Plans evolve over time.

See Tracking Plan observability for more details.