**Ampli** dynamically generates a lightweight wrapper for the **Amplitude SDK** based on your analytics tracking plan in **Amplitude Data**, making event tracking easier and less error-prone.

This document gives a high-level overview of Ampli. For more information, go to [Amplitude Academy](https://academy.amplitude.com/instrumenting-events-with-amplitude-data-and-the-ampli-cli).

## Key articles

- [Ampli CLI](/docs/sdks/ampli/ampli-cli).
- [Ampli Wrapper](/docs/sdks/ampli/ampli-wrapper).
- [Migrate to Ampli](/docs/sdks/ampli/migrate-to-ampli).
- [Source control](/docs/sdks/ampli/source-control).
- [Validate in CI](/docs/sdks/ampli/validate-in-ci).

![Diagram of Ampli generating a typed wrapper from the tracking plan](/images/ampli-diagram-1726085522.svg)

The **Ampli Wrapper** provides types and methods that prevent human error by strictly enforcing event names and property values. The wrapper code enables autocompletion for all events and properties in your tracking plan, plus static type checks at development and compile time.

```typescript
import { ampli, SongPlayed } from "./ampli";

// Ampli tracks these 2 events as expected.
ampli.songPlayed({ title: "Happy Birthday" });
ampli.track(new SongPlayed({ title: "Song 2" }));

// The following 2 events don't track due to data quality issues.
// Instead, they generate type errors at build time with information
// about the expected property names and types.

// Error: Event 'Song Played' is missing required property 'title'
ampli.songPlayed({ name: "I Knew You Were Trouble" });

// Error: Property 'title' received 'boolean' expected type 'String'
ampli.songPlayed({ title: true });
```

Compare this to the general-purpose **Amplitude SDK**. Sending events with hand-entered values can create data quality issues and requires close coordination between data governors and engineers.

```typescript
import * as amplitude from "@amplitude/analytics-browser";

// Amplitude tracks these 2 events as expected
amplitude.track("Song Played", { title: "Happy Birthday" });
amplitude.track({
  event_type: "Song Played",
  event_properties: { title: "Song 2" },
});

// Amplitude tracks the following 2 events, but they have data quality issues
// that make them difficult to include in analysis. Typos and type errors are
// easy to create and hard to find and fix.

// Charts based on 'title' don't include this event, which sets 'name' instead.
amplitude.track("Song Played", { name: "I Knew You Were Trouble" });

// Charts based on event_type='Song Played' don't include this event.
// It also sets 'title' to boolean 'true' instead of the expected type 'String'.
amplitude.track("sonG Playd", { title: true });
```

The **Ampli CLI** generates the **Ampli Wrapper** and can verify the instrumentation status of your events. This makes it easy to know if you missed any event tracking calls, giving you confidence that your implementation is complete.

```shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
✔ All events tracked: 1 found, 1 total
```

## Amplitude Data

**Amplitude Data** lets you plan your analytics by defining the events and properties you want to track in your application. **Ampli** requires a tracking plan in **Amplitude Data** with events added to an **SDK source**.

The following examples use this tracking plan.

- Browser SDK source named `web`.
- Event `Song Played` with required property `title` of type `String`.
- Event `Song Played` added to source `web`.
- Environment named `production`.

## Ampli CLI

The Ampli CLI connects to Amplitude Data and uses the schema information for a given source to generate and verify the Ampli Wrapper in your project.

### Install Ampli CLI

{% code-group %}
```shell brew
brew tap amplitude/ampli
brew install ampli
```

```shell npm
npm install -g @amplitude/ampli
```
{% /code-group %}

### Generate the Ampli wrapper

Running `ampli pull` connects to Amplitude Data and downloads the Ampli Wrapper for your tracking plan.

```shell
ampli pull [source-name] [--path ./path/for/generated/ampli/wrapper]
```

The Ampli Wrapper connects to a specific source in Amplitude Data. You can optionally provide the source name as a parameter. If you don't, Ampli prompts you to select one.

```shell
? Select a Source: web
```

The first time you run `ampli pull` on a source, Ampli prompts you to select a development language and an underlying Amplitude SDK. To change the source configuration later, run `ampli configure` and select a different platform, language, or Amplitude SDK.

```shell
? Select a platform: Browser
? Select a language: TypeScript
? Select a SDK: @amplitude/analytics-browser@^1.0 (recommended)
```

Ampli then makes the generated Ampli Wrapper available at the provided path. If you don't provide a path, the Ampli CLI chooses a default based on the platform for your source.

```shell
✔ Tracking library generated successfully.
  ↳ Path: ./ampli
```

## Verify event instrumentation

Running `ampli status` scans the source code in your project directory and checks for event tracking calls such as `ampli.songPlayed({ ... })`. It outputs the number of times it detects each event.

```shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
✔ All events tracked: 1 found, 1 total
```

If your tracking plan includes events that your project doesn't implement, `ampli status` returns an error. For example, this happens when you add a new event, `Song Favorited`, to the tracking plan but don't instrument it in the project.

```shell
➜ ampli status
✔ Verifying event tracking implementation in source code
  ✔ Song Played (1 location)
  ✘ Song Favorited
✘ ERROR Event tracking incomplete: 1 missed, 2 total
```

## Ampli Wrapper

### A generated SDK for your tracking plan

The **Ampli Wrapper** is a thin facade over the **Amplitude SDK** that provides convenience methods (for example, `ampli.songPlayed()`) and classes (for example, `new SongPlayed()`) for all events in your tracking plan.

```typescript
import { ampli, SongPlayed } from "./ampli";

ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });

ampli.client.setUserId("ampli@amplitude.com");

ampli.songPlayed({ title: "Happy Birthday" });

ampli.track(new SongPlayed({ title: "Song 2" }));

ampli.flush();
```

### Wrapping the Amplitude SDK

The **Ampli Wrapper** provides access to all methods of the underlying **Amplitude SDK** instance through `ampli.client`. You can configure the instance directly or provide an existing one. If you don't provide one, Ampli uses a default Amplitude SDK instance.

```typescript
import * as amplitude from "@amplitude/analytics-browser";
import { ampli } from "./ampli";
import { CustomPlugin } from "./plugins";

// Initialize the Amplitude SDK instance
amplitude.init(AMPLITUDE_API_KEY);

// Provide the Amplitude SDK instance to Ampli
ampli.load({ client: { instance: amplitude } });
assertEqual(ampli.client, amplitude);

// Call methods directly on the Amplitude SDK
ampli.client.add(CustomPlugin);
ampli.client.setUserId("ampli@amplitude.com");
ampli.client.setGroup("team", "awesome");
```

To configure the underlying Amplitude SDK instance without creating it directly, provide `client.configuration` to `ampli.load()`. Ampli supports all configuration options for the underlying Amplitude SDK.

```typescript
ampli.load({
  client: { apiKey: AMPLITUDE_API_KEY, configuration: { serverZone: "EU" } },
});
```

### Add the Ampli Wrapper to your project and track events

Use the **Ampli CLI** to download the **Ampli Wrapper**.

```shell
ampli pull [--path ./ampli]
```

Add the downloaded source code in `path` and `ampli.json` to your repository and source control.

```shell
git add ./ampli ampli.json
git commit -m "Added Ampli wrapper"
```

Depending on the **Amplitude SDK** selected for your source, install the corresponding dependency.

```shell
npm install @amplitude/analytics-browser
```

After you download the **Ampli Wrapper** with `ampli pull` and install the dependencies, use it to track events in your code.

```typescript
import { ampli, SongPlayed } from "./ampli";

ampli.load({ client: { apiKey: AMPLITUDE_API_KEY } });
ampli.songPlayed({ title: "Happy Birthday" });
ampli.flush();
```

Use the **Ampli CLI** to verify the instrumentation status of the **Ampli Wrapper** in your project.

```shell
ampli status
```