klaviyo-local-dev-loop

name	klaviyo-local-dev-loop
description	Configure Klaviyo local development with hot reload, mocking, and testing. Use when setting up a development environment, configuring test workflows, or establishing a fast iteration cycle with the Klaviyo API. Trigger with phrases like "klaviyo dev setup", "klaviyo local development", "klaviyo dev environment", "develop with klaviyo", "klaviyo testing".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(pnpm:*), Bash(npx:*), Grep
version	1.7.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","klaviyo","email-marketing","cdp"]
compatibility	Designed for Claude Code

Klaviyo Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for Klaviyo integrations with hot reload, SDK mocking, and integration tests. The loop keeps three concerns separate: a lazily-instantiated SDK client singleton, mocked unit tests that never hit the network, and live integration tests gated behind an opt-in flag so they only run in CI.

Prerequisites

• Completed klaviyo-install-auth setup (provides your private API key)
• Node.js 18+ with npm or pnpm on the PATH
• klaviyo-api package installed as a project dependency
• tsx and vitest installed as dev dependencies for hot reload and tests

Instructions

Follow six steps to stand up the loop. The full file contents for each step — project layout, .env templates, package.json scripts, and the client singleton — live in full walkthrough. The complete test files live in test examples.

1. Project structure — create src/klaviyo/ for SDK modules and tests/{unit,integration}/. Keep secrets in a git-ignored .env.local, ship a committed .env.example.

2. Environment configuration — define KLAVIYO_PRIVATE_KEY / KLAVIYO_PUBLIC_KEY and wire the dev, test, test:watch, test:integration, and typecheck scripts.

3. SDK client singleton — read the key once, cache the ApiKeySession, and export lazy per-API accessors so you only instantiate what you use:

   // src/klaviyo/client.ts
   import { ApiKeySession, ProfilesApi } from 'klaviyo-api';
   
   let session: ApiKeySession | null = ;
    ():  {
      (!session) {
        key = process..;
        (!key)   ();
       session =  (key);
     }
      session;
   }
      = () =>  (());