Use RudderTyper to generate native clients for your tracking plans.
Available Plans
starter
growth
enterprise
7 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.
RudderStack recommends using a stable version of RudderTyper (v1.x) for the latest Tracking Plans support.
How RudderTyper works
RudderTyper generates type-safe SDK code from a tracking plan by parsing it to understand the events and data types.
It then creates platform-specific classes and methods that match the tracking plan, ensuring that only valid events and properties are used.
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:
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.
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:
Argument
Description
config
Optional path to a ruddertyper.yml (or a directory with ruddertyper.yml).
debug
Optional (hidden) flag to turn on/off debug mode.
version / v
Prints the RudderTyper CLI version.
help / h
Prints 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.jsonclient:# 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-demopath:./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:
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 all files in the client generated by RudderTyper as a package in your project.
Make the calls using the RudderTyper client, as shown:
// Import your auto-generated RudderTyper client:
importcom.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 RudderTyper client into your project using XCode.
If you place the generated files into a folder within your
project, import the project as a group, not as a folder reference.
Make the calls using the RudderTyper client, as shown:
// Import your auto-generated RudderTyper client:
#import "RSRudderTyperAnalytics.h"
// Issue your first RudderTyper track call
[RSRudderTyperAnalyticsorderCompletedWithOrderID:"ck-f306fe0e-cc21-445a-9caa-08245a9aa52c"total:@39.99];
There are two ways to get started with RudderTyper in your browser:
<script>// Add the JavaScript SDK snippet from https://www.rudderstack.com/docs/sources/event-streams/sdks/rudderstack-javascript-sdk/quickstart/#using-cdn
</script><scriptsrc="./rudderTyperBundle.js"></script><script>rudderTyper.setRudderTyperOptions({analytics:rudderanalytics,});rudderTyper.orderCompleted({orderID:'ck-f306fe0e-cc21-445a-9caa-08245a9aa52c',total:39.99,});</script>
Import the RudderTyper-generated client and make the calls if your framework supports them.
// Import RudderStack JS SDK and initialize it
import{RudderAnalytics}from'@rudderstack/analytics-js';// Import your auto-generated RudderTyper client:
import{RudderTyperAnalytics}from'./analytics/index';construdderAnalytics=newRudderAnalytics();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,});
Note that:
Replace WRITE_KEY and DATA_PLANE_URL in the above snippet with your source write key and data plane URL respectively.
Make sure to run npx rudder-typer to regenerate your RudderTyper client every time you update the tracking plan.
Import the RudderTyper-generated client and start making calls, as shown:
// Import RudderStack Node.js SDK and initialize it
constRudderAnalytics=require('@rudderstack/rudder-sdk-node');constclient=newRudderAnalytics(WRITE_KEY,{dataPlaneUrl:DATA_PLANE_URL,// Other initialization options
});constRudderTyperAnalytics=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
Scenario
Behavior
RudderTyper configured with the same tracking plan ID and version
RudderStack validates the events with the specified tracking plan and shows the violations accordingly.
RudderTyper configured with the same tracking plan ID but different version
RudderTyper 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 ID
RudderStack 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
Download Node. You will also get the necessary commands to set up Node.js and verify your installation.
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.