@datalyr/wizard 1.0.4 → 1.0.5

package/dist/bin/wizard.js

@@ -132,9 +132,11 @@ Install and configure the Datalyr analytics SDK in the user's project. Complete
 | SDK | Use Case | Install Command |
 |-----|----------|-----------------|
 | @datalyr/web | Browser apps (React, Vue, Svelte, Next.js client) | npm install @datalyr/web |
-| @datalyr/api | Server-side (Next.js API routes, Express, Node) | npm install @datalyr/api |
+| @datalyr/api | Server-side only (API routes, Express, Node) | npm install @datalyr/api |
 | @datalyr/react-native | React Native & Expo mobile apps | npm install @datalyr/react-native |
 | DatalyrSDK | Native iOS Swift apps | Swift Package Manager |
+
+IMPORTANT: For most projects, you only need @datalyr/web. Do NOT install @datalyr/api unless the user explicitly needs server-side tracking.
 </sdks>
 
 <rules>
@@ -143,40 +145,140 @@ Install and configure the Datalyr analytics SDK in the user's project. Complete
 3. MATCH the project's code style (indentation, quotes, semicolons)
 4. USE TypeScript if the project uses TypeScript
 5. PLACE initialization in the correct entry point for the framework
-6. UPDATE .env or .env.local with NEXT_PUBLIC_DATALYR_WORKSPACE_ID
+6. UPDATE .env or .env.local with the correct env var name for the framework
 7. CHECK for existing Datalyr setup first - don't duplicate
+8. ONLY install @datalyr/web unless server-side tracking is explicitly needed
 </rules>
 
+<critical-nextjs-rules>
+NEXT.JS APP ROUTER REQUIRES SPECIAL HANDLING:
+
+1. SERVER VS CLIENT COMPONENTS:
+   - By default, all components in app/ directory are Server Components
+   - Server Components CANNOT use: useEffect, useState, useRef, onClick, or any browser APIs
+   - To use these, you MUST add 'use client' directive at the TOP of the file
+
+2. THE 'use client' DIRECTIVE:
+   - MUST be the FIRST line of the file (before any imports)
+   - Makes the component and all its children Client Components
+   - Required for any component that uses React hooks or browser APIs
+
+3. THE PROVIDER PATTERN (REQUIRED FOR NEXT.JS APP ROUTER):
+   - Create a separate Client Component file for the provider
+   - The layout.tsx stays as a Server Component
+   - Import and use the provider inside layout.tsx
+
+4. WINDOW/DOCUMENT CHECKS:
+   - Even in Client Components, code runs on server first for SSR
+   - useEffect is the safest way to run client-only code
+   - Never access window/document outside of useEffect
+
+CORRECT PATTERN:
+- app/providers.tsx -> 'use client' + DatalyrProvider with useEffect
+- app/layout.tsx -> Server Component that imports and wraps with DatalyrProvider
+</critical-nextjs-rules>
+
 <workflow>
 Step 1: Read package.json to detect framework and package manager
 Step 2: List files to find entry points (app/layout.tsx, src/main.tsx, App.tsx, etc.)
 Step 3: Read entry point files to understand current structure
-Step 4: Install SDK packages using detected package manager
-Step 5: Create initialization file (lib/datalyr.ts or similar)
+Step 4: Install SDK package using detected package manager (usually just @datalyr/web)
+Step 5: Create initialization file (for Next.js App Router: app/providers.tsx with 'use client')
 Step 6: Update entry point to import and initialize Datalyr
-Step 7: Update or create .env.local with workspace ID placeholder
+Step 7: Update or create .env.local with workspace ID
 Step 8: Call task_complete with summary of changes
 </workflow>
 
 <examples>
 <example name="nextjs-app-router">
