npm - @odvi/create-dtt-framework - Versions diffs - 0.1.3 → 0.1.5 - Mend

@odvi/create-dtt-framework 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (111) hide show

package/dist/commands/create.d.ts.map +1 -1
package/dist/commands/create.js +16 -13
package/dist/commands/create.js.map +1 -1
package/package.json +3 -2
package/template/.env.example +103 -0
package/template/components.json +22 -0
package/template/docs/framework/01-overview.md +289 -0
package/template/docs/framework/02-techstack.md +503 -0
package/template/docs/framework/api-layer.md +681 -0
package/template/docs/framework/clerk-authentication.md +649 -0
package/template/docs/framework/cli-installation.md +564 -0
package/template/docs/framework/deployment/ci-cd.md +907 -0
package/template/docs/framework/deployment/digitalocean.md +991 -0
package/template/docs/framework/deployment/domain-setup.md +972 -0
package/template/docs/framework/deployment/environment-variables.md +863 -0
package/template/docs/framework/deployment/monitoring.md +927 -0
package/template/docs/framework/deployment/production-checklist.md +649 -0
package/template/docs/framework/deployment/vercel.md +791 -0
package/template/docs/framework/environment-variables.md +658 -0
package/template/docs/framework/health-check-system.md +582 -0
package/template/docs/framework/implementation.md +559 -0
package/template/docs/framework/snowflake-integration.md +591 -0
package/template/docs/framework/state-management.md +615 -0
package/template/docs/framework/supabase-integration.md +581 -0
package/template/docs/framework/testing-guide.md +544 -0
package/template/docs/framework/what-did-i-miss.md +526 -0
package/template/drizzle.config.ts +12 -0
package/template/next.config.js +21 -0
package/template/postcss.config.js +5 -0
package/template/prettier.config.js +4 -0
package/template/public/favicon.ico +0 -0
package/template/src/app/(auth)/layout.tsx +4 -0
package/template/src/app/(auth)/sign-in/[[...sign-in]]/page.tsx +10 -0
package/template/src/app/(auth)/sign-up/[[...sign-up]]/page.tsx +10 -0
package/template/src/app/(dashboard)/dashboard/page.tsx +8 -0
package/template/src/app/(dashboard)/health/page.tsx +16 -0
package/template/src/app/(dashboard)/layout.tsx +17 -0
package/template/src/app/api/[[...route]]/route.ts +11 -0
package/template/src/app/api/debug-files/route.ts +33 -0
package/template/src/app/api/webhooks/clerk/route.ts +112 -0
package/template/src/app/layout.tsx +28 -0
package/template/src/app/page.tsx +12 -0
package/template/src/app/providers.tsx +20 -0
package/template/src/components/layouts/navbar.tsx +14 -0
package/template/src/components/shared/loading-spinner.tsx +6 -0
package/template/src/components/ui/badge.tsx +46 -0
package/template/src/components/ui/button.tsx +62 -0
package/template/src/components/ui/card.tsx +92 -0
package/template/src/components/ui/collapsible.tsx +33 -0
package/template/src/components/ui/scroll-area.tsx +58 -0
package/template/src/components/ui/sheet.tsx +139 -0
package/template/src/config/__tests__/env.test.ts +166 -0
package/template/src/config/__tests__/site.test.ts +46 -0
package/template/src/config/env.ts +36 -0
package/template/src/config/site.ts +10 -0
package/template/src/env.js +44 -0
package/template/src/features/__tests__/health-check-config.test.ts +142 -0
package/template/src/features/__tests__/health-check-types.test.ts +201 -0
package/template/src/features/documentation/components/doc-sidebar.tsx +109 -0
package/template/src/features/documentation/components/doc-viewer.tsx +70 -0
package/template/src/features/documentation/index.tsx +92 -0
package/template/src/features/documentation/utils/doc-loader.ts +177 -0
package/template/src/features/health-check/components/health-dashboard.tsx +363 -0
package/template/src/features/health-check/config.ts +72 -0
package/template/src/features/health-check/index.ts +4 -0
package/template/src/features/health-check/stores/health-store.ts +14 -0
package/template/src/features/health-check/types.ts +18 -0
package/template/src/hooks/__tests__/use-debounce.test.tsx +28 -0
package/template/src/hooks/queries/use-health-checks.ts +16 -0
package/template/src/hooks/utils/use-debounce.ts +20 -0
package/template/src/lib/__tests__/utils.test.ts +52 -0
package/template/src/lib/__tests__/validators.test.ts +114 -0
package/template/src/lib/nextbank/client.ts +37 -0
package/template/src/lib/snowflake/client.ts +53 -0
package/template/src/lib/supabase/admin.ts +7 -0
package/template/src/lib/supabase/client.ts +7 -0
package/template/src/lib/supabase/server.ts +23 -0
package/template/src/lib/utils.ts +6 -0
package/template/src/lib/validators.ts +9 -0
package/template/src/middleware.ts +22 -0
package/template/src/server/api/index.ts +22 -0
package/template/src/server/api/middleware/auth.ts +19 -0
package/template/src/server/api/middleware/logger.ts +4 -0
package/template/src/server/api/routes/health/clerk.ts +214 -0
package/template/src/server/api/routes/health/database.ts +117 -0
package/template/src/server/api/routes/health/edge-functions.ts +75 -0
package/template/src/server/api/routes/health/framework.ts +45 -0
package/template/src/server/api/routes/health/index.ts +102 -0
package/template/src/server/api/routes/health/nextbank.ts +67 -0
package/template/src/server/api/routes/health/snowflake.ts +83 -0
package/template/src/server/api/routes/health/storage.ts +163 -0
package/template/src/server/api/routes/users.ts +95 -0
package/template/src/server/db/index.ts +17 -0
package/template/src/server/db/queries/users.ts +8 -0
package/template/src/server/db/schema/__tests__/health-checks.test.ts +31 -0
package/template/src/server/db/schema/__tests__/users.test.ts +46 -0
package/template/src/server/db/schema/health-checks.ts +11 -0
package/template/src/server/db/schema/index.ts +2 -0
package/template/src/server/db/schema/users.ts +16 -0
package/template/src/server/db/schema.ts +26 -0
package/template/src/stores/__tests__/ui-store.test.ts +87 -0
package/template/src/stores/ui-store.ts +14 -0
package/template/src/styles/globals.css +129 -0
package/template/src/test/mocks/clerk.ts +35 -0
package/template/src/test/mocks/snowflake.ts +28 -0
package/template/src/test/mocks/supabase.ts +37 -0
package/template/src/test/setup.ts +69 -0
package/template/src/test/utils/test-helpers.ts +158 -0
package/template/src/types/index.ts +14 -0
package/template/tsconfig.json +43 -0
package/template/vitest.config.ts +44 -0

