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
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:

Create an API Token:
- Go to your EventPanel workspace settings
- Navigate to the API tokens section
- Create a new token
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

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",
    "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:
    documentation: true             # Include documentation comments
    outputFilePath: src/analytics/events.ts
    eventClassName: AnalyticsEvent  # Base event class / interface name
    namespace: AnalyticsEvents      # Namespace for generated code
events:
  - id: EVENT_ID                    # Event ID from EventPanel
    version: 1                      # Event schema version

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
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:

Log in to EventPanel web interface
Navigate to your workspace settings
Go to the API tokens section
Create a new token
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

Overview​

Features​

Installation​

Prerequisites​

Install EventPanel CLI​

Option 1: Homebrew (Recommended)​

Option 2: Manual Installation​

Verify Installation​

Project Initialization​

Step 1: Initialize EventPanel Configuration​

Step 2: Set API Token​

Step 3: Add Events to Configuration​

Add a Single Event by ID​

Add an Event by Name​

Add All Events​

Add Events by Category​

Manual Configuration​

Step 4: Integrate Codegen into Your Build​

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

Usage​

Basic Event Tracking​

Generated Code Structure​

Example Generated Events​

Configuration Reference​

EventPanel.yaml Structure​

Adding Events Command Reference​

Example Configuration​

Project Structure Example​

Authentication​

Setting API Token​

Verifying Authentication​

Learn More​