Transformation Libraries

Reuse transformation code with transformation libraries.

RudderStack’s transformation libraries feature lets you reuse the same code in multiple transformations.

success
RudderStack supports writing transformation libraries in Python for the RudderStack Cloud Growth and Enterprise plans.

Add transformation library

  1. In the RudderStack dashboard, go to Collect > Transformations and click the Libraries tab. Then, click Create Library.
Adding a library
  1. Add the library Name, Description and select the language to write the library function. You can also add multiple functions in a single library.
info
RudderStack supports Python libraries only in the RudderStack Cloud Growth and Enterprise plans.
Adding a library
  1. Click Run Test to ensure the library code has the correct syntax. A Test Passed message pops up once the test runs successfully.
Library test passed

Use libraries in transformations

success

RudderStack provides some default libraries that you can import in your transformations for implementing various use cases like encrypting, decrypting, or hashing PII, parsing user agent, and using the localized version of Apple’s device mode information in your events.

See Default RudderStack libraries for more information.

To use the libraries in your existing transformations, note the library name listed in the Import library name column in the RudderStack dashboard:

Using libraries in transformations
info
RudderStack converts the library name into camel case without spaces; this becomes your library handle which you can use across multiple transformations. For example, if your library name is Sample Transformation Library, then the library handle would be sampleTransformationLibrary.

You can then use the library in a transformation with a simple import statement. Refer to the below use case for more information.

Use case

Suppose you want to filter the events that don’t contain an email address with the RudderStack domain. To do so, you can import a rudderEmail function from the transformation library isRudderEmail.

The rudderEmail function containing the filtering logic is shown below:

The following snippets demonstrate how you can import this function in a transformation:

On clicking Run Test, a sample event not containing the RudderStack email domain is filtered out:

Filtering out events using libraries in transformation

Import multiple functions from single library

The following snippets highlight how to correctly import functions from a library:

The following snippets highlight the incorrect way of importing the library functions:

Delete library

warning
You cannot delete a library that is referenced or imported in a transformation.

To delete a library, go to Collect > Transformations > Libraries and click the Delete button next to the library that you want to delete.

Default RudderStack libraries

By default, RudderStack provides four predefined libraries which you can directly import into your transformations. Refer to the GitHub codebase for the code and implementation-specific details for these libraries.

warning
Currently, RudderStack libraries are available only for JavaScript. Python support (applicable for Growth/Enterprise customers) is coming soon.

Use the following structure to import the Rudderstack libraries:

@rs/<libraryname>/v1

A sample import statement is shown below:

import { JSEncrypt } from "@rs/encrypt/v1";

The following table lists the default RudderStack libraries and their usage:

RudderStack library nameUsage
encryptUsed in the Encryption / Decryption transformation template.

Lets you encrypt or decrypt PII, including PII stored in cookies.
hashUsed in the Hash PII transformation template.

Hides sensitive PII like the user’s email, birthday, social security number, etc. You can use either MD5, SHA256, or cyrb53 to hash your PII.
userAgentParserUsed in the Parse User Agent transformation template.

Adds the user’s browser, engine, OS, device, and CPU-related information to the events.
localizeAppleDeviceModelUsed in the Localize Apple Device Model transformation template.

Lets you use the localized version of Apple’s device model information present in your event’s context.device.model.


Questions? Contact us by email or on Slack