package/template/docs/framework/state-management.md ADDED Viewed

@@ -0,0 +1,615 @@
+# DTT Framework - State Management
+## Overview
+The DTT Framework uses a dual state management approach:
+1. **TanStack Query** for server state (data from APIs, databases)
+2. **Zustand** for client state (UI state, temporary data)
+This separation of concerns provides a clear mental model and optimal performance.
+### Why This Approach?
+| State Type | Solution | Why |
+|------------|-----------|------|
+| **Server State** | TanStack Query | Caching, synchronization, background updates, deduplication |
+| **Client State** | Zustand | Simple, lightweight, no boilerplate, no context re-renders |
+---
+## TanStack Query for Server State
+### What is TanStack Query?
+[TanStack Query](https://tanstack.com/query/latest) (formerly React Query) is a powerful data synchronization library for React. It handles:
+- **Fetching**: Data fetching with loading states
+- **Caching**: Automatic caching and cache invalidation
+- **Synchronization**: Keeping data fresh with refetching
+- **Deduplication**: Avoiding duplicate requests
+- **Background Updates**: Silent refetching in the background
+### Installation
+```bash
+pnpm add @tanstack/react-query
+```
+### Setup
+**Create Query Client**
+Located at [`src/app/providers.tsx`](../../src/app/providers.tsx):
+```typescript
+'use client'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { ClerkProvider } from '@clerk/nextjs'
+import { useState } from 'react'
+export function Providers({ children }: { children: React.ReactNode }) {
+  const [queryClient] = useState(() => new QueryClient({
+    defaultOptions: {
+      queries: {
+        staleTime: 60 * 1000, // Data is fresh for 60 seconds
+        retry: 1 // Retry failed requests once
+      }
+    },
+  }))
+  return (
+    <ClerkProvider>
+      <QueryClientProvider client={queryClient}>
+        {children}
+      </QueryClientProvider>
+    </ClerkProvider>
+  )
+}
+```
+**Wrap App with Providers**
+```typescript
+// src/app/layout.tsx
+import { Providers } from './providers'
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+### Basic Usage
+**useQuery Hook**
+```typescript
+import { useQuery } from '@tanstack/react-query'
+function UsersList() {
+  const { data, isLoading, error, refetch } = useQuery({
+    queryKey: ['users'],
+    queryFn: async () => {
+      const response = await fetch('/api/users')
+      if (!response.ok) throw new Error('Failed to fetch users')
+      return response.json()
+    },
+  })
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+  return (
+    <div>
+      <button onClick={() => refetch()}>Refresh</button>
+      {data?.users?.map(user => (
+        <div key={user.id}>{user.email}</div>
+      ))}
+    </div>
+  )
+}
+```
+**useMutation Hook**
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+function CreateUserForm() {
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: async (userData: { name: string; email: string }) => {
+      const response = await fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(userData),
+      })
+      if (!response.ok) throw new Error('Failed to create user')
+      return response.json()
+    },
+    onSuccess: () => {
+      // Invalidate and refetch users query
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+  })
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    const formData = new FormData(e.target as HTMLFormElement)
+    mutation.mutate({
+      name: formData.get('name') as string,
+      email: formData.get('email') as string,
+    })
+  }
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="name" placeholder="Name" />
+      <input name="email" placeholder="Email" />
+      <button type="submit" disabled={mutation.isPending}>
+        {mutation.isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  )
+}
+```
+### Query Keys
+Query keys are used to identify and manage queries:
+```typescript
+// Simple key
+useQuery({ queryKey: ['users'], queryFn: fetchUsers })
+// Key with parameters
+useQuery({
+  queryKey: ['user', userId],
+  queryFn: () => fetchUser(userId)
+})
+// Complex key
+useQuery({
+  queryKey: ['posts', { page, limit }],
+  queryFn: () => fetchPosts(page, limit)
+})
+```
+### Cache Invalidation
+```typescript
+const queryClient = useQueryClient()
+// Invalidate specific query
+queryClient.invalidateQueries({ queryKey: ['users'] })
+// Invalidate all queries
+queryClient.invalidateQueries()
+// Invalidate queries matching a predicate
+queryClient.invalidateQueries({
+  predicate: (query) => query.queryKey[0] === 'users'
+})
+```
+### Prefetching
+```typescript
+const queryClient = useQueryClient()
+// Prefetch data before it's needed
+useEffect(() => {
+  queryClient.prefetchQuery({
+    queryKey: ['user', nextUserId],
+    queryFn: () => fetchUser(nextUserId),
+  })
+}, [nextUserId])
+```
+### Custom Hooks
+Located at [`src/hooks/queries/use-health-checks.ts`](../../src/hooks/queries/use-health-checks.ts):
+```typescript
+'use client'
+import { useQuery } from '@tanstack/react-query'
+export function useHealthChecks() {
+  return useQuery({
+    queryKey: ['health-checks'],
+    queryFn: async () => {
+      const response = await fetch('/api/health/all')
+      if (!response.ok) throw new Error('Failed to fetch health checks')
+      return response.json()
+    },
+  })
+}
+```
+**Usage:**
+```typescript
+import { useHealthChecks } from '@/hooks/queries/use-health-checks'
+function HealthPage() {
+  const { data, isLoading, error, refetch } = useHealthChecks()
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error: {error.message}</div>
+  return <div>{/* Render health checks */}</div>
+}
+```
+---
+## Zustand for Client State
+### What is Zustand?
+[Zustand](https://zustand-demo.pmnd.rs/) is a small, fast, and scalable state management solution. It provides:
+- **Simple API**: Minimal boilerplate
+- **No Context**: Avoids unnecessary re-renders
+- **TypeScript Support**: Full type safety
+- **DevTools**: Built-in DevTools integration
+- **Middleware**: Composable middleware
+### Installation
+```bash
+pnpm add zustand
+```
+### Basic Usage
+**Create a Store**
+Located at [`src/stores/ui-store.ts`](../../src/stores/ui-store.ts):
+```typescript
+'use client'
+import { create } from 'zustand'
+interface UIState {
+  sidebarOpen: boolean
+  toggleSidebar: () => void
+  setSidebarOpen: (open: boolean) => void
+}
+export const useUIStore = create<UIState>((set) => ({
+  sidebarOpen: false,
+  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+  setSidebarOpen: (open) => set({ sidebarOpen: open }),
+}))
+```
+**Use the Store**
+```typescript
+import { useUIStore } from '@/stores/ui-store'
+function Sidebar() {
+  const sidebarOpen = useUIStore((state) => state.sidebarOpen)
+  const toggleSidebar = useUIStore((state) => state.toggleSidebar)
+  return (
+    <div>
+      <button onClick={toggleSidebar}>Toggle Sidebar</button>
+      {sidebarOpen && <div>Sidebar Content</div>}
+    </div>
+  )
+}
+```
+### Advanced Patterns
+**Multiple Selectors**
+```typescript
+// Select multiple state values
+const { sidebarOpen, theme } = useUIStore((state) => ({
+  sidebarOpen: state.sidebarOpen,
+  theme: state.theme,
+}))
+```
+**Actions**
+```typescript
+interface UIState {
+  // State
+  sidebarOpen: boolean
+  theme: 'light' | 'dark'
+  // Actions
+  toggleSidebar: () => void
+  setSidebarOpen: (open: boolean) => void
+  setTheme: (theme: 'light' | 'dark') => void
+}
+export const useUIStore = create<UIState>((set) => ({
+  sidebarOpen: false,
+  theme: 'light',
+  toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+  setSidebarOpen: (open) => set({ sidebarOpen: open }),
+  setTheme: (theme) => set({ theme }),
+}))
+```
+**Async Actions**
+```typescript
+interface DataState {
+  data: any[]
+  loading: boolean
+  error: string | null
+  fetchData: () => Promise<void>
+}
+export const useDataStore = create<DataState>((set) => ({
+  data: [],
+  loading: false,
+  error: null,
+  fetchData: async () => {
+    set({ loading: true, error: null })
+    try {
+      const response = await fetch('/api/data')
+      const data = await response.json()
+      set({ data, loading: false })
+    } catch (error) {
+      set({ error: error.message, loading: false })
+    }
+  },
+}))
+```
+**Middleware**
+```typescript
+import { devtools, persist } from 'zustand/middleware'
+export const useUIStore = create<UIState>()(
+  devtools(
+    persist(
+      (set) => ({
+        sidebarOpen: false,
+        toggleSidebar: () => set((state) => ({ sidebarOpen: !state.sidebarOpen })),
+      }),
+      { name: 'ui-storage' }
+    )
+  )
+)
+```
+### Slices
+For larger stores, you can use slices:
+```typescript
+// slices/sidebarSlice.ts
+import { create } from 'zustand'
+export const createSidebarSlice = (set: any) => ({
+  sidebarOpen: false,
+  toggleSidebar: () => set((state: any) => ({ sidebarOpen: !state.sidebarOpen })),
+})
+// slices/themeSlice.ts
+export const createThemeSlice = (set: any) => ({
+  theme: 'light' as 'light' | 'dark',
+  setTheme: (theme: 'light' | 'dark') => set({ theme }),
+})
+// index.ts
+import { create } from 'zustand'
+import { createSidebarSlice } from './slices/sidebarSlice'
+import { createThemeSlice } from './slices/themeSlice'
+export const useUIStore = create<UIState>((set) => ({
+  ...createSidebarSlice(set),
+  ...createThemeSlice(set),
+}))
+```
+---
+## Usage Patterns and Examples
+### Pattern 1: Fetch and Display Data
+```typescript
+import { useQuery } from '@tanstack/react-query'
+function UserProfile({ userId }: { userId: string }) {
+  const { data, isLoading, error } = useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => fetch(`/api/users/${userId}`).then(r => r.json()),
+  })
+  if (isLoading) return <div>Loading...</div>
+  if (error) return <div>Error loading user</div>
+  return (
+    <div>
+      <h1>{data.user.name}</h1>
+      <p>{data.user.email}</p>
+    </div>
+  )
+}
+```
+### Pattern 2: Create and Invalidate
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query'
+function CreateUserForm() {
+  const queryClient = useQueryClient()
+  const mutation = useMutation({
+    mutationFn: (userData: any) =>
+      fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(userData),
+      }).then(r => r.json()),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] })
+    },
+  })
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    const formData = new FormData(e.target as HTMLFormElement)
+    mutation.mutate({
+      name: formData.get('name'),
+      email: formData.get('email'),
+    })
+  }
+  return (
+    <form onSubmit={handleSubmit}>
+      <input name="name" required />
+      <input name="email" required />
+      <button type="submit" disabled={mutation.isPending}>
+        {mutation.isPending ? 'Creating...' : 'Create User'}
+      </button>
+    </form>
+  )
+}
+```
+### Pattern 3: Optimistic Updates
+```typescript
+const mutation = useMutation({
+  mutationFn: updateTodo,
+  onMutate: async (newTodo) => {
+    // Cancel outgoing refetches
+    await queryClient.cancelQueries({ queryKey: ['todos'] })
+    // Snapshot previous value
+    const previousTodos = queryClient.getQueryData(['todos'])
+    // Optimistically update
+    queryClient.setQueryData(['todos'], (old: any) =>
+      old?.map((todo: any) =>
+        todo.id === newTodo.id ? { ...todo, ...newTodo } : todo
+      )
+    )
+    return { previousTodos }
+  },
+  onError: (err, newTodo, context) => {
+    // Rollback on error
+    queryClient.setQueryData(['todos'], context?.previousTodos)
+  },
+  onSettled: () => {
+    // Always refetch after error or success
+    queryClient.invalidateQueries({ queryKey: ['todos'] })
+  },
+})
+```
+### Pattern 4: UI State with Zustand
+```typescript
+import { useUIStore } from '@/stores/ui-store'
+function Header() {
+  const { sidebarOpen, toggleSidebar, theme, setTheme } = useUIStore()
+  return (
+    <header>
+      <button onClick={toggleSidebar}>
+        {sidebarOpen ? 'Close' : 'Open'} Sidebar
+      </button>
+      <select
+        value={theme}
+        onChange={(e) => setTheme(e.target.value as 'light' | 'dark')}
+      >
+        <option value="light">Light</option>
+        <option value="dark">Dark</option>
+      </select>
+    </header>
+  )
+}
+```
+### Pattern 5: Combining Both
+```typescript
+function TodoApp() {
+  // Server state from API
+  const { data: todos, isLoading } = useQuery({
+    queryKey: ['todos'],
+    queryFn: fetchTodos,
+  })
+  // Client state for UI
+  const { filter, setFilter } = useTodoStore()
+  // Filter todos based on UI state
+  const filteredTodos = todos?.filter(todo => {
+    if (filter === 'active') return !todo.completed
+    if (filter === 'completed') return todo.completed
+    return true
+  })
+  return (
+    <div>
+      <div>
+        <button onClick={() => setFilter('all')}>All</button>
+        <button onClick={() => setFilter('active')}>Active</button>
+        <button onClick={() => setFilter('completed')}>Completed</button>
+      </div>
+      {isLoading ? <div>Loading...</div> : (
+        <ul>
+          {filteredTodos?.map(todo => (
+            <li key={todo.id}>{todo.title}</li>
+          ))}
+        </ul>
+      )}
+    </div>
+  )
+}
+```
+---
+## Best Practices
+### TanStack Query
+1. **Use meaningful query keys**: Structure keys to reflect data hierarchy
+2. **Set appropriate stale time**: Balance freshness and performance
+3. **Use mutations for writes**: Separate reads from writes
+4. **Invalidate after mutations**: Keep cache in sync
+5. **Use custom hooks**: Reuse query logic across components
+### Zustand
+1. **Keep stores focused**: One store per domain
+2. **Use selectors**: Subscribe only to needed state
+3. **Avoid putting server state in Zustand**: Use TanStack Query instead
+4. **Use middleware when needed**: DevTools, persistence, etc.
+---
+## Related Documentation
+- [API Layer](./api-layer.md) - API endpoints for data fetching
+- [Health Check System](./health-check-system.md) - Health check data fetching
+- [Clerk Authentication](./clerk-authentication.md) - Authentication state