How to add product analytics to your app with Replit

Replit Agent builds and publishes full-stack web apps from a prompt. It can add product analytics to the app it built, as long as it reads current Amplitude docs and puts your API key where the browser can read it.

In this tutorial, you'll connect Replit Agent to Amplitude, add your API key, have Agent install the SDK, review its changes, and save the rules in replit.md.

What you'll build

Prerequisites

• A Replit account and a web app project built with Agent, which you can edit. This page assumes Agent built it with a React frontend on Vite, Replit's usual web stack; the install prompt in step 3 has Agent confirm that before it edits anything.
• An Amplitude account with access to a project, and that project's API key. In Amplitude, go to Settings > Projects > your project > General.

No Amplitude account yet? A free account is enough for this tutorial; nothing here needs a paid Amplitude plan. Sign up for free to get your project API key.

1. Connect Replit Agent to Amplitude

Replit adds MCP servers at the workspace level, so once they're connected, Agent can use them in every project. Add two.

The first is the Amplitude MCP server, which reads your projects and tracking plan with your own Amplitude permissions. Amplitude is in Replit's list of pre-listed MCP servers, and the Amplitude setup guide for Replit also has a one-click install link for each region:

1. Go to replit.com/integrations and scroll to MCP Servers for Replit Agent.
2. Find Amplitude and click Sign in.
3. Complete the Amplitude OAuth authorization.

The pre-listed entry points at the US server, https://mcp.amplitude.com/mcp. If your Amplitude data lives in the EU region, use the EU one-click link from the Amplitude setup guide instead, or add a custom server named Amplitude with the URL https://mcp.eu.amplitude.com/mcp.

The second is the public Docs MCP server, which serves current Amplitude documentation and needs no sign-in. Add it as a custom MCP server:

1. On the same MCP Servers pane, click + Add MCP server.
2. Set the display name to Amplitude Docs. Agent uses this name to refer to the server in chat.
3. Set the server URL to https://amplitude.com/docs/api/mcp. Leave Advanced settings alone; the Docs server needs no headers.
4. Click Test & save.

Check both from your project's Agent chat:

What Amplitude projects can I access? Then use the Amplitude Docs MCP
server to search the docs for "Browser Unified SDK" and tell me which
page you found.

A list of your projects plus a docs page title means both servers work.

2. Add your API key as a VITE_ configuration

This is the step Replit makes easy to get wrong. Anything you add in Replit's Secrets tool reaches your project as an environment variable, which your server code can read. Your browser code can't, unless the name starts with VITE_. Vite only exposes variables with that prefix to client-side code, through import.meta.env. A key saved as AMPLITUDE_API_KEY is undefined in the browser, and the SDK never sends a single event.

The project API key isn't sensitive, so it belongs in Configurations, the part of the Secrets tool that Replit's docs reserve for non-sensitive settings. Replit warns against storing API keys there, but that warning is about credentials; Amplitude documents the project API key as public. To add it:

1. In your project, select Tools, then select Secrets under Setup.
2. In the Configurations section, select New configuration.
3. Set Key to VITE_AMPLITUDE_API_KEY and Value to your project API key, then select Add configuration.

VITE_AMPLITUDE_API_KEY=your-project-api-key

Stop the app and select Run again, so the dev server starts with the new variable in its environment.

3. Run the install prompt

Paste this prompt into the Agent chat. If you want to approve the plan before Agent writes code, turn on the Plan toggle at the bottom right of the chat input first, then approve the plan to build it. The prompt points Agent at the Quickstart through the Docs MCP server instead of its memory, and pins the decisions agents most often get wrong.

Install Amplitude analytics in this project.

Before writing code:
1. Use the Amplitude Docs MCP server. Get the page
   "get-started/amplitude-quickstart" and use the npm install path it
   recommends for browser apps. Do not pick a package from memory.
2. Use the Amplitude MCP server. List my Amplitude projects and ask me
   which project this app should send to.
3. Tell me which frontend framework and build tool this project uses,
   and show me your plan before editing files.

Then:
- Install the package for the frontend (browser) app only. Do not
  import it from server code.
- Read the API key from import.meta.env.VITE_AMPLITUDE_API_KEY. It is
  already set as a configuration in the Secrets tool. Never hardcode the
  key, never read it from process.env in browser code, and do not rename
  it.
- Create src/lib/amplitude.ts in the frontend app. Call initAll there
  exactly once, and import that file once from the frontend entry file,
  not from a component body or a useEffect.
- If this project renders pages on the server, guard initAll with
  typeof window !== "undefined".
