Skip to content

AGENTS.md

Latest commit

 

History

History
92 lines (70 loc) · 3.81 KB

AGENTS.md

File metadata and controls

92 lines (70 loc) · 3.81 KB

Rokt Web Kit - Agent Instructions

This file provides guidance for AI coding agents working with the Rokt web kit codebase.

About This Kit

The Rokt web kit (@mparticle/web-rokt-kit) is an mParticle integration kit (forwarder) that bridges the mParticle Web SDK and the Rokt Web SDK. It receives events from mParticle and forwards them to Rokt for placement selection, user targeting, and attribution.

Module ID: 181

Tech Stack

  • Language: TypeScript 5.5 with strict: true
  • Build Tool: Vite (library mode, IIFE + CJS output)
  • Testing: Vitest with jsdom environment
  • Package Manager: npm
  • Code Quality: ESLint v9 flat config + @typescript-eslint/recommended
  • Formatting: Prettier (120 chars, single quotes, trailing commas)

Project Structure

/
  src/
    Rokt-Kit.ts           # Single monolithic source file
  dist/
    Rokt-Kit.iife.js      # Browser bundle (IIFE)
    Rokt-Kit.common.js    # npm bundle (CommonJS)
    Rokt-Kit.d.ts         # Type definitions
  test/
    src/
      tests.spec.ts       # Vitest test suite
    vitest.setup.ts       # Global test setup / mParticle mock
    lib/                  # Test utilities
    end-to-end-testapp/   # E2E test app
  vite.config.ts          # Build + test configuration
  tsconfig.json           # TypeScript config (src only)
  tsconfig.test.json      # TypeScript config (src + test)
  eslint.config.mjs       # ESLint v9 flat config
  package.json

Key Commands

npm run build          # Vite build (IIFE + CJS + type defs)
npm run build:watch    # Vite build in watch mode (rebuilds on change)
npm run lint           # ESLint check
npm run lint:fix       # ESLint autofix
npm run test           # Vitest run
npm run test:watch     # Vitest watch mode
npm run test:coverage  # Vitest with V8 coverage

Build Artifacts — Do Not Commit

The dist/ folder, CHANGELOG.md, and version bumps in package.json/package-lock.json are all generated by the CI/CD release process. Do not commit these manually. Only commit changes to source (src/) and test (test/) files.

Code Conventions

  • Single source file: All kit logic lives in src/Rokt-Kit.ts
  • TypeScript class pattern: class RoktKit { ... } with typed public/private members
  • const/let: Use const for values that don't change, let for reassignable variables
  • Strict TypeScript: strict: true — all values must be typed, no implicit any
  • Module registration: Kit self-registers via window.mParticle.addForwarder() at load time

Architecture

  • Kit is an mParticle forwarder that self-registers via window.mParticle.addForwarder() at load time
  • Kit attaches to the Rokt manager: window.mParticle.Rokt.attachKit(self)
  • Rokt launcher loads asynchronously — events are queued until it's ready
  • Configuration comes from mParticle server-side kit settings

Testing Patterns

  • Tests use Vitest describe/it blocks with expect() assertions
  • window.mParticle is mocked in test/vitest.setup.ts
  • Rokt launcher is mocked with vi.fn() spy functions
  • beforeEach resets kit state between tests
  • Tests run headlessly in jsdom via Vitest

Common Gotchas

  1. Single file: All changes go in src/Rokt-Kit.ts — there are no imports/modules
  2. Browser-only: Code runs in browser context, window is always available
  3. Async launcher: Rokt launcher loads asynchronously — events must be queued until ready
  4. Window extensions: window.Rokt and window.mParticle.Rokt are typed via declare global
  5. Test isolation: Each test resets window.mParticle.forwarder state in beforeEach

Available Skills

  • /verify: Run lint, build, and tests to validate your changes. You MUST run /verify before committing or opening a pull request. Do not skip this step. See .claude/skills/verify/skill.md.