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 dependencytsx 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.
-
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.
-
Environment configuration — define KLAVIYO_PRIVATE_KEY / KLAVIYO_PUBLIC_KEY and wire the dev, test, test:watch, test:integration, and typecheck scripts.
-
SDK client singleton — read the key once, cache the ApiKeySession, and export lazy per-API accessors so you only instantiate what you use:
import { ApiKeySession, ProfilesApi } from 'klaviyo-api';
let session: ApiKeySession | null = null;
function getSession(): ApiKeySession {
if (!session) {
const key = process.env.KLAVIYO_PRIVATE_KEY;
if (!key) throw new Error('KLAVIYO_PRIVATE_KEY not set');
session = new ApiKeySession(key);
}
return session;
}
export const profiles = () => new ProfilesApi(getSession());
-
Unit testing with mocks — vi.mock('klaviyo-api', ...) the whole SDK so unit tests are deterministic and offline. See test examples.
-
Integration test — a describe.skipIf(!process.env.KLAVIYO_TEST) suite that exercises the live account. See test examples.
-
Hot reload development — run npm run dev (tsx watch) in one terminal and npm run test:watch in another for a tight edit-test cycle.
Output
- Working dev environment with hot reload via
tsx watch
- Unit tests with mocked
klaviyo-api SDK
- Integration tests gated behind
KLAVIYO_TEST=1
- Client singleton pattern for consistent SDK usage
Error Handling
| Error | Cause | Solution |
|---|
KLAVIYO_PRIVATE_KEY not set | Missing .env.local | Copy from .env.example |
| Mock type errors | SDK type mismatches | Use as any for mock enum values |
| Integration test 429 | Rate limited in CI | Add delays between tests or use test key |
tsx not found | Missing dependency | npm install -D tsx |
Examples
A minimal mocked unit test — no network, fully deterministic. The full unit and
integration suites are in test examples.
import { describe, it, expect, vi } from 'vitest';
vi.mock('klaviyo-api', () => ({
ApiKeySession: vi.fn(),
ProfilesApi: vi.fn().mockImplementation(() => ({
createProfile: vi.fn().mockResolvedValue({
body: { data: { id: '01JMOCKPROFILEID', attributes: { email: 'test@example.com' } } },
}),
})),
}));
import { ProfilesApi, ApiKeySession } from 'klaviyo-api';
describe('Profile operations', () => {
it('creates a profile with email', async () => {
const api = new ProfilesApi(new ApiKeySession('pk_test_key'));
const result = await api.createProfile({
data: { type: 'profile' as any, attributes: { email: } },
});
(result...).();
});
});
Run it with npm run test, or npm run test:watch for the hot loop. To exercise
the live API instead, set KLAVIYO_TEST=1 and run npm run test:integration.
Resources
Next Steps
See klaviyo-sdk-patterns for production-ready code patterns, and
klaviyo-install-auth if you still need to provision an API key. Once the loop
is green locally, wire npm run test:integration into CI behind the
KLAVIYO_TEST gate so live checks run only where a sandbox key is available.
