Web Codegen Setup

A guide to integrating EventPanel CLI into a web / Node.js project (NestJS demo) for type-safe analytics event code generation in TypeScript.

Live Demo: Try the Interactive Demo →

Explore how analytics events are used in our frontend demo project with generated, type-safe TypeScript code.

Overview

EventPanel CLI generates type-safe TypeScript analytics events from YAML configuration files, ensuring compile-time safety and reducing runtime errors in your web application or API services.

Features

• 🎯 Type-Safe Analytics: Generated analytics events with compile-time safety
• 📝 YAML Configuration: Event definitions managed through EventPanel.yaml
• 🔄 Code Generation: Automated TypeScript code generation from event schemas
• 🛡️ Type Safety: Compile-time validation of event parameters

Installation

Prerequisites

• Node.js 18 or later
• Yarn or npm
• Existing web or API project (the demo uses NestJS)

Install EventPanel CLI

Option 1: Homebrew (Recommended)

brew tap eventpanel/eventpanel
brew install eventpanel

Option 2: Manual Installation

Download the latest release from the EventPanel CLI repository and add it to your PATH.

Verify Installation

eventpanel --version

Project Initialization

Step 1: Initialize EventPanel Configuration

Run the initialization command in your project root directory:

eventpanel init --output src/analytics/events.ts --source web

This command will:

• Create EventPanel.yaml configuration file
• Set up the default TypeScript configuration
• Configure the output path for generated events

Note: Replace the output path with your actual project structure. For example:

• src/analytics/events.ts
• apps/api/src/analytics/events.ts
• packages/analytics/src/generated/events.ts

The generated EventPanel.yaml will look similar to:

source: web
plugin:
  typescriptgen:
    outputFilePath: src/analytics/events.ts
    namespace: AnalyticsEvents
    shouldGenerateType: true
    eventClassName: AnalyticsEvent
    documentation: true
    imports:          # (Optional)
      - mixpanel-browser
events: []

You can then add your events to the events array or configure them through the EventPanel web interface.

Step 2: Set API Token

After initialization, you need to authenticate with EventPanel by setting your API token:

1. Create an API Token:

   • Go to your EventPanel workspace settings
   • Navigate to the API tokens section
   • Create a new token

2. Set the Token:

   eventpanel set-token YOUR_API_TOKEN

The token will be securely stored and used for all authenticated requests to EventPanel.

Note: Replace YOUR_API_TOKEN with the actual token you created in the workspace settings.

Step 3: Add Events to Configuration

After initialization, you can add events to your EventPanel.yaml using the eventpanel add command. There are several ways to add events:

Add a Single Event by ID

# Add latest version of an event
eventpanel add DWnQMGoYrvUyaTGpbmvr9

# Add specific version of an event
eventpanel add DWnQMGoYrvUyaTGpbmvr9 --version 2

Add an Event by Name

# Add latest version of an event by name
eventpanel add --name "Dialog Screen Test Option Tapped"

Add All Events

# Add all available events for the configured source
eventpanel add --all

Add Events by Category

# Add all events from a category by ID
eventpanel add --category-id abc123

# Add all events from a category by name
eventpanel add --category-name "Dialog Screen"

Manual Configuration

You can also manually edit EventPanel.yaml to add events:

events:
  - id: YOUR_EVENT_ID_1
  - id: YOUR_EVENT_ID_2
    version: 2

Sync workspace latest revisions into YAML

eventpanel pull fetches the scheme for each event using the version from EventPanel.yaml, or 1 if version is omitted — it does not automatically pick the newest catalog revision for that event id. After the workspace bumps an event’s schema revision, run:

eventpanel outdated   # list YAML entries that lag workspace latest
eventpanel update     # write newer version: lines into EventPanel.yaml, then pull + generate (defaults)

Use eventpanel update <id> [<id>...] to update specific events. This is CLI update — not the EventPanel MCP tool update_event, which edits the live catalog on the server but does not change your local YAML.

Step 4: Integrate Codegen into Your Build

For backend / Node.js projects, you can run generation:

• On demand (e.g. before commits or deployments)
• As part of your build scripts

Add a script to your package.json:

{
  "scripts": {
    "analytics:generate": "eventpanel generate",
    "analytics:outdated": "eventpanel outdated",
    "analytics:update": "eventpanel update",
    "build": "eventpanel generate && nest build"
  }
}

You can also run generation manually:

eventpanel generate

Step 5: Install and Run the Demo App (Optional)

If you are using the EventPanel web demo:

yarn install
eventpanel generate
yarn start:dev

Usage

Basic Event Tracking

The generated TypeScript code exposes a namespace (for example AnalyticsEvents) with strongly-typed factory functions for each event.

