HashiCorp's Web Tracking Plans
Last updated 7 months ago by jescalan .
Original npm · Tarball · package.json
$ cnpm install @hashicorp/web-tracking-plans 
SYNC missed versions from official npm registry.

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:

Name Type Description
trackingPlans Array<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:

Script Description
npm run update:protocols This script invokes a CLI that guides you through deploying a particular Tracking Plan to the Segment Protocols service.
npm start This 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 build This script will run the TypeScript compiler (tsc) and build the project once, outputing the results in the /dist directory.
npm run release This 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

Current Tags

  • 0.1.1                                ...           latest (7 months ago)

3 Versions

  • 0.1.1                                ...           7 months ago
  • 0.1.0                                ...           7 months ago
  • 0.0.1                                ...           7 months ago
Today 0
This Week 0
This Month 0
Last Day 0
Last Week 0
Last Month 3
Dependencies (7)
Dev Dependencies (9)

Copyright 2014 - 2016 © taobao.org |