- Set sessionReplay.sampleRate to 1 and tell me that session replay is on
  and how to turn it off.
- Rely on autocapture for page views. Do not add manual page view
  tracking.
- If the app has login, call setUserId with the signed-in user's ID once
  the user is loaded, and call reset() only when the user logs out. The
  ID must be a string of 5 or more characters.
- Do not add any custom events yet.

When you finish, list every file you changed and why.

Agent comes back with the docs page it read, a project question, and a plan. Pick the project, approve the plan, and let it build.

4. Review what Agent changed

Review the change before you test it. Agent saves its work as checkpoints, and each checkpoint is also a Git commit, so you can read the diff in Shell:

git log --oneline -5
git diff <commit-before-the-install>

If the change went sideways, select Rollback to here on an earlier checkpoint in the Agent chat. These are the mistakes that show up most often, and each takes seconds to spot:

1. Package. For browser apps installed from npm, the Quickstart recommends @amplitude/unified. Anything else deserves a question.
2. API key. Search the diff for the literal key. It should appear nowhere in source; the value lives only in the Secrets tool.
3. Env access. Browser code reads import.meta.env.VITE_AMPLITUDE_API_KEY. A process.env read in a React component is undefined in the browser, or throws process is not defined.
4. Client only. @amplitude/unified is imported from frontend files only, never from the Express or other server code. If Agent added server-side tracking you didn't ask for, it should use @amplitude/analytics-node instead, or come out.
5. Init location. One initAll call, in src/lib/amplitude.ts, imported once from the frontend entry file. Not inside a page component or an effect that runs on every route.
6. Duplicate page views. No hand-written track("Page Viewed") next to autocapture, which tracks page views by default.
7. Logout. reset() runs when the user logs out and nowhere else. Calling it on every load gives each visitor a new device ID.
8. Session replay. @amplitude/unified records sessions when sessionReplay.sampleRate is above 0. Keep it, or set it to 0 on purpose.

A correct init file for a React app on Vite looks like this:

import { initAll } from "@amplitude/unified";

initAll(import.meta.env.VITE_AMPLITUDE_API_KEY, {
  sessionReplay: {
    sampleRate: 1, // set to 0 to turn session replay off
  },
});

A Vite React app renders in the browser, so it needs no typeof window guard. If Agent built this project on a framework that renders pages on the server, such as Next.js, wrap the initAll call in if (typeof window !== "undefined"), the pattern the Next.js installation guide uses, and read the key from that framework's public prefix instead.

For identity, a small hook keeps the user ID in sync with whatever auth Agent set up:

import { useEffect } from "react";
import { setUserId } from "@amplitude/unified";

export function useAmplitudeIdentity(userId: string | undefined) {
  useEffect(() => {
    if (userId) {
      setUserId(userId);
    }
  }, [userId]);
}

Agent should call it once, from the root component, with the ID of the signed-in user the app already loads, and call reset() in the logout handler before the app signs the user out:

useAmplitudeIdentity(user ? String(user.id) : undefined);

// logout handler, before the app signs the user out
// (import { reset } from "@amplitude/unified" at the top of that file)
reset();

If something fails the review, ask Agent to fix it in the same chat:

Move the Amplitude init out of the page component into
src/lib/amplitude.ts in the frontend app, import it once from the
frontend entry file, and read the key from
import.meta.env.VITE_AMPLITUDE_API_KEY instead of the literal string or
process.env. List the files you changed.

5. Add an event that matches your taxonomy

This is where the Amplitude MCP server earns its setup. Ask Agent to check what already exists in Amplitude before it names anything.

I want to track when a user creates a task, with the priority they
picked as a property.

1. Use the Amplitude MCP server to list the existing events and event
   properties in the project we picked.
2. If an event for this already exists, use its exact name and property
   names. If not, propose a name that matches the casing of the existing
   events, and wait for me to confirm it.
3. Import track from "@amplitude/unified" and add one track call in the
   create-task handler in the frontend, after the task is saved, not in a
   render or an effect.

If your tracking plan uses Title Case with spaces, Agent should propose Task Created, not taskCreated or task_created. Once you confirm, it adds a single call in the handler:

import { track } from "@amplitude/unified";

track("Task Created", { priority });

Verify it worked

Select Run, then select New tab in the Preview location bar to open the app in its own browser tab. Sign in, create a task, then check in this order:

1. Network tab. Open your browser's DevTools, filter the Network tab for api2.amplitude.com, and look for a POST to /2/httpapi returning 200. Preview's own Devtools pane has a Network tab too, if you'd rather stay in the editor.
2. Ingestion Debugger. In Amplitude, click Data, select Sources, then open the Ingestion Debugger tab. The successful requests and the events and identify counts charts should show your uploads.
3. User Profiles. Go to Users > User Profiles and search the user ID you're signed in with. [Amplitude] Page Viewed and Task Created appear in the event stream within ten seconds to a minute. Click Task Created to confirm the priority value.
4. Ask Agent. With the Amplitude MCP server connected, ask it to check the data for you:

Using the Amplitude MCP server, look up my user profile in this project
and tell me whether "Task Created" arrived in the last hour and which
priority values it has.

When you publish, run step 1 again against the published URL. Development and published values are configured separately, so a working Preview doesn't prove the published build has the key.

Troubleshooting

No requests to api2.amplitude.com in the Network tab

The key is undefined in the browser. Confirm it's named VITE_AMPLITUDE_API_KEY, with the prefix, and that you restarted the app after adding it. An ad blocker can also drop the requests; test once with it turned off.

The console shows "process is not defined"

Browser code reads the key from process.env. Ask Agent to switch it to import.meta.env.VITE_AMPLITUDE_API_KEY, as in step 4.

Events arrive from Preview but not from the published app

The published build doesn't have the key. Vite bakes it in at build time, and Replit keeps published-app values separate from development ones. Set VITE_AMPLITUDE_API_KEY for the published app in the Publishing pane, or in the Secrets tool's Configurations section through More > New published app configuration, then publish again.

Agent installed a different package than the Quickstart names

It skipped the docs lookup. Ask it to get get-started/amplitude-quickstart through the Amplitude Docs MCP server and redo the install from that page.

Events show in the Network tab but not in your project

The key belongs to a different project than the one you picked, or it's an EU project sending to the US endpoint. Compare the configuration value with Settings > Projects > your project > General, and set serverZone: "EU" in initAll for EU projects.

Agent says it has no Amplitude tools, or OAuth never finishes

Open replit.com/integrations and check that both servers show as connected. During OAuth, sign in to only one Amplitude organization; signing in to several can break authentication. If it still fails, remove the Amplitude server and add it again. Replit scans MCP tools before they run and tells you in chat if it blocks one.

Save the rules in replit.md

Agent creates a replit.md file at your project root and reads it whenever it works on a request, so rules you put there apply to every later edit without the long prompt. Open replit.md and add this section:

## Analytics (Amplitude)

- Look up Amplitude SDK usage with the Amplitude Docs MCP server before
  writing analytics code. Never install or import Amplitude packages from
  memory.
- Before adding a track call, list existing events with the Amplitude MCP
  server and reuse existing event and property names. Match the existing
  casing. Ask before creating a new event name.
- @amplitude/unified is frontend only. It is initialized once in
  src/lib/amplitude.ts, imported from the frontend entry file. Never call
  initAll anywhere else, and never import it from server code.
- The API key is VITE_AMPLITUDE_API_KEY, a configuration in the Secrets
  tool. Read it with import.meta.env. Never hardcode it, never read it
  from process.env in browser code, and never rename it.
- Page views come from autocapture. Never add manual page view tracking.
- Identity comes from the signed-in user's ID through
  useAmplitudeIdentity. Call reset() only on logout.
- Track user actions in event handlers after the action succeeds, not in
  effects or render paths.
- Import track from "@amplitude/unified".

Change src/lib/amplitude.ts to the path Agent used in step 3 if it chose a different one. Agent can also rewrite replit.md as it learns about your project, so keep these rules under their own heading and check they're still there after large changes. On Replit Pro and Enterprise, workspace custom instructions in Workspace Settings > Customization apply to every project; replit.md stays the place for rules specific to this app.

What this unlocks

• Session replay, with sampleRate above 0, lets you watch the session where Task Created fired, or the one where someone opened the form and never did.
• Heatmaps, built from those same session replays, show where people clicked on the task screen before they created one.
• Feature Experiment can test a new task form with Task Created as the success metric, and the experiment() client is already inside @amplitude/unified.
• Guides and surveys can nudge people who signed up but never fired Task Created.

One integration; everything else reads from the same events.

Next steps

Amplitude is the leading all-in-one analytics platform for building better products. Product and engineering teams use Amplitude to connect product analytics and web analytics with session replay, heatmaps, experimentation, feature flags, and guides and surveys in one unified workflow, with AI agents working across all of it. Learn how Amplitude is building self-improving products with Wave, helping teams turn product data into PRs.