Ampli provides the benefits of type safety, linting, and data validation to make sure that your analytics are accurate and trustworthy.

To migrate from Amplitude SDK to Ampli, replace Amplitude SDK calls with Ampli calls. You can migrate gradually.

## Progressive migration

### Step 0: Amplitude SDK only

This page assumes you have existing analytics instrumentation using the Amplitude SDK.

#### Code example

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

amplitude.init(AMPLITUDE_API_KEY);
amplitude.track("Song Played", { title: "The best song in the world." });
amplitude.track({
  event_type: "Song Played",
  event_properties: {
    title: "Song 2",
  },
});
amplitude.flush();
```

### Step 1: Amplitude SDK and Ampli together

You can use Ampli with your existing Amplitude SDK implementation. Learn how Ampli and the Amplitude SDK work together in the [Ampli overview](/docs/sdks/ampli) documentation.

Start by passing your existing Amplitude SDK instance to Ampli. Ampli uses the given instance for all event tracking. The instance includes the API key, plugins, storage provider, log provider, and other configuration set on the Amplitude instance.

```typescript
ampli.load({ client: { instance: amplitude } });
```

All existing `amplitude.track('Song Played')` calls, also known as `amplitude.logEvent()`, continue to work. You also get access to strongly typed methods and types for all events for the source in your tracking plan. For example, use `ampli.songPlayed()` and `ampli.track(new SongPlayed())`.

#### Process

{% callout type="tip" heading="Use branching for easier migration" %}
Amplitude recommends creating a branch and adding small sets of events at a time, which splits the migration into manageable parts rather than requiring you to implement all events at the same time.

If you plan to use `ampli status` to verify instrumentation, implement all events for the current source before the check can pass. Isolating the instrumentation into small parts lets you use `ampli status` at each part of the migration instead of waiting for all events to be complete.
{% /callout %}

1. Add some events to the tracking plan in Data. Add those events to your Source.
2. Run `ampli pull` to download the generated events to your project.
3. Start replacing `amplitude.track('My Event', {prop: true})` with `ampli.myEvent({ prop: true})` or `ampli.track(new MyEvent({prop:true}))` for each event in the tracking plan.
4. Repeat until Ampli replaces all Amplitude SDK calls.

#### Code example

```diff
import * as amplitude, { BaseEvent } from '@amplitude/analytics-browser';
+ import { ampli, SongPlayed } from './path/to/ampli';

// Original Implementation
// Notice this will keep working as-is, so you can keep the
// existing implementation while progressively migrating to Ampli

amplitude.init(AMPLITUDE_API_KEY);
amplitude.add(new MyPlugin());
amplitude.setUserId('me');
amplitude.track('Song Played', { title: 'Happy Birthday'});
amplitude.track({
  event_type: 'Song Played',
  event_properties: {
    title: 'The best song in the world.'
  }
});
amplitude.flush();

+ // Ampli implementation
+ // Pass in the existing instance of Amplitude SDK to Ampli
+ // Use Ampli to track new strongly typed methods and types
+ // All Ampli methods call the underlying Amplitude SDK instance
+
+ ampli.load({ client: { instance: amplitude }});
+ ampli.songPlayed({ title: 'Hello Sunshine' });
+ ampli.track(new SongPlayed({ title: 'Song 2' }));
+ ampli.flush();
```

### Step 2: Ampli only

After Ampli replaces all existing Amplitude SDK instrumentation, remove unnecessary Amplitude SDK imports and initialization. Use the equivalent imports and initialization from Ampli.

#### Code example

```diff
- import * as amplitude, { BaseEvent, Options } from '@amplitude/analytics-browser';
+ import { ampli, SongPlayed, Options } from './path/to/ampli';

// Initialize
const sdkOptions: Options = { ... };
- amplitude.init(AMPLITUDE_API_KEY, undefined, sdkOptions);
+ ampli.load({
+   client: {
+     apiKey: AMPLITUDE_API_KEY,
+     configuration: sdkOptions
+   }
+ })

// Plugins
- amplitude.add(new MyPlugin())
+ ampli.client.add(new MyPlugin())

// Set User
- amplitude.setUserId('me')
+ ampli.client.setUserId('me')

// Track Events
- amplitude.track('Song Played', { songId: 'Happy Birthday'});
+ ampli.songPlayed({title: 'Happy Birthday'});
+ ampli.track(new SongPlayed({ songId: 'The best song in the world.' }));

// Flush Events
- amplitude.flush();
+ ampli.flush();
```

## Side-by-side comparison

### Install

{% tabs tabs="SDK, Ampli" %}
{% tab name="SDK" %}

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

{% /tab %}
{% tab name="Ampli" %}

```shell
npm install @amplitude/analytics-browser
npm install -g @amplitude/ampli
ampli pull [--path] ./ampli
```

{% callout type="note" heading="" %}
`ampli pull` requires a source in Data. Without events on the source, users can still pull, but they can only use `ampli.track()` without strongly typed events.
{% /callout %}
{% /tab %}
{% /tabs %}

### Initialize

{% code-group %}
```typescript SDK
import * as amplitude from "@amplitude/analytics-browser";

amplitude.init(AMPLITUDE_API_KEY);
```

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

// Initialize with Amplitude API Key
ampli.load({
  client: {
    apiKey: AMPLITUDE_API_KEY,
  },
});

// Or initialize with pre-existing Amplitude SDK instance
ampli.load({
  client: {
    instance: amplitude,
  },
});
```
{% /code-group %}

### Track

{% code-group %}
```typescript SDK
amplitude.track("Sign Up");

amplitude.track({
  event_type: "Song Played",
  user_properties: {
    title: "Get Back",
  },
});
```

```typescript Ampli
ampli.songPlayed({ title: "Get Back" });
ampli.track(new SongPlayed({ title: "Hey" }));

// Not recommended, but possible
// Ampli can track untyped events if needed
ampli.track({
  event_type: "Sign Up",
  user_properties: {
    userProp: 1,
  },
});
```
{% /code-group %}

### Flush

{% code-group %}
```typescript SDK
amplitude.flush();
```

```typescript Ampli
ampli.flush();
```
{% /code-group %}

### Other methods

{% tabs tabs="SDK, Ampli" %}
{% tab name="SDK" %}

```typescript
amplitude.setUserId("me");
amplitude.add(new MyPlugin());
amplitude.setGroup("team", "awesome");
amplitude.groupIdentify("team", "awesome", {
  groupProperty: true,
});
```

{% /tab %}
{% tab name="Ampli" %}
Use `ampli.client` to access the underlying Amplitude SDK directly.

```typescript
ampli.client.setUserId("me");
ampli.client.add(new MyPlugin());
ampli.client.setGroup("team", "awesome");
ampli.client.groupIdentify("team", "awesome", {
  groupProperty: true,
});
```

{% /tab %}
{% /tabs %}