@jmruthers/pace-core 0.6.4 → 0.6.6

package/docs/getting-started/dependencies.md

@@ -0,0 +1,650 @@
+---
+lastUpdated: 2025-01-28T00:00:00+00:00
+version: 0.6.5
+reviewedBy: dependency-clarity-audit
+---
+
+# PACE Core Dependencies Guide
+
+> **📚 Complete Dependency Reference** | [← Back to Documentation](../README.md) | [Installation Guide](./installation-guide.md) | [🔍 Dependency Audit Guide](./dependency-audit-guide.md)
+
+**This guide clearly explains which dependencies you need to install and which are already included in pace-core.**
+
+> **🎯 New to auditing?** Start with the [Dependency Audit Guide](./dependency-audit-guide.md) for a quick overview and step-by-step instructions.
+
+## 🎯 Quick Start: Audit Your Dependencies
+
+**This document is the single source of truth for pace-core dependencies.** Use it to audit your consuming app's dependencies.
+
+> **🎯 New to auditing?** Start with the [Dependency Audit Guide](./dependency-audit-guide.md) for a quick overview and step-by-step instructions.
+
+**Quick Audit Checklist:**
+1. ✅ Verify pace-core version (`^0.6.5` or later)
+2. ❌ Remove included dependencies (see [Included Dependencies](#-already-included-do-not-install) below)
+3. ✅ Install required core dependencies (see [Required Peer Dependencies](#-required-peer-dependencies-must-install) below)
+4. ⚠️ Install optional dependencies only if you use those features
+5. 🔄 Update code to use pace-core exports instead of direct imports
+
+**For detailed guidance:**
+- [Dependency Audit Guide](./dependency-audit-guide.md) - Quick overview and 5-step process
+- [Consuming Apps Audit Checklist](../../audit/consuming-apps-audit-checklist.md) - Step-by-step checklist with commands
+
+---
+
+## ⚠️ CRITICAL: pace-core Version Requirement
+
+**You MUST use `@jmruthers/pace-core@^0.6.5` or later.** Older versions may have incompatible dependencies or missing features.
+
+```bash
+# ✅ Ensure you're using the latest version
+npm install @jmruthers/pace-core@latest
+
+# Verify your installed version
+npm ls @jmruthers/pace-core
+```
+
+**Why this matters:**
+- Dependency structure may change between versions
+- Security patches and bug fixes are included in newer versions
+- New features require specific dependency versions
+- This guide is accurate for pace-core v0.6.5+
+
+## Quick Reference
+
+### ✅ Already Included (DO NOT Install)
+
+These packages are included as dependencies in `@jmruthers/pace-core` and **should NOT** be installed in your consuming app:
+
+```bash
+# ❌ DO NOT install these - they're already included
+# @supabase/supabase-js (use createBaseClient from pace-core instead)
+# @radix-ui/react-checkbox (use pace-core components instead)
+# @radix-ui/react-label (use pace-core components instead)
+# @radix-ui/react-slot (use pace-core components instead)
+# @radix-ui/react-switch (use pace-core components instead)
+# @radix-ui/react-tabs (use pace-core components instead)
+# @radix-ui/react-toast (use pace-core components instead)
+# @radix-ui/react-tooltip (use pace-core components instead)
+# lucide-react (use @jmruthers/pace-core/icons instead)
+# @tanstack/react-virtual
+# @hookform/resolvers
+# lodash.debounce
+# lodash.throttle
+# papaparse
+# react-is
+```
+
+> **Note**: 
+> - `@supabase/supabase-js` is **included** - Use `createBaseClient()` from `@jmruthers/pace-core` instead of importing `createClient` directly (security enforcement).
+> - `@radix-ui/*` packages are **included** - Use pace-core components instead of importing Radix UI primitives directly (consistency enforcement).
+> - `lucide-react` is **included** - Use `@jmruthers/pace-core/icons` instead of importing icons directly (consistency enforcement).
+> - `@tanstack/react-query` is a **peer dependency** (see below) because consuming apps need direct access to `QueryClient`, `QueryClientProvider`, and React Query hooks.
+> - `date-fns` and `date-fns-tz` are **peer dependencies** (see below) because consuming apps may need direct access to date-fns functions that pace-core doesn't export.
+
+### ⚠️ Required Peer Dependencies (MUST Install)
+
+These packages are **required** for pace-core to function. You **MUST** install them in your consuming app:
+
+**Minimum Versions (Required):**
+```bash
+# ✅ REQUIRED - Minimum versions (^ allows compatible updates)
+npm install react@^19.0.0 react-dom@^19.0.0
+npm install @tanstack/react-query@^5.90.0
+npm install @tanstack/react-table@^8.0.0
+npm install date-fns@^3.0.0 date-fns-tz@^3.0.0
+npm install @radix-ui/react-checkbox@^1.0.0
+npm install @radix-ui/react-label@^2.0.0
+npm install @radix-ui/react-slot@^1.0.0
+npm install @radix-ui/react-switch@^1.1.0
+npm install @radix-ui/react-tabs@^1.0.0
+npm install @radix-ui/react-toast@^1.0.0
+npm install @radix-ui/react-tooltip@^1.0.0
+npm install clsx@^2.0.0
+npm install lucide-react@^0.400.0
+npm install react-day-picker@^9.0.0
+npm install react-hook-form@^7.0.0
+npm install react-router-dom@^6.0.0
+npm install tailwind-merge@^2.0.0
+npm install tailwindcss@^4.0.0
+npm install zod@^3.20.0
+```
+
+**Recommended Specific Versions (For Maximum Compatibility):**
+```bash
+# ✅ RECOMMENDED - Specific tested versions
+npm install react@19.2.3 react-dom@19.2.3
+npm install @tanstack/react-query@^5.90.16
+npm install @tanstack/react-table@^8.20.0
+npm install date-fns@^3.0.0 date-fns-tz@^3.0.0
+npm install @radix-ui/react-checkbox@^1.1.2
+npm install @radix-ui/react-label@^2.1.1
+npm install @radix-ui/react-slot@^1.1.0
+npm install @radix-ui/react-switch@^1.1.1
+npm install @radix-ui/react-tabs@^1.1.1
+npm install @radix-ui/react-toast@^1.2.2
+npm install @radix-ui/react-tooltip@^1.1.3
+npm install clsx@^2.1.1
+npm install lucide-react@^0.468.0
+npm install react-day-picker@^9.4.3
+npm install react-hook-form@^7.54.2
+npm install react-router-dom@^6.28.0
+npm install tailwind-merge@^2.5.5
+npm install tailwindcss@^4.0.0
+npm install zod@^3.24.1
+```
+
+> **💡 Version Strategy**: Use `^` (caret) ranges for flexibility, or pin specific versions for maximum stability. React 19.2.3+ is recommended to avoid security vulnerabilities in earlier 19.x versions.
+
+### 📦 One-Line Install (All Required Peers)
+
+```bash
+npm install react react-dom @tanstack/react-query @tanstack/react-table clsx date-fns date-fns-tz react-day-picker react-hook-form react-router-dom tailwind-merge tailwindcss zod
+```
+
+> **Note**: Only install peer dependencies that your app actually uses. For example:
+> - If you don't use DataTable, you may not need `@tanstack/react-table`
+> - If you don't use forms, you may not need `react-hook-form`
+> - If you don't use date pickers, you may not need `react-day-picker`
+> - If you don't use date formatting, you may not need `date-fns`/`date-fns-tz`
+
+---
+
+## Detailed Breakdown
+
+### Included Dependencies
+
+These are bundled with pace-core. Installing them separately will create duplicate dependencies and potential version conflicts.
+
+| Package | Version | Used For |
+|---------|---------|----------|
+| `@supabase/supabase-js` | ^2.89.0 | Supabase client (use `createBaseClient()` from pace-core) |
+| `@radix-ui/react-checkbox` | ^1.0.0 | Checkbox primitive (use pace-core `Checkbox` component) |
+| `@radix-ui/react-label` | ^2.0.0 | Label primitive (use pace-core `Label` component) |
+| `@radix-ui/react-slot` | ^1.0.0 | Slot primitive (used by pace-core components) |
+| `@radix-ui/react-switch` | ^1.1.0 | Switch primitive (use pace-core `Switch` component) |
+| `@radix-ui/react-tabs` | ^1.0.0 | Tabs primitive (use pace-core `Tabs` component) |
+| `@radix-ui/react-toast` | ^1.0.0 | Toast primitive (use pace-core `Toast` component) |
+| `@radix-ui/react-tooltip` | ^1.0.0 | Tooltip primitive (use pace-core `Tooltip` component) |
+| `lucide-react` | ^0.400.0 | Icon library (use `@jmruthers/pace-core/icons`) |
+| `@tanstack/react-virtual` | ^3.13.16 | Virtual scrolling for DataTable performance |
+| `@hookform/resolvers` | ^3.9.0 | Form validation with Zod |
+| `lodash.debounce` | ^4.0.8 | Input debouncing |
+| `lodash.throttle` | ^4.1.1 | Event throttling |
+| `papaparse` | ^5.5.3 | CSV parsing (DataTable export) |
+| `react-is` | ^19.2.3 | React element type checking |
+
+**Why these are included:**
+- They're core to pace-core's functionality
+- Ensures version compatibility
+- Prevents duplicate installations
+- Simplifies consuming app setup
+
+### Required Peer Dependencies
+
+These must be installed by consuming apps because:
+
+1. **React & React DOM** - Core framework (peer dependency to allow React 19+)
+2. **@tanstack/react-query** - Data fetching, caching, state management (peer to allow app-level QueryClient configuration)
+3. **date-fns & date-fns-tz** - Date formatting and timezone utilities (peer to allow apps to use date-fns functions directly)
+4. **@tanstack/react-table** - DataTable component functionality
+5. **react-router-dom** - Navigation and routing (peer to allow app-level routing)
+6. **tailwindcss** - Styling system (peer to allow app-level Tailwind config)
+7. **Other utilities** - Used throughout pace-core components
+
+**Note**: `@supabase/supabase-js`, `@radix-ui/*` packages, and `lucide-react` are now **included dependencies** to enforce security and consistency. Use pace-core's exports instead:
+- `createBaseClient()` from `@jmruthers/pace-core` (instead of `createClient` from `@supabase/supabase-js`)
+- pace-core components (instead of `@radix-ui/*` primitives)
+- `@jmruthers/pace-core/icons` (instead of `lucide-react`)
+
+| Package | Minimum Version | Recommended Version | Used For | Required? |
+|---------|-----------------|---------------------|----------|----------|
+| `react` | ^19.0.0 | **19.2.3+** (security fixes) | React framework | ✅ Always |
+| `react-dom` | ^19.0.0 | **19.2.3+** (security fixes) | React DOM rendering | ✅ Always |
+| `react-router-dom` | ^6.0.0 | ^6.28.0 | Routing and navigation | ✅ Always |
+| `tailwindcss` | ^4.0.0 | ^4.0.0 | CSS framework | ✅ Always |
+| `@tanstack/react-query` | ^5.90.0 | ^5.90.16 | Data fetching, caching, QueryClient configuration | ⚠️ If using data fetching |
+| `@tanstack/react-table` | ^8.0.0 | ^8.20.0 | DataTable component | ⚠️ If using DataTable |
+| `date-fns` | ^3.0.0 | ^3.0.0 | Date formatting and manipulation | ⚠️ If using date formatting |
+| `date-fns-tz` | ^3.0.0 | ^3.0.0 | Timezone-aware date operations | ⚠️ If using timezone features |
+| `react-hook-form` | ^7.0.0 | ^7.54.2 | Form handling | ⚠️ If using forms |
+| `react-day-picker` | ^9.0.0 | ^9.4.3 | Calendar/date picker | ⚠️ If using date pickers |
+| `zod` | ^3.20.0 | ^3.24.1 | Schema validation | ⚠️ If using validation |
+| `clsx` | ^2.0.0 | ^2.1.1 | Conditional className utility | ⚠️ If using className utilities |
+| `tailwind-merge` | ^2.0.0 | ^2.5.5 | Tailwind class merging utility | ⚠️ If using class merging |
+
+> **⚠️ React Version Security**: React 19.0.0 through 19.2.0 had security vulnerabilities (CVE-2025-55182). **You MUST use React 19.2.3 or later** to avoid these issues.
+
+**Why these are peer dependencies:**
+- Allows consuming apps to control versions
+- Prevents duplicate installations
+- Enables app-level configuration (e.g., Tailwind config)
+- Ensures single instance of React/React Router
+
+---
+
+## Installation Checklist
+
+Use this checklist to verify your installation:
+
+### ✅ Step 1: Install pace-core (Latest Version)
+
+```bash
+# Install latest version
+npm install @jmruthers/pace-core@latest
+
+# Or install specific minimum version
+npm install @jmruthers/pace-core@^0.6.5
+
+# Verify installed version
+npm ls @jmruthers/pace-core
+```
+
+**Expected output:** Should show `@jmruthers/pace-core@0.6.5` or higher.
+
+### ✅ Step 2: Install Required Peer Dependencies
+
+**Install core dependencies (always required):**
+```bash
+npm install react react-dom react-router-dom tailwindcss
+```
+
+**Install optional dependencies (only if you use these features):**
+```bash
+# If using data fetching
+npm install @tanstack/react-query
+
+# If using DataTable
+npm install @tanstack/react-table
+
+# If using date formatting
+npm install date-fns date-fns-tz
+
+# If using forms
+npm install react-hook-form
+
+# If using date pickers
+npm install react-day-picker
+
+# If using validation
+npm install zod
+
+# If using className utilities
+npm install clsx tailwind-merge
+```
+
+### ✅ Step 3: Install Tailwind v4 (Dev Dependency)
+
+```bash
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+### ❌ Step 4: Verify You Did NOT Install Included Dependencies
+
+Check your `package.json` - you should **NOT** have these as dependencies:
+
+- ❌ `@supabase/supabase-js` (already in pace-core - use `createBaseClient()` from pace-core)
+- ❌ `@radix-ui/react-checkbox` (already in pace-core - use pace-core `Checkbox` component)
+- ❌ `@radix-ui/react-label` (already in pace-core - use pace-core `Label` component)
+- ❌ `@radix-ui/react-slot` (already in pace-core - used by pace-core components)
+- ❌ `@radix-ui/react-switch` (already in pace-core - use pace-core `Switch` component)
+- ❌ `@radix-ui/react-tabs` (already in pace-core - use pace-core `Tabs` component)
+- ❌ `@radix-ui/react-toast` (already in pace-core - use pace-core `Toast` component)
+- ❌ `@radix-ui/react-tooltip` (already in pace-core - use pace-core `Tooltip` component)
+- ❌ `lucide-react` (already in pace-core - use `@jmruthers/pace-core/icons`)
+- ❌ `@tanstack/react-virtual` (already in pace-core)
+- ❌ `@hookform/resolvers` (already in pace-core)
+- ❌ `lodash.debounce` (already in pace-core)
+- ❌ `lodash.throttle` (already in pace-core)
+- ❌ `papaparse` (already in pace-core)
+- ❌ `react-is` (already in pace-core)
+- ❌ `@hookform/resolvers` (already in pace-core)
+- ❌ `date-fns` (already in pace-core)
+- ❌ `date-fns-tz` (already in pace-core)
+- ❌ `lodash.debounce` (already in pace-core)
+- ❌ `lodash.throttle` (already in pace-core)
+- ❌ `papaparse` (already in pace-core)
+- ❌ `react-is` (already in pace-core)
+
+If you find any of these in your `package.json`, remove them:
+
+```bash
+npm uninstall @supabase/supabase-js @radix-ui/react-checkbox @radix-ui/react-label @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react @tanstack/react-virtual @hookform/resolvers lodash.debounce lodash.throttle papaparse react-is
+```
+
+> **Note**: 
+> - `@supabase/supabase-js` is **included** - Use `createBaseClient()` from `@jmruthers/pace-core` instead.
+> - `@radix-ui/*` packages are **included** - Use pace-core components instead.
+> - `lucide-react` is **included** - Use `@jmruthers/pace-core/icons` instead.
+> - `@tanstack/react-query` is a **peer dependency** and should be installed (see [Required Peer Dependencies](#-required-peer-dependencies-must-install) above).
+> - `date-fns` and `date-fns-tz` are **peer dependencies** and should be installed (see [Required Peer Dependencies](#-required-peer-dependencies-must-install) above).
+
+---
+
+## Common Mistakes
+
+### ❌ Mistake 1: Installing Included Dependencies
+
+**Problem:** Installing packages that are already included in pace-core
+
+```bash
+# ❌ WRONG - Don't do this
+npm install @supabase/supabase-js @radix-ui/react-checkbox lucide-react @tanstack/react-virtual
+```
+
+**Why it's wrong:**
+- Creates duplicate dependencies
+- Can cause version conflicts
+- Increases bundle size unnecessarily
+- May cause runtime errors
+- **Security risk**: Allows bypassing pace-core security rules
+- **Consistency risk**: Allows bypassing pace-core components/icons
+
+**Solution:** Remove them from your `package.json` and use pace-core exports instead:
+
+```bash
+npm uninstall @supabase/supabase-js @radix-ui/react-checkbox @radix-ui/react-label @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react @tanstack/react-virtual @hookform/resolvers lodash.debounce lodash.throttle papaparse react-is
+```
+
+**Use pace-core exports instead:**
+```tsx
+// ✅ CORRECT: Use pace-core exports
+import { createBaseClient } from '@jmruthers/pace-core';
+import { Button, Checkbox, Label } from '@jmruthers/pace-core';
+import { ChevronDown, Edit } from '@jmruthers/pace-core/icons';
+
+// ❌ WRONG: Direct imports (will fail - packages are included, not peer)
+import { createClient } from '@supabase/supabase-js';
+import { Checkbox } from '@radix-ui/react-checkbox';
+import { ChevronDown } from 'lucide-react';
+```
+
+> **Note**: 
+> - `@tanstack/react-query` is a **peer dependency** and should be installed. See [Required Peer Dependencies](#-required-peer-dependencies-must-install) above.
+> - `date-fns` and `date-fns-tz` are **peer dependencies** and should be installed. See [Required Peer Dependencies](#-required-peer-dependencies-must-install) above.
+
+### ❌ Mistake 2: Missing Required Peer Dependencies
+
+**Problem:** Not installing required peer dependencies
+
+**Symptoms:**
+- Runtime errors: "Cannot find module '@radix-ui/react-checkbox'"
+- TypeScript errors: "Module not found"
+- Components don't render correctly
+
+**Solution:** Install all required peer dependencies (see [Required Peer Dependencies](#-required-peer-dependencies-must-install) above)
+
+### ❌ Mistake 3: Wrong Versions
+
+**Problem:** Installing incompatible versions of peer dependencies
+
+**Example:**
+```bash
+# ❌ WRONG - React 18 when pace-core requires React 19
+npm install react@^18.0.0
+
+# ❌ WRONG - React 19.0.0-19.2.0 have security vulnerabilities
+npm install react@19.0.0
+```
+
+**Solution:** Use compatible versions specified in peer dependencies:
+
+```bash
+# ✅ CORRECT - Minimum version
+npm install react@^19.0.0 react-dom@^19.0.0
+
+# ✅ BETTER - Recommended secure version
+npm install react@19.2.3 react-dom@19.2.3
+```
+
+### ❌ Mistake 4: Installing Optional Dependencies
+
+**Problem:** Installing packages that aren't needed
+
+**Note:** Currently, all peer dependencies are required. There are no optional peer dependencies.
+
+---
+
+## Verification
+
+### Check Your Installation
+
+Run this command to verify core peer dependencies are installed:
+
+```bash
+# Check core dependencies (always required)
+npm ls react react-dom react-router-dom tailwindcss
+
+# Check optional dependencies (only if you use these features)
+npm ls @tanstack/react-query @tanstack/react-table date-fns date-fns-tz react-day-picker react-hook-form zod clsx tailwind-merge
+```
+
+### Check for Duplicates
+
+Verify you don't have duplicate dependencies:
+
+```bash
+# Check for included dependencies that shouldn't be installed
+npm ls @supabase/supabase-js @radix-ui/react-checkbox @radix-ui/react-label @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip lucide-react @tanstack/react-virtual @hookform/resolvers lodash.debounce lodash.throttle papaparse react-is
+```
+
+If these show up as direct dependencies (not under `@jmruthers/pace-core`), remove them and use pace-core exports instead.
+
+> **Note**: 
+> - `@tanstack/react-query` should be a direct dependency (it's a peer dependency).
+> - `date-fns` and `date-fns-tz` should be direct dependencies (they're peer dependencies).
+> - `@supabase/supabase-js`, `@radix-ui/*`, and `lucide-react` should NOT be direct dependencies (they're included - use pace-core exports).
+
+### Verify pace-core Version
+
+Check that you're using a compatible version of pace-core:
+
+```bash
+# Check installed version
+npm ls @jmruthers/pace-core
+
+# Check latest available version
+npm view @jmruthers/pace-core version
+
+# Compare versions
+npm outdated @jmruthers/pace-core
+```
+
+**Required:** You must be using `@jmruthers/pace-core@^0.6.5` or later.
+
+### Verify Version Compatibility
+
+Check that your peer dependency versions match pace-core requirements:
+
+```bash
+# Check key dependencies
+npm ls react react-dom @tanstack/react-query date-fns date-fns-tz tailwindcss @jmruthers/pace-core
+
+# Check all peer dependencies
+npm ls react react-dom @tanstack/react-query @tanstack/react-table clsx date-fns date-fns-tz react-day-picker react-hook-form react-router-dom tailwind-merge tailwindcss zod
+```
+
+All should show versions compatible with pace-core's peer dependency requirements.
+
+**Critical Check:** Ensure React is 19.2.3 or later:
+```bash
+npm ls react
+# Should show: react@19.2.3 or higher
+```
+
+---
+
+## Troubleshooting
+
+### Issue: "Cannot find module '@radix-ui/react-checkbox'" or similar Radix UI errors
+
+**Cause:** `@radix-ui/*` packages are now **included dependencies** in pace-core. You should NOT import them directly.
+
+**Solution:**
+1. **DO NOT** install `@radix-ui/*` packages - they're included in pace-core
+2. **Use** pace-core components instead:
+
+```tsx
+// ✅ CORRECT: Use pace-core components
+import { Checkbox, Label, Switch, Tabs, Toast, Tooltip } from '@jmruthers/pace-core';
+
+// ❌ WRONG: Direct Radix UI import (will fail - packages are included, not peer)
+import { Checkbox } from '@radix-ui/react-checkbox';
+```
+
+**Note**: `@radix-ui/*` packages are included dependencies to enforce consistency. Use pace-core components instead.
+
+### Issue: "Module not found: '@supabase/supabase-js'" or "Rollup failed to resolve import '@supabase/supabase-js'"
+
+**Cause:** `@supabase/supabase-js` is now an **included dependency** in pace-core. You should NOT import it directly.
+
+**Solution:**
+1. **Remove** `@supabase/supabase-js` from your `package.json` if you have it installed
+2. **Use** `createBaseClient()` from pace-core instead:
+
+```tsx
+// ✅ CORRECT: Use pace-core's createBaseClient
+import { createBaseClient } from '@jmruthers/pace-core';
+
+const supabase = createBaseClient(
+  import.meta.env.VITE_SUPABASE_URL,
+  import.meta.env.VITE_SUPABASE_PUBLISHABLE_KEY
+);
+
+// ❌ WRONG: Direct import (will fail - package is included, not peer)
+import { createClient } from '@supabase/supabase-js';
+```
+
+**Why:** 
+- `@supabase/supabase-js` is included to enforce security rules
+- Use `createBaseClient()` which enforces the allowed exception pattern
+- **Do NOT** add it to Vite `optimizeDeps` - that won't work and violates security rules
+
+**Files to check:**
+- `src/lib/supabase.ts`
+- `src/main.tsx`
+- Any file importing `createClient` from `@supabase/supabase-js`
+
+### Issue: Build-Time Resolution Errors
+
+**Cause:** Some bundlers (Vite/Rollup) require packages to be in direct dependencies for build-time module resolution.
+
+**Symptoms:**
+- Build errors: "Failed to resolve import '@tanstack/react-query'"
+- Build errors: "Failed to resolve import 'date-fns'"
+- Build errors: `[vite]: Rollup failed to resolve import "@tanstack/react-query"`
+
+**Solution:** 
+- `@tanstack/react-query`, `date-fns`, and `date-fns-tz` are **peer dependencies** and **MUST be installed** as direct dependencies in your `package.json`. See [Required Peer Dependencies](#-required-peer-dependencies-must-install) above.
+- **Do NOT** externalize them in Vite config - install them as dependencies instead.
+- **Do NOT** add them to `optimizeDeps.include` - that won't fix the build error.
+- `@supabase/supabase-js`, `@radix-ui/*`, and `lucide-react` are included dependencies - use pace-core exports instead of importing directly.
+
+**Common Mistake:**
+If you removed `@tanstack/react-query` during cleanup thinking it was included, you need to reinstall it:
+
+```bash
+# ✅ CORRECT: Install as peer dependency
+npm install @tanstack/react-query@^5.90.0
+
+# ❌ WRONG: Don't externalize in vite.config.ts
+# build: { rollupOptions: { external: ['@tanstack/react-query'] } }
+
+# ❌ WRONG: Don't add to optimizeDeps
+# optimizeDeps: { include: ['@tanstack/react-query'] }
+```
+
+**Why:** 
+- Peer dependencies must be explicitly installed in your `package.json`
+- Peer dependencies are **NOT** transitive dependencies - they won't be available unless you install them
+- Externalizing or adding to `optimizeDeps` are workarounds that won't work - the dependency must be in `package.json`
+- This is the standard approach for peer dependencies
+
+### Issue: Version conflicts
+
+**Cause:** Incompatible versions of peer dependencies
+
+**Solution:**
+1. Check required versions in pace-core's `package.json`
+2. Update your dependencies to match:
+   ```bash
+   npm install react@^19.0.0 react-dom@^19.0.0
+   ```
+
+### Issue: Duplicate React instances
+
+**Cause:** Multiple React installations
+
+**Solution:**
+1. Check for duplicates: `npm ls react`
+2. Remove duplicate installations
+3. Ensure Vite config deduplicates React (see [Installation Guide](./installation-guide.md))
+
+---
+
+## Reference
+
+### View Current Dependencies
+
+To see pace-core's current dependencies and peer dependencies:
+
+```bash
+# View pace-core package.json
+npm view @jmruthers/pace-core peerDependencies
+npm view @jmruthers/pace-core dependencies
+```
+
+Or check the source:
+- **Peer Dependencies:** `packages/core/package.json` → `peerDependencies`
+- **Included Dependencies:** `packages/core/package.json` → `dependencies`
+
+### Package.json Structure
+
+```json
+{
+  "peerDependencies": {
+    // ⚠️ REQUIRED - Install these in your app
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@tanstack/react-query": "^5.90.0",
+    "date-fns": "^3.0.0",
+    "date-fns-tz": "^3.0.0",
+    // ... other required peers
+  },
+  "dependencies": {
+    // ✅ INCLUDED - Already in pace-core, don't install
+    // Use pace-core exports instead:
+    // - @supabase/supabase-js → use createBaseClient() from pace-core
+    // - @radix-ui/* → use pace-core components
+    // - lucide-react → use @jmruthers/pace-core/icons
+    "@supabase/supabase-js": "^2.89.0",
+    "@radix-ui/react-checkbox": "^1.0.0",
+    // ... other included deps
+  }
+}
+```
+
+
+---
+
+## Summary
+
+| Category | Action | Packages |
+|----------|--------|----------|
+| **pace-core** | ✅ **MUST** use latest | `@jmruthers/pace-core@^0.6.5` (use `@latest` to get current version) |
+| **Included** | ❌ **DO NOT** install | `@supabase/supabase-js` (use `createBaseClient()`), `@radix-ui/*` (use pace-core components), `lucide-react` (use `@jmruthers/pace-core/icons`), `@tanstack/react-virtual`, `@hookform/resolvers`, `lodash.debounce`, `lodash.throttle`, `papaparse`, `react-is` |
+| **Required Peers (Always)** | ✅ **MUST** install | `react@19.2.3+`, `react-dom@19.2.3+`, `react-router-dom@^6.0.0`, `tailwindcss@^4.0.0` |
+| **Optional Peers (If Used)** | ⚠️ **Install if needed** | `@tanstack/react-query@^5.90.0` (data fetching), `@tanstack/react-table@^8.0.0` (DataTable), `date-fns@^3.0.0` (date formatting), `date-fns-tz@^3.0.0` (timezone), `react-hook-form@^7.0.0` (forms), `react-day-picker@^9.0.0` (date pickers), `zod@^3.20.0` (validation), `clsx@^2.0.0` (className utility), `tailwind-merge@^2.0.0` (class merging) |
+| **Dev Dependency** | ✅ **MUST** install | `@tailwindcss/vite`, `tailwindcss@^4.0.0` |
+
+---
+
+**Last Updated:** 2025-01-28 | **Version:** v0.6.5
+
+**Next Steps:**
+- [Consuming Apps Audit Checklist](../../audit/consuming-apps-audit-checklist.md) - **Use this checklist to audit your dependencies**
+- [Installation Guide](./installation-guide.md) - Complete setup instructions
+- [Quick Start](./quick-start.md) - Build your first app
+- [Troubleshooting](../troubleshooting/README.md) - Fix common issues
+
+**This document is the single source of truth for pace-core dependencies.**
+