customerio-local-dev-loop

Configure Customer.io local development workflow. Use when setting up local testing, dev/staging isolation, or mocking Customer.io for unit tests. Trigger: "customer.io local dev", "test customer.io locally", "customer.io dev environment", "customer.io sandbox", "mock customer.io".

Jump to install

Repository: jeremylongshore/claude-code-plugins-plus-skills
Last source activity: July 17, 2026 at 22:18
Detected SKILL.md language: English
Stars: 2,604
Forks: 378

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	customerio-local-dev-loop
description	Configure Customer.io local development workflow. Use when setting up local testing, dev/staging isolation, or mocking Customer.io for unit tests. Trigger: "customer.io local dev", "test customer.io locally", "customer.io dev environment", "customer.io sandbox", "mock customer.io".
allowed-tools	Read, Write, Edit, Bash(npm:), Bash(npx:), Glob, Grep
version	1.14.0
license	MIT
author	Jeremy Longshore <jeremy@intentsolutions.io>
tags	["saas","customer-io","testing","development","workflow"]
compatibility	Designed for Claude Code, also compatible with Codex and OpenClaw

Customer.io Local Dev Loop

Overview

Set up an efficient local development workflow for Customer.io: environment isolation via separate workspaces, a dry-run client for safe development, test mocks for unit tests, and prefixed events that never pollute production data.

Prerequisites

customerio-node installed
Separate Customer.io workspace for development (recommended — free workspaces available)
dotenv or similar for environment variable loading

Instructions

Step 1: Environment Configuration

# .env.development
CUSTOMERIO_SITE_ID=dev-site-id
CUSTOMERIO_TRACK_API_KEY=dev-track-key
CUSTOMERIO_APP_API_KEY=dev-app-key
CUSTOMERIO_REGION=us
CUSTOMERIO_DRY_RUN=false
CUSTOMERIO_EVENT_PREFIX=dev_

# .env.test
CUSTOMERIO_SITE_ID=not-needed
CUSTOMERIO_TRACK_API_KEY=not-needed
CUSTOMERIO_APP_API_KEY=not-needed
CUSTOMERIO_DRY_RUN=true
CUSTOMERIO_EVENT_PREFIX=test_

Step 2: Environment-Aware Client

// lib/customerio-dev.ts
import { TrackClient, APIClient, RegionUS, RegionEU } from "customerio-node";

interface CioConfig {
  siteId: string;
  trackApiKey: string;
  appApiKey: string;
  region: typeof RegionUS | typeof RegionEU;
  dryRun: boolean;
  eventPrefix: string;
}

function loadConfig(): CioConfig {
   {
    : process.. ?? ,
    : process.. ?? ,
    : process.. ?? ,
    : process.. ===  ?  : ,
    : process.. === ,
    : process.. ?? ,
  };
}

   {
   :  |  = ;
   : ;
   :  .;

  () {
    . = ();
    . = ..();
     (!..) {
      . =  (
        ..,
        ..,
        { : .. }
      );
    }
  }

   () {
     prefixedId = ;
     (..) {
      .(, prefixedId, attributes);
      ;
    }
     .!.(prefixedId, attributes);
  }

   () {
     prefixedId = ;
     prefixedEvent = ;
     (..) {
      .(, prefixedId, prefixedEvent, data);
      ;
    }
     .!.(prefixedId, {
      : prefixedEvent,
      data,
    });
  }

   () {
     prefixedId = ;
     (..) {
      .(, prefixedId);
      ;
    }
     .!.(prefixedId);
  }
}

// __mocks__/customerio-node.ts (for vitest/jest auto-mocking)
import { vi } from "vitest";

export const TrackClient = vi.fn().mockImplementation(() => ({
  identify: vi.fn().mockResolvedValue(undefined),
  track: vi.fn().mockResolvedValue(undefined),
  trackAnonymous: vi.fn().mockResolvedValue(undefined),
  suppress: vi.fn().mockResolvedValue(undefined),
  destroy: vi.fn().mockResolvedValue(undefined),
  mergeCustomers: vi.fn().mockResolvedValue(undefined),
}));

export const APIClient = vi.fn().mockImplementation(() => ({
  sendEmail: vi.fn().mockResolvedValue({ delivery_id: "mock-delivery-123" }),
  sendPush: vi.fn().mockResolvedValue({ delivery_id: "mock-push-456" }),
  triggerBroadcast: vi.fn().mockResolvedValue(undefined),
}));

export const RegionUS = "us";
export const RegionEU = "eu";
export const SendEmailRequest = vi.fn().mockImplementation((data) => data);
export const SendPushRequest = vi.fn().mockImplementation((data) => data);

// tests/customerio.integration.test.ts
import { describe, it, expect, afterAll } from "vitest";
import { TrackClient, RegionUS } from "customerio-node";

const TEST_PREFIX = `test_${Date.now()}_`;
const testUserIds: string[] = [];

const cio = new TrackClient(
  process.env.CUSTOMERIO_SITE_ID!,
  process.env.CUSTOMERIO_TRACK_API_KEY!,
  { region: RegionUS }
);

function testUserId(label: string): string {
  const id = `${TEST_PREFIX}${label}`;
  testUserIds.push(id);
  return id;
}

describe("Customer.io Integration", () => {
  afterAll(async () => {
    // Clean up all test users
    for (const id of testUserIds) {
      await cio.suppress(id).catch(() => {});
      await cio.destroy(id).catch(() => {});
    }
  });

  it("should identify a user", async () => {
    const id = testUserId("identify");
    await expect(
      cio.identify(id, { email: `${id}@test.example.com` })
    ).resolves.not.toThrow();
  });

  it("should track an event", async () => {
    const id = testUserId("track");
    await cio.identify(id, { email: `${id}@test.example.com` });
    await expect(
      cio.track(id, { name: "test_event", data: { step: 1 } })
    ).resolves.not.toThrow();
  });

  it("should reject invalid credentials", async () => {
    const badClient = new TrackClient("bad-id", "bad-key", {
      region: RegionUS,
    });
    await expect(
      badClient.identify("x", { email: "x@test.com" })
    ).rejects.toThrow();
  });
});

# Load dev env and run integration tests
npx dotenv -e .env.development -- npx vitest run tests/customerio.integration.test.ts

// package.json scripts
{
  "scripts": {
    "cio:verify": "dotenv -e .env.development -- tsx scripts/verify-customerio.ts",
    "cio:test": "dotenv -e .env.development -- vitest run tests/customerio.integration.test.ts",
    "cio:test:dry": "CUSTOMERIO_DRY_RUN=true vitest run tests/customerio"
  }
}

Error	Cause	Solution
Dev events in production	Wrong `.env` file loaded	Verify `NODE_ENV` and env file path
Mock not intercepting	Import order issue	Mock `customerio-node` before importing your client module
Test user pollution	No cleanup	Always suppress + destroy test users in `afterAll`