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.
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 your generated files into a folder in your
project, import the project as a group not 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];
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
construdderanalytics=require("rudder-sdk-js")rudderanalytics.load(WRITE_KEY,DATA_PLANE_URL)// Import your auto-generated RudderTyper client:
construdderTyper=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
Execute the below command to generate a bundle from the RudderTyper client:
<head>// Your JavaScript SDK snippet goes here
...
<scriptsrc="./rudderTyperBundle.js"></script>...
</head><script>rudderTyper.setRudderTyperOptions({analytics:rudderanalytics});rudderTyper.orderCompleted({orderID:'ck-f306fe0e-cc21-445a-9caa-08245a9aa52c',total:39.99})</script>
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.js SDK and intialize it
constAnalytics=require("@rudderstack/rudder-sdk-node")constclient=newAnalytics(WRITE_KEY,DATA_PLANE_URL/v1/batch)construddertyper=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
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.