@amplitude/wizard 1.0.0-beta.2 → 1.0.0

package/skills/integration/integration-react-react-router-7-data/references/EXAMPLE.md

@@ -0,0 +1,830 @@
+# Amplitude React Router v7 - Data mode Example Project
+
+Repository: https://github.com/amplitude/context-hub
+Path: basics/react-react-router-7-data
+
+---
+
+## README.md
+
+# Amplitude React Router 7 Data Mode example
+
+This is a [React Router 7](https://reactrouter.com) Data Mode example demonstrating Amplitude integration with product analytics and event tracking.
+
+### Amplitude SDKs
+
+The browser uses the [Browser Unified SDK (npm)](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk#unified-sdk-npm): [`@amplitude/unified`](https://www.npmjs.com/package/@amplitude/unified) with `initAll` in `index.tsx`. [Initialize the Unified SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk#initialize-the-unified-sdk) describes `initAll` as initializing every product bundled with Unified npm. Optional settings are in [Unified SDK configuration](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk#configuration). The `experiment` block is **Feature Experiment** (`@amplitude/experiment-js-client`). Amplitude’s [product support table](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk#product-support-by-installation-method) lists **Web Experiment** (`@amplitude/experiment-tag`, including the visual editor) for Amplitude’s [CDN unified script](https://amplitude.com/docs/sdks/analytics/browser/browser-unified-sdk#unified-script-cdn), not the Unified **npm** row.
+
+For API or server-side events, use [`@amplitude/analytics-node`](https://www.npmjs.com/package/@amplitude/analytics-node).
+
+## Features
+
+- **Product Analytics**: Track user events and behaviors
+- **User Authentication**: Demo login system with Amplitude user identification
+- **Client-side Tracking**: Examples of client-side tracking methods
+
+## Getting Started
+
+### 1. Install Dependencies
+
+```bash
+npm install
+# or
+pnpm install
+```
+
+### 2. Configure Environment Variables
+
+Create a `.env` file in the root directory:
+
+```bash
+VITE_PUBLIC_AMPLITUDE_API_KEY=your_amplitude_api_key
+```
+
+Get your Amplitude API key from your [Amplitude project settings](https://app.amplitude.com).
+
+### 3. Run the Development Server
+
+```bash
+npm run dev
+# or
+pnpm dev
+```
+
+Open [http://localhost:5173](http://localhost:5173) with your browser to see the app.
+
+## Project Structure
+
+```
+app/
+├── components/
+│   └── Header.tsx           # Navigation header with auth state
+├── contexts/
+│   └── AuthContext.tsx      # Authentication context with Amplitude integration
+├── routes/
+│   ├── home.tsx             # Home/Login page
+│   ├── burrito.tsx          # Demo feature page with event tracking
+│   └── profile.tsx          # User profile page
+└── root.tsx                 # Root layout component
+index.tsx                    # App entry point with Amplitude initialization
+```
+
+## Key Integration Points
+
+### Client-side initialization (index.tsx)
+
+```typescript
+import * as amplitude from '@amplitude/unified';
+
+void amplitude.initAll(import.meta.env.VITE_PUBLIC_AMPLITUDE_API_KEY);
+```
+
+### User identification (contexts/AuthContext.tsx)
+
+```typescript
+import * as amplitude from '@amplitude/unified';
+import { Identify } from '@amplitude/unified';
+
+amplitude.setUserId(username);
+const identifyObj = new Identify();
+identifyObj.set('username', username);
+amplitude.identify(identifyObj);
+amplitude.track('User Logged In', { username });
+```
+
+### Event tracking (routes/burrito.tsx)
+
+```typescript
+amplitude.track('Burrito Considered', {
+  total_considerations: updatedUser.burritoConsiderations,
+  username: user.username,
+});
+```
+
+## Learn More
+
+- [Amplitude Documentation](https://amplitude.com/docs)
+- [React Router 7 Documentation](https://reactrouter.com/home)
+- [Amplitude Browser SDK](https://amplitude.com/docs/sdks/analytics/browser/browser-sdk-2)
+
+---
+
+## .env.example
+
+```example
+VITE_PUBLIC_AMPLITUDE_API_KEY=
+
+```
+
+---
+
+## .react-router/types/+future.ts
+
+```ts
+// Generated by React Router
+
+import "react-router";
+
+declare module "react-router" {
+  interface Future {
+    v8_middleware: false
+  }
+}
+```
+
+---
+
+## .react-router/types/+routes.ts
+
+```ts
+// Generated by React Router
+
+import "react-router"
+
+declare module "react-router" {
+  interface Register {
+    pages: Pages
+    routeFiles: RouteFiles
+    routeModules: RouteModules
+  }
+}
+
+type Pages = {
+  "/": {
+    params: {};
+  };
+};
+
+type RouteFiles = {
+  "root.tsx": {
+    id: "root";
+    page: "/";
+  };
+  "routes/home.tsx": {
+    id: "routes/home";
+    page: "/";
+  };
+};
+
+type RouteModules = {
+  "root": typeof import("./app/root.tsx");
+  "routes/home": typeof import("./app/routes/home.tsx");
+};
+```
+
+---
+
+## .react-router/types/app/+types/root.ts
+
+```ts
+// Generated by React Router
+
+import type { GetInfo, GetAnnotations } from "react-router/internal";
+
+type Module = typeof import("../root.js")
+
+type Info = GetInfo<{
+  file: "root.tsx",
+  module: Module
+}>
+
+type Matches = [{
+  id: "root";
+  module: typeof import("../root.js");
+}];
+
+type Annotations = GetAnnotations<Info & { module: Module, matches: Matches }, false>;
+
+export namespace Route {
+  // links
+  export type LinkDescriptors = Annotations["LinkDescriptors"];
+  export type LinksFunction = Annotations["LinksFunction"];
+
+  // meta
+  export type MetaArgs = Annotations["MetaArgs"];
+  export type MetaDescriptors = Annotations["MetaDescriptors"];
+  export type MetaFunction = Annotations["MetaFunction"];
+
+  // headers
+  export type HeadersArgs = Annotations["HeadersArgs"];
+  export type HeadersFunction = Annotations["HeadersFunction"];
+
+  // middleware
+  export type MiddlewareFunction = Annotations["MiddlewareFunction"];
+
+  // clientMiddleware
+  export type ClientMiddlewareFunction = Annotations["ClientMiddlewareFunction"];
+
+  // loader
+  export type LoaderArgs = Annotations["LoaderArgs"];
+
+  // clientLoader
+  export type ClientLoaderArgs = Annotations["ClientLoaderArgs"];
+
+  // action
+  export type ActionArgs = Annotations["ActionArgs"];
+
+  // clientAction
+  export type ClientActionArgs = Annotations["ClientActionArgs"];
+
+  // HydrateFallback
+  export type HydrateFallbackProps = Annotations["HydrateFallbackProps"];
+
+  // Component
+  export type ComponentProps = Annotations["ComponentProps"];
+
+  // ErrorBoundary
+  export type ErrorBoundaryProps = Annotations["ErrorBoundaryProps"];
+}
+```
+
+---
+
+## .react-router/types/app/routes/+types/home.ts
+
+```ts
+// Generated by React Router
+
+import type { GetInfo, GetAnnotations } from "react-router/internal";
+
+type Module = typeof import("../home.js")
+
+type Info = GetInfo<{
+  file: "routes/home.tsx",
+  module: Module
+}>
+
+type Matches = [{
+  id: "root";
+  module: typeof import("../../root.js");
+}, {
+  id: "routes/home";
+  module: typeof import("../home.js");
+}];
+
+type Annotations = GetAnnotations<Info & { module: Module, matches: Matches }, false>;
+
+export namespace Route {
+  // links
+  export type LinkDescriptors = Annotations["LinkDescriptors"];
+  export type LinksFunction = Annotations["LinksFunction"];
+
+  // meta
+  export type MetaArgs = Annotations["MetaArgs"];
+  export type MetaDescriptors = Annotations["MetaDescriptors"];
+  export type MetaFunction = Annotations["MetaFunction"];
+
+  // headers
+  export type HeadersArgs = Annotations["HeadersArgs"];
+  export type HeadersFunction = Annotations["HeadersFunction"];
+
+  // middleware
+  export type MiddlewareFunction = Annotations["MiddlewareFunction"];
+
+  // clientMiddleware
+  export type ClientMiddlewareFunction = Annotations["ClientMiddlewareFunction"];
+
+  // loader
+  export type LoaderArgs = Annotations["LoaderArgs"];
+
+  // clientLoader
+  export type ClientLoaderArgs = Annotations["ClientLoaderArgs"];
+
+  // action
+  export type ActionArgs = Annotations["ActionArgs"];
+
+  // clientAction
+  export type ClientActionArgs = Annotations["ClientActionArgs"];
+
+  // HydrateFallback
+  export type HydrateFallbackProps = Annotations["HydrateFallbackProps"];
+
+  // Component
+  export type ComponentProps = Annotations["ComponentProps"];
+
+  // ErrorBoundary
+  export type ErrorBoundaryProps = Annotations["ErrorBoundaryProps"];
+}
+```
+
+---
+
+## app/components/Header.tsx
+
+```tsx
+import { Link } from 'react-router';
+import { useAuth } from '../contexts/AuthContext';
+import * as amplitude from '@amplitude/unified';
+
+export default function Header() {
+  const { user, logout } = useAuth();
+
+  const handleLogout = () => {
+    amplitude.track('User Logged Out');
+    amplitude.reset();
+    logout();
+  };
+
+  return (
+    <header className="header">
+      <div className="header-container">
+        <nav>
+          <Link to="/">Home</Link>
+          {user && (
+            <>
+              <Link to="/burrito">Burrito Consideration</Link>
+              <Link to="/profile">Profile</Link>
+            </>
+          )}
+        </nav>
+        <div className="user-section">
+          {user ? (
+            <>
+              <span>Welcome, {user.username}!</span>
+              <button onClick={handleLogout} className="btn-logout">
+                Logout
+              </button>
+            </>
+          ) : (
+            <span>Not logged in</span>
+          )}
+        </div>
+      </div>
+    </header>
+  );
+}
+
+```
+
+---
+
+## app/contexts/AuthContext.tsx
+
+```tsx
+import * as amplitude from '@amplitude/unified';
+import { Identify } from '@amplitude/unified';
+import { createContext, useContext, useState, type ReactNode } from 'react';
+
+interface User {
+  username: string;
+  burritoConsiderations: number;
+}
+
+interface AuthContextType {
+  user: User | null;
+  login: (username: string, password: string) => Promise<boolean>;
+  logout: () => void;
+  setUser: (user: User) => void;
+}
+
+const AuthContext = createContext<AuthContextType | undefined>(undefined);
+
+const users: Map<string, User> = new Map();
+
+export function AuthProvider({ children }: { children: ReactNode }) {
+  const [user, setUser] = useState<User | null>(() => {
+    if (typeof window === 'undefined') return null;
+
+    const storedUsername = localStorage.getItem('currentUser');
+    if (storedUsername) {
+      const existingUser = users.get(storedUsername);
+      if (existingUser) {
+        return existingUser;
+      }
+    }
+    return null;
+  });
+
+  const login = async (username: string, password: string): Promise<boolean> => {
+    // Client-side only fake auth - no server calls
+    if (!username || !password) {
+      return false;
+    }
+
+    let localUser = users.get(username);
+    if (!localUser) {
+      localUser = {
+        username,
+        burritoConsiderations: 0
+      };
+      users.set(username, localUser);
+    }
+
+    setUser(localUser);
+    localStorage.setItem('currentUser', username);
+
+    // Identify user in Amplitude using username as user ID
+    amplitude.setUserId(username);
+    const identifyObj = new Identify();
+    identifyObj.set('username', username);
+    amplitude.identify(identifyObj);
+    amplitude.track('User Logged In', { username });
+
+    return true;
+  };
+
+  const logout = () => {
+    setUser(null);
+    localStorage.removeItem('currentUser');
+  };
+
+  const setUserState = (newUser: User) => {
+    setUser(newUser);
+    users.set(newUser.username, newUser);
+  };
+
+  return (
+    <AuthContext.Provider value={{ user, login, logout, setUser: setUserState }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+export function useAuth() {
+  const context = useContext(AuthContext);
+  if (context === undefined) {
+    throw new Error('useAuth must be used within an AuthProvider');
+  }
+  return context;
+}
+
+```
+
+---
+
+## app/root.tsx
+
+```tsx
+import { Outlet, useRouteError, isRouteErrorResponse } from "react-router";
+import Header from "./components/Header";
+import { AuthProvider } from "./contexts/AuthContext";
+import "./globals.css";
+
+export default function Root() {
+  return (
+      <AuthProvider>
+        <Header />
+        <main>
+          <Outlet />
+        </main>
+      </AuthProvider>
+  );
+}
+
+export function RootErrorBoundary() {
+  const error = useRouteError();
+
+  if (isRouteErrorResponse(error)) {
+    return (
+      <>
+        <h1>
+          {error.status} {error.statusText}
+        </h1>
+        <p>{error.data}</p>
+      </>
+    );
+  } else if (error instanceof Error) {
+    return (
+      <div>
+        <h1>Error</h1>
+        <p>{error.message}</p>
+        <p>The stack trace is:</p>
+        <pre>{error.stack}</pre>
+      </div>
+    );
+  } else {
+    return <h1>Unknown Error</h1>;
+  }
+}
+
+```
+
+---
+
+## app/routes.tsx
+
+```tsx
+import React from "react";
+import type { RouteObject } from "react-router";
+import Root, { RootErrorBoundary } from "./root";
+import Home from "./routes/home";
+import Burrito from "./routes/burrito";
+import Profile from "./routes/profile";
+
+export const routes: RouteObject[] = [
+  {
+    path: "/",
+    element: <Root />,
+    ErrorBoundary: RootErrorBoundary,
+    children: [
+      {
+        index: true,
+        element: <Home />,
+      },
+      {
+        path: "burrito",
+        element: <Burrito />,
+      },
+      {
+        path: "profile",
+        element: <Profile />,
+      },
+    ],
+  },
+];
+
+
+```
+
+---
+
+## app/routes/burrito.tsx
+
+```tsx
+import { useState, useEffect } from 'react';
+import { useNavigate } from 'react-router';
+import { useAuth } from '../contexts/AuthContext';
+import * as amplitude from '@amplitude/unified';
+
+export default function BurritoPage() {
+  const { user, setUser } = useAuth();
+  const navigate = useNavigate();
+  const [hasConsidered, setHasConsidered] = useState(false);
+
+  useEffect(() => {
+    if (!user) {
+      navigate('/');
+    }
+  }, [user, navigate]);
+
+  if (!user) {
+    return null;
+  }
+
+  const handleConsideration = () => {
+    // Client-side only - no server calls
+    const updatedUser = {
+      ...user,
+      burritoConsiderations: user.burritoConsiderations + 1
+    };
+    setUser(updatedUser);
+    setHasConsidered(true);
+    setTimeout(() => setHasConsidered(false), 2000);
+
+    // Capture burrito consideration event
+    amplitude.track('Burrito Considered', {
+      total_considerations: updatedUser.burritoConsiderations,
+      username: user.username,
+    });
+  };
+
+  return (
+    <div className="container">
+      <h1>Burrito consideration zone</h1>
+      <p>Take a moment to truly consider the potential of burritos.</p>
+
+      <div style={{ textAlign: 'center' }}>
+        <button
+          onClick={handleConsideration}
+          className="btn-burrito"
+        >
+          I have considered the burrito potential
+        </button>
+
+        {hasConsidered && (
+          <p className="success">
+            Thank you for your consideration! Count: {user.burritoConsiderations}
+          </p>
+        )}
+      </div>
+
+      <div className="stats">
+        <h3>Consideration stats</h3>
+        <p>Total considerations: {user.burritoConsiderations}</p>
+      </div>
+    </div>
+  );
+}
+
+```
+
+---
+
+## app/routes/home.tsx
+
+```tsx
+import { useState } from 'react';
+import { useAuth } from '../contexts/AuthContext';
+
+export default function Home() {
+  const { user, login } = useAuth();
+  const [username, setUsername] = useState('');
+  const [password, setPassword] = useState('');
+  const [error, setError] = useState('');
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    setError('');
+
+    const success = await login(username, password);
+    if (success) {
+      setUsername('');
+      setPassword('');
+    } else {
+      setError('Please provide both username and password');
+    }
+  };
+
+  if (user) {
+    return (
+      <div className="container">
+        <h1>Welcome back, {user.username}!</h1>
+        <p>You are now logged in. Feel free to explore:</p>
+        <ul>
+          <li>Consider the potential of burritos</li>
+          <li>View your profile and statistics</li>
+        </ul>
+      </div>
+    );
+  }
+
+  return (
+    <div className="container">
+      <h1>Welcome to Burrito Consideration App</h1>
+      <p>Please sign in to begin your burrito journey</p>
+
+      <form onSubmit={handleSubmit} className="form">
+        <div className="form-group">
+          <label htmlFor="username">Username:</label>
+          <input
+            type="text"
+            id="username"
+            value={username}
+            onChange={(e) => setUsername(e.target.value)}
+            placeholder="Enter any username"
+          />
+        </div>
+
+        <div className="form-group">
+          <label htmlFor="password">Password:</label>
+          <input
+            type="password"
+            id="password"
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            placeholder="Enter any password"
+          />
+        </div>
+
+        {error && <p className="error">{error}</p>}
+
+        <button type="submit" className="btn-primary">Sign In</button>
+      </form>
+
+      <p className="note">
+        Note: This is a demo app. Use any username and password to sign in.
+      </p>
+    </div>
+  );
+}
+
+```
+
+---
+
+## app/routes/profile.tsx
+
+```tsx
+import { useEffect } from 'react';
+import { useNavigate } from 'react-router';
+import { useAuth } from '../contexts/AuthContext';
+
+export default function ProfilePage() {
+  const { user } = useAuth();
+  const navigate = useNavigate();
+
+  useEffect(() => {
+    if (!user) {
+      navigate('/');
+    }
+  }, [user, navigate]);
+
+  if (!user) {
+    return null;
+  }
+
+  return (
+    <div className="container">
+      <h1>User Profile</h1>
+
+      <div className="stats">
+        <h2>Your Information</h2>
+        <p><strong>Username:</strong> {user.username}</p>
+        <p><strong>Burrito Considerations:</strong> {user.burritoConsiderations}</p>
+      </div>
+
+      <div style={{ marginTop: '2rem' }}>
+        <h3>Your Burrito Journey</h3>
+        {user.burritoConsiderations === 0 ? (
+          <p>You haven&apos;t considered any burritos yet. Visit the Burrito Consideration page to start!</p>
+        ) : user.burritoConsiderations === 1 ? (
+          <p>You&apos;ve considered the burrito potential once. Keep going!</p>
+        ) : user.burritoConsiderations < 5 ? (
+          <p>You&apos;re getting the hang of burrito consideration!</p>
+        ) : user.burritoConsiderations < 10 ? (
+          <p>You&apos;re becoming a burrito consideration expert!</p>
+        ) : (
+          <p>You are a true burrito consideration master! 🌯</p>
+        )}
+      </div>
+    </div>
+  );
+}
+
+```
+
+---
+
+## index.html
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>React Router 7 Data Mode</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/index.tsx"></script>
+  </body>
+</html>
+
+```
+
+---
+
+## index.tsx
+
+```tsx
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { createBrowserRouter, RouterProvider } from "react-router";
+import Root, { RootErrorBoundary } from "./app/root";
+import Home from "./app/routes/home";
+import Burrito from "./app/routes/burrito";
+import Profile from "./app/routes/profile";
+
+import * as amplitude from '@amplitude/unified'
+
+void amplitude.initAll(import.meta.env.VITE_PUBLIC_AMPLITUDE_API_KEY);
+
+const router = createBrowserRouter([
+  {
+    path: "/",
+    Component: Root,
+    ErrorBoundary: RootErrorBoundary,
+    children: [
+      {
+        index: true,
+        Component: Home,
+      },
+      {
+        path: "burrito",
+        Component: Burrito,
+      },
+      {
+        path: "profile",
+        Component: Profile,
+      },
+    ],
+  },
+]);
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <RouterProvider router={router} />
+  </StrictMode>
+);
+
+```
+
+---
+
+## vite.config.ts
+
+```ts
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import tsconfigPaths from "vite-tsconfig-paths";
+
+export default defineConfig({
+  plugins: [react(), tsconfigPaths()],
+});
+
+
+```
+
+---
+