import { AnalyticsEvents } from './analytics/events';

// Track a dialog screen test option tap
const event = AnalyticsEvents.dialogScreenTestOptionTapped();
analytics.track(event);

// Example event payload shape
// {
//   name: 'Dialog Screen Test Option Tapped',
//   parameters: {}
// }

Generated Code Structure

The CLI generates TypeScript code in the following structure (demo app):

src/
├── analytics/
│   └── events.ts                # Generated event code
├── app.controller.ts            # HTTP controller
├── app.service.ts               # Service with analytics integration
├── app.module.ts                # Root NestJS module
└── main.ts                      # App entry point

Example Generated Events

Your generated events.ts will contain type-safe helpers (shape simplified):

// Generated using EventPanel — https://github.com/eventpanel/eventpanel-cli

export namespace AnalyticsEvents {
  /**
   * User selected an answer option in a test question
   */
  export function dialogScreenTestOptionTapped(): AnalyticsEvent {
    return {
      name: 'Dialog Screen Test Option Tapped',
      parameters: {},
    };
  }
}

export interface AnalyticsEvent {
  name: string;
  parameters: Record<string, unknown>;
}

The actual structure may vary based on the CLI version and configuration, but the core ideas are:

• Strongly-typed event names
• Strongly-typed parameters
• Centralized, generated API for analytics events

Configuration Reference

EventPanel.yaml Structure

source: web                         # Event source
plugin:
  typescriptgen:
    outputFilePath: src/analytics/events.ts
    namespace: AnalyticsEvents      # Namespace for generated code
    shouldGenerateType: true        # Generate the event type
    eventClassName: AnalyticsEvent  # Base event class / interface name
    documentation: true             # Include documentation comments
    imports:                        # (Optional) Additional TypeScript imports
      - mixpanel-browser
events:
  - id: EVENT_ID                    # Event ID from EventPanel
    version: 1                      # Event schema version

Plugin Options

Option	Type	Required	Description
outputFilePath	String	Yes	Path to the generated TypeScript file
namespace	String	Yes	Namespace for generated event types
shouldGenerateType	Bool	Yes	Generate the event type definition
eventClassName	String	Yes	Base event class / interface name
documentation	Bool	Yes	Include documentation comments in generated code
imports	[String]	No	Additional TypeScript import statements to include in the generated file

Adding Events Command Reference

The eventpanel add command provides multiple ways to add events:

Command	Description
eventpanel add <event-id>	Add latest version of an event by ID
eventpanel add <event-id> --version <version>	Add specific version of an event
eventpanel add --name <event-name>	Add latest version of an event by name
eventpanel add --all	Add all available events for the configured source
eventpanel add --category-id <id>	Add all events from a category by ID
eventpanel add --category-name <name>	Add all events from a category by name

Options:

• --scheme-update / --no-scheme-update: Control whether to apply scheme updates during generation (default: enabled)

Example Configuration

A complete example configuration for the web demo:

source: web
plugin:
  typescriptgen:
    outputFilePath: src/analytics/events.ts
    namespace: AnalyticsEvents
    shouldGenerateType: true
    eventClassName: AnalyticsEvent
    documentation: true
    imports:
      - mixpanel-browser
events:
  - id: F53ZoV4lBswnVy_wWj8kU  # Dialog Screen Test Option Tapped
    version: 2

Tip: You can also manage events through the EventPanel web interface, and they will be synced to your EventPanel.yaml file.

Project Structure Example

Typical NestJS demo layout with analytics:

src/
├── analytics/
│   ├── analytics-event.interface.ts  # Base analytics event interface (optional)
│   └── events.ts                     # Generated event code
├── app.controller.ts                 # HTTP controller
├── app.service.ts                    # Service with analytics integration
├── app.module.ts                     # Root NestJS module
└── main.ts                           # App entry point

Authentication

Setting API Token

The EventPanel CLI requires authentication to fetch event schemas from your workspace. After running eventpanel init, you must set your API token:

eventpanel set-token YOUR_API_TOKEN

How to get your API token:

1. Log in to EventPanel web interface
2. Navigate to your workspace settings
3. Go to the API tokens section
4. Create a new token
5. Copy the token and use it with the set-token command

The token is securely stored locally and will be used for all authenticated CLI operations.

Verifying Authentication

After setting the token, you can verify it works by running:

eventpanel generate

If authentication fails, you'll see an error message. Make sure:

• The token is valid and not expired
• The token has the necessary permissions for your workspace
• You're connected to the internet

Learn More

• 🚀 EventPanel CLI
• 🌐 EventPanel Website
• 📚 NestJS Documentation