Quick start

This guide will get you up and running with a basic setup of Eventvisor.

Prerequisites#

• Node.js v24+

NOTE: Eventvisor SDKs are meant to be platform agnostic. Node.js is only required for the CLI for managing projects.

Initialize a new project#

Run the following command to initialize a new project:

$ mkdir my-project && cd my-project
$ npx @eventvisor/cli init

To begin with a fuller e-commerce reference instead, initialize the demo scaffold:

$ npx @eventvisor/cli init --project=demo

This is ideally meant to be a completely separate repository from your application code, so they can be deployed independently.

Learn more in projects page about more advanced uses cases, including monorepo setup.

Installation#

Once initialized, install the dependencies:

$ npm install

Install skills for AI agents#

Installing skills for AI agents is optional, but it can help you manage your Eventvisor project faster and more accurately:

$ npx skills add eventvisor/eventvisor

In agents such as Claude Code, Codex, Cursor, and OpenCode, you can use the skill by mentioning /eventvisor.

Configuring your project#

Once installed, you can configure the Eventvisor project by editing the eventvisor.config.js file.

A very minimal configuration file would look like this:

module.exports = {
  tags: [
    'web',
    'mobile',
    'backend',
  ],
}

Tags label related definitions so they can be selected together. Targets use tags, keys, and patterns to define the smaller datafiles that applications load through Eventvisor SDKs.

This allows you to have a single Eventvisor project that can be used by multiple applications, and each application can load only the data it needs.

Learn more in Configuration page.

Defining attributes#

Attributes are contextual information about the environment that your application is running in. These attributes can be about the user, the device, the application itself, etc which do not change too frequently.

For now, we can we define two simple attributes.

First deviceId:

description: Device ID
tags:
  - web
type: string

And also userId:

description: User ID (if user is logged in)
tags:
  - web
type: string

The name of the attribute is the file name (without the extension).

The schema for attributes is defined using a subset of JSON Schema that you can read more about here.

Learn more in Attributes page.

Defining events#

Events are structured data, which can be either a log or an analytics event, that your application will track using SDKs.

For now, we can we define a simple event called pageView:

description: Page view
tags:
  - web
type: object
properties:
  url:
    type: string
required:
  - url

Above, we defined an event called pageView with a JSON Schema that expects a url property which is a required property.

Example payload in JSON format would look like this:

{
  "url": "https://www.example.com"
}

Learn more in Events page.

Define a destination#

Destinations are where our tracked events are sent to, and transports are the means how they reach there.

Transports can be your browser's console, your favourite analytics service like GA4, or your own custom backend service.

Assuming our target application is a web application, we can define a destination called browser which will log the tracked events to the browser's console:

description: Print to browser console
tags:
  - web
transport: console

We will learn more later about how transports are setup via modules in the application layer.

Transforms#

We can also use transforms to manipulate the body of the event before it is handed over to the transport:

# ...
transforms:
  # remove a certain property
  - type: remove
    target: payload.sensitiveProperty

Learn about more advanced use cases of transforms in destinations page.

Conditions#

If we wish to filter the events before they are transported to a particular destination, we can also add conditions to it:

# ...
conditions:
  - source: eventName
    operator: equals
    value: pageView

Above will make sure only the pageView event is transported to the browser's console, and not other tracked events.

Learn more in conditions and sources pages.

Sampling#

Sometimes you may want to ingest only a certain percentage of the tracked events to your desired destination. You can do that by adding a sampling rule to the destination:

# ...
sample:
  by: attributes.userId
  percentage: 10

It is recommended to use a consistent value like userId attribute to sample the events, because this will allow maintaining a consistent sampling strategy across different devices and sessions (think web, iOS, and Android apps) for the same user.

Learn about more advanced sampling rules in sampling page.

Linting#

It's not surprising that managing all these files can lead to syntax errors and other structural issues. To help with that, Eventvisor provides a linter that will help you catch these issues early:

$ npx eventvisor lint

Learn more in Linting page.

Building datafiles#

Datafiles are static JSON files generated for named Targets. Add a Target for each application or service:

description: Web application
tag: web

Tags are reusable selection metadata. The Target is the artifact contract.

You can build them by running the following command:

$ npx eventvisor build

The output will be available in the datafiles directory:

datafiles/
└── eventvisor-web.json

Learn more in building datafiles page.

Deploy datafiles#

Eventvisor itself does not have any opinion on how you make these datafiles available to your applications. You can use your own server, or a CDN, or even deploy them long with your application code.

Because controlling how events flow from applications via remote configuration is highly beneficial, it is recommended that you use a CDN to serve them, allowing you to decouple your application code deployment from your Eventvisor project's datafile deployments.

You can learn more about deployment strategies in deployment page.

Consume datafiles using SDKs#

Once you have built the datafiles, you can consume them using Eventvisor SDKs.

Use the JavaScript SDK in browsers, Node.js, React, and React Native applications. A Java SDK is also available for JVM applications.

Install SDK#

In your application (either web or Node.js), install the SDK and the console module together:

$ npm install --save @eventvisor/sdk @eventvisor/module-console

Modules are additional packages that can be installed on demand to expand the capabilities of the SDK.

Initialize SDK#

Once your desired datafile is fetched, you can initialize the SDK along with the module(s) you want to use:

import { createEventvisor } from "@eventvisor/sdk";
import { createConsoleModule } from "@eventvisor/module-console";
// fetch datafile, or
// have it hardcoded in the application
const DATAFILE_URL = "https://cdn.yoursite.com/eventvisor-web.json";
const datafile = await fetch(DATAFILE_URL).then(res => res.json());
// initialize
const eventvisor = createEventvisor({
  datafile: datafile,
  modules: [
    createConsoleModule(),
  ],
});

Set attributes#

Now that we have the SDK instance ready, we can start setting attributes:

await eventvisor.setAttribute("deviceId", "device-123");
await eventvisor.setAttribute("userId", "user-456");

Track events#

Now the more interesting part for tracking events:

await eventvisor.track("pageView", {
  path: "/home",
});

Doing above will show us a warning in the console, because the payload of this event does not honour the schema that we defined for it earlier.

We can try doing it the correct way now:

await eventvisor.track("pageView", {
  url: "https://www.yoursite.com/home",
});

Now you should see the tracked event in your application's console immediately.

If you indeed see it, it means you have successfully set up Eventvisor and you are ready to start tracking your events.

Next steps#

This was a very simple setup, but there's a lot more that you can do with Eventvisor.

Several concepts that can help you make the most out of Eventvisor below:

• Testing declaratively
• Effects & handlers
• Writing your own modules
• Lookups for enriching payloads
• Multiple environments
• Parsers for going beyond YAML files