-For Next.js 13+ with App Router, create app/providers.tsx:
+For Next.js 13+ with App Router:
+
+STEP 1: Create app/providers.tsx (Client Component):
 \`\`\`tsx
 'use client';
+
 import datalyr from '@datalyr/web';
 import { useEffect } from 'react';
 
 export function DatalyrProvider({ children }: { children: React.ReactNode }) {
   useEffect(() => {
+    // useEffect only runs on client, safe to initialize here
     datalyr.init({
       workspaceId: process.env.NEXT_PUBLIC_DATALYR_WORKSPACE_ID!,
       debug: process.env.NODE_ENV === 'development',
     });
   }, []);
+
   return <>{children}</>;
 }
 \`\`\`
-Then wrap children in app/layout.tsx with <DatalyrProvider>.
+
+STEP 2: Update app/layout.tsx (stays as Server Component):
+\`\`\`tsx
+import { DatalyrProvider } from './providers';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <DatalyrProvider>
+          {children}
+        </DatalyrProvider>
+      </body>
+    </html>
+  );
+}
+\`\`\`
+
+STEP 3: Add to .env.local:
+\`\`\`
+NEXT_PUBLIC_DATALYR_WORKSPACE_ID=your_workspace_id
+\`\`\`
+
+CRITICAL: The 'use client' directive MUST be at the very top of providers.tsx, before any imports!
+</example>
+
+<example name="nextjs-pages-router">
+For Next.js Pages Router (pages/ directory):
+
+STEP 1: Create lib/datalyr.ts:
+\`\`\`ts
+import datalyr from '@datalyr/web';
+
+let initialized = false;
+
+export function initDatalyr() {
+  if (initialized || typeof window === 'undefined') return;
+
+  datalyr.init({
+    workspaceId: process.env.NEXT_PUBLIC_DATALYR_WORKSPACE_ID!,
+    debug: process.env.NODE_ENV === 'development',
+  });
+
+  initialized = true;
+}
+
+export { datalyr };
+\`\`\`
+
+STEP 2: Update pages/_app.tsx:
+\`\`\`tsx
+import { useEffect } from 'react';
+import { initDatalyr } from '../lib/datalyr';
+import type { AppProps } from 'next/app';
+
+export default function App({ Component, pageProps }: AppProps) {
+  useEffect(() => {
+    initDatalyr();
+  }, []);
+
+  return <Component {...pageProps} />;
+}
+\`\`\`
 </example>
 
 <example name="react-vite">
@@ -197,7 +299,16 @@ export function initDatalyr() {
 
 export { datalyr };
 \`\`\`
-Then call initDatalyr() at the top of src/main.tsx.
+
+Update src/main.tsx:
+\`\`\`tsx
+import { initDatalyr } from './lib/datalyr';
+
+// Initialize before rendering
+initDatalyr();
+
+// ... rest of app
+\`\`\`
 </example>
 
 <example name="react-native">
@@ -205,20 +316,66 @@ For React Native, create src/utils/datalyr.ts:
 \`\`\`ts
 import { Datalyr } from '@datalyr/react-native';
 
-export async function initDatalyr(apiKey: string) {
+let initialized = false;
+
+export async function initDatalyr() {
+  if (initialized) return;
+
+  const apiKey = process.env.DATALYR_API_KEY;
+  if (!apiKey) {
+    console.warn('[Datalyr] API key not configured');
+    return;
+  }
+
   await Datalyr.initialize({
     apiKey,
     enableAutoEvents: true,
     debug: __DEV__,
   });
+
+  initialized = true;
 }
 
 export { Datalyr };
 \`\`\`
-Then call initDatalyr() in App.tsx useEffect.
+
+Update App.tsx:
+\`\`\`tsx
+import { useEffect } from 'react';
+import { initDatalyr } from './src/utils/datalyr';
+
+export default function App() {
+  useEffect(() => {
+    initDatalyr();
+  }, []);
+
+  return (/* your app */);
+}
+\`\`\`
 </example>
 </examples>
 
+<common-mistakes>
+AVOID THESE MISTAKES:
+
+1. WRONG: Adding useEffect directly in layout.tsx without 'use client'
+   This will error: "useEffect only works in Client Components"
+
+2. WRONG: Putting 'use client' after imports
+   The directive MUST be the first line of the file
+
+3. WRONG: Trying to access window/document at module level
+   Always use useEffect or check typeof window !== 'undefined'
+
+4. WRONG: Installing @datalyr/api when only client tracking is needed
+   Most apps only need @datalyr/web
+
+5. WRONG: Using the wrong env var prefix
+   - Next.js: NEXT_PUBLIC_
+   - Vite: VITE_
+   - SvelteKit: PUBLIC_
+</common-mistakes>
+
 <signals>
 When complete: ${AGENT_SIGNALS.SUCCESS}
 On error: ${AGENT_SIGNALS.ERROR_FAILED}
@@ -370,7 +527,6 @@ function getSDKsForFramework(framework) {
     case "sveltekit":
     case "nuxt":
     case "astro":
-      return ["@datalyr/web", "@datalyr/api"];
     case "react":
     case "react-vite":
     case "svelte":
@@ -1008,17 +1164,12 @@ var NEXTJS_CONFIG = {
   id: "nextjs",
   name: "Next.js",
   detectPackage: "next",
-  sdks: ["@datalyr/web", "@datalyr/api"],
+  sdks: ["@datalyr/web"],
   envVars: [
     {
       key: "NEXT_PUBLIC_DATALYR_WORKSPACE_ID",
       description: "Your Datalyr workspace ID",
       isPublic: true
-    },
-    {
-      key: "DATALYR_API_KEY",
-      description: "Server-side API key",
-      isPublic: false
     }
   ],
   estimatedTime: 3,
@@ -1083,17 +1234,12 @@ var SVELTEKIT_CONFIG = {
   id: "sveltekit",
   name: "SvelteKit",
   detectPackage: "@sveltejs/kit",
-  sdks: ["@datalyr/web", "@datalyr/api"],
+  sdks: ["@datalyr/web"],
   envVars: [
     {
       key: "PUBLIC_DATALYR_WORKSPACE_ID",
       description: "Your Datalyr workspace ID",
       isPublic: true
-    },
-    {
-      key: "DATALYR_API_KEY",
-      description: "Server-side API key",
-      isPublic: false
     }
   ],
   estimatedTime: 3,
@@ -1146,17 +1292,12 @@ var NUXT_CONFIG = {
   id: "nuxt",
   name: "Nuxt",
   detectPackage: "nuxt",
-  sdks: ["@datalyr/web", "@datalyr/api"],
+  sdks: ["@datalyr/web"],
   envVars: [
     {
       key: "NUXT_PUBLIC_DATALYR_WORKSPACE_ID",
       description: "Your Datalyr workspace ID",
       isPublic: true
-    },
-    {
-      key: "DATALYR_API_KEY",
-      description: "Server-side API key",
-      isPublic: false
     }
   ],
   estimatedTime: 3,
@@ -1171,17 +1312,12 @@ var REMIX_CONFIG = {
   id: "remix",
   name: "Remix",
   detectPackage: "@remix-run/react",
-  sdks: ["@datalyr/web", "@datalyr/api"],
+  sdks: ["@datalyr/web"],
   envVars: [
     {
       key: "DATALYR_WORKSPACE_ID",
       description: "Your Datalyr workspace ID",
       isPublic: true
-    },
-    {
-      key: "DATALYR_API_KEY",
-      description: "Server-side API key",
-      isPublic: false
     }
   ],
   estimatedTime: 3,