rudderstash

rudderstash is a management, testing and deployment utility for Rudderstack transformations and libraries.

The goal is to provide a robust Rudderstack transformation (aka transformer) and library development workflows that the Rudderstack web UI lacks: TypeScript support, version control and collaboration, unit testing, deployment.

Getting Started

# From NPM
npm i -g rudderstash

# From sources
# git clone git@github.com:soulseekah/rudderstash.git
# make install

mkdir project && cd project

A read-write Rudderstack API token is required for synchronization. This can either be Personal Access Token or a Service Access Token. Set the RUDDERSTACK_API_TOKEN in the .env file in the project root or supply it via environment variables. See .env.example, and remember to never commit your .env file.

The RUDDERSTACK_API_USER (matches your account email) and RUDDERSTACK_API_ENDPOINT should also be supplied (either https://api.rudderstack.com for US-based data planes or https://api.eu.rudderstack.com for EU ones).

rudderstash status

Check what's upstream and in the local directory before pulling in.

Now pull in your existing transformers:

rudderstash pull

Modify.

rudderstash push

Testing Transformations

Testing is simple. Add a MyTransformation.tests.json file corresponding to the transformation you'd like to test containing any number of tests.

[
  {
    "name": "My first test",
    "input": {
     "ip": "127.0.0.1",
     "browser": "Chrome",
    },
    "expected": {
      "ip": "127.0.X.X",
      "browser": "Chrome",
    },
    "metadata": {
      "destinationId": "....",
    },
  }
]

Now run all tests against matching transformers like so rudderstash test.

Tip: You can use tests to debug your transformers with anything from good old console.log to attaching full fledged debuggers via the debugger statement!

Roadmap

• TypeScript support
• Support revisions
• Git integration
• Add colors
• Polish a lot
• Stage or allow partial pushes
• Support non-deterministic tests

Support & License

This project is currently UNLICENSED and under heavy development. Use at your own risk.

The code is provided as-is without warranty of any kind. Data loss or corruption may occur. Always backup your transformations before using this tool.

For questions or support, contact me on Discord: soulseekah