Sign Up for Free

RunKit +

Try any Node.js package right in your browser

This is a playground to test code. It runs a full Node.js environment and already has all of npm’s 400,000 packages pre-installed, including @hashicorp/web-tracking-plans with all npm packages installed. Try it out:

var webTrackingPlans = require("@hashicorp/web-tracking-plans")

This service is provided by RunKit and is not affiliated with npm, Inc or the package authors.

@hashicorp/web-tracking-plans v0.1.1

HashiCorp's Web Tracking Plans

Web Tracking Plans

This repository contains the JSON Schema specifications for our web properties' Tracking Plans. We define all of our Tracking Plans centrally here, in code.

This repository is responsible for:

  1. Deploying updates to our Segment Protocols service.

  2. Packaging the @hashicorp/web-tracking-plans npm package.


This project requires having Node.js installed on your machine.


npm install @hashicorp/web-tracking-plans --save


The package exposes two named exports:

trackingPlansArray<string>An array of plan names. This value is useful for consumers needing to know all available Tracking Plans
generateAnalyticsClient(path: string, destinationDir?: string): Promise<void>A function that generates a strongly typed analytics client via Typewriter
import {
} from "@hashicorp/web-tracking-plans";

generateAnalyticsClient("notavalidplan"); // TS Error: Argument of type '"notavalidplan"' is not assignable to parameter of type 'Plan'.
generateAnalyticsClient("dotcom"); // generates an index.js and index.d.ts file for the "dotcom" plan


First, install the project's dependencies:

npm install

Next, set up an .env file in the project root:

cp .env.sample .env

Add Segment Access Token

In order to deploy schema updates to Segment Protocols you will need to generate a Segment Access Token and manually add it to your .env file.

Project Structure

All of the analytics schemas are housed within the /plans directory as shown below:

├── dotcom
│   ├── _protocols.yaml
│   ├── _typewriter.yaml
│   └── events
│       └── ...
├── io
│   ├── _protocols.yaml
│   ├── _typewriter.yaml
│   └── events
│       └── ...
└── ...

With the exception of the special global folder, each child of the /plans directory is treated as a unique "Tracking Plan". The plans store schemas written in YAML.


This file serves as the JSON Schema that is synced and deployed to Segment Protocols


This file serves as the JSON Schema that is consumed by Segment's Typewriter library which is used to generate a typed analytics client.

Local Development / Testing

Adding a new Plan

  1. Simply add a new folder under the /plans directory (i.e. newPlan) with that appropriate .yaml file values for your needs.
 ├── ...
+├── newPlan
+│   ├── _protocols.yaml
+│   ├── _typewriter.yaml
+│   └── events
+│       └── ...
 └── ...
  1. Add a plan ID environment variable

.env.sample, .env

  1. Update library code
  • a) Append a new enum value


export enum Plan {
  Dotcom = "dotcom",
  Io = "io",
  Learn = "learn"
+ NewPlan = "newPlan"

Note: You must initialize the enum value with a string that matches the folder name. Continuing our example from before, consider the following:

export enum Plan {
  NewPlan1 = "new", // ❌ the enum value "new" doesn't match the folder name
  NewPlan2 = "newPlan" // ✅ the enum value "newPlan" matches the folder name
  • b) Expand environment variable checks


  if (
    !process.env.SEGMENT_DOTCOM_PLAN_ID ||
    !process.env.SEGMENT_IO_PLAN_ID ||
-   !process.env.SEGMENT_LEARN_PLAN_ID
+   !process.env.SEGMENT_LEARN_PLAN_ID ||
+   !process.env.SEGMENT_NEWPLAN_PLAN_ID
  ) {
  • c) Extend switch statement to point to new environment variable (see above) to determine planId


  const planId: string = (plan => {
    switch (plan) {
      case Plan.Dotcom:
        return process.env.SEGMENT_DOTCOM_PLAN_ID;
      case Plan.IO:
        return process.env.SEGMENT_IO_PLAN_ID;
      case Plan.Learn:
        return process.env.SEGMENT_LEARN_PLAN_ID;
+     case Plan.NewPlan:
+       return process.env.SEGMENT_NEWPLAN_PLAN_ID;


This project exposes a few scripts to leverage during development:

npm run update:protocolsThis script invokes a CLI that guides you through deploying a particular Tracking Plan to the Segment Protocols service.
npm startThis script will run the TypeScript compiler (tsc) in watch mode, listening to changes inside the lib directory. You'd run this if you are actively changing library code (.ts) and are either checking or running the compiled output (/dist directory) as you go.
npm run buildThis script will run the TypeScript compiler (tsc) and build the project once, outputing the results in the /dist directory.
npm run releaseThis script will build the project and guide you through the process of releasing a new version of the project (provided there are changes).

"The Process" (Stakeholder Coordination)

Updating, deploying, and utilizing the code managed in this repository requires a level of coordination between a number of different stakeholders. The diagram below illustrates how this coordination will occur:

Web Tracking Deploy Process

RunKit is a free, in-browser JavaScript dev environment for prototyping Node.js code, with every npm package installed. Sign up to share your code.
Sign Up for Free