create-n8-app 0.2.0 → 0.3.1

package/dist/index.js

@@ -122,7 +122,15 @@ async function runShadcnInit(targetDir) {
       stdio: "inherit"
     });
     logger.info("Adding base Shadcn/ui components...");
-    const baseComponents = ["button", "card", "input", "label"];
+    const baseComponents = [
+      "button",
+      "card",
+      "input",
+      "label",
+      "form",
+      "sonner",
+      "textarea"
+    ];
     await execa("npx", ["shadcn@latest", "add", ...baseComponents, "-y"], {
       cwd: targetDir,
       stdio: "inherit"
@@ -232,7 +240,7 @@ async function createProject(options) {
 
 // src/index.ts
 var program = new Command();
-program.name("create-n8-app").description("Create a new Next.js app with the N8 stack").version("0.2.0").argument("[project-name]", "Name of the project").option("--skip-install", "Skip installing dependencies").option("--skip-git", "Skip initializing git repository").action(async (projectName, options) => {
+program.name("create-n8-app").description("Create a new Next.js app with the N8 stack").version("0.3.1").argument("[project-name]", "Name of the project").option("--skip-install", "Skip installing dependencies").option("--skip-git", "Skip initializing git repository").action(async (projectName, options) => {
   try {
     await createProject({
       projectName,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-n8-app",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Create a Next.js app with the N8 stack - Next.js 16, Tailwind v4, Shadcn/ui, Drizzle, tRPC, TanStack Query, Zustand, NextAuth, and more",
   "type": "module",
   "bin": {
@@ -32,11 +32,11 @@
     "template",
     "scaffold"
   ],
-  "author": "Nate McG",
+  "author": "Nate McGrady",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/natemcgrady/create-n8-app"
+    "url": "https://github.com/nmcgrady/n8-stack"
   },
   "devDependencies": {
     "@types/fs-extra": "^11.0.4",

package/template/_package.json

@@ -17,43 +17,52 @@
     "db:studio": "drizzle-kit studio"
   },
   "dependencies": {
-    "@ai-sdk/openai": "^1.3.0",
-    "@auth/drizzle-adapter": "^1.11.0",
-    "@neondatabase/serverless": "^1.0.0",
-    "@tanstack/react-query": "^5.90.0",
-    "@trpc/client": "^11.8.0",
-    "@trpc/react-query": "^11.8.0",
-    "@trpc/server": "^11.8.0",
-    "ai": "^4.3.0",
+    "@ai-sdk/openai": "^3.0.21",
+    "@auth/drizzle-adapter": "^1.11.1",
+    "@hookform/resolvers": "^5.2.2",
+    "@neondatabase/serverless": "^1.0.2",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@tanstack/react-query": "^5.90.20",
+    "@trpc/client": "^11.8.1",
+    "@trpc/react-query": "^11.8.1",
+    "@trpc/server": "^11.8.1",
+    "ai": "^6.0.57",
+    "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "drizzle-orm": "^0.45.0",
+    "drizzle-orm": "^0.45.1",
     "lucide-react": "^0.563.0",
-    "next": "^16.0.0",
-    "next-auth": "^5.0.0-beta.30",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
+    "next": "^16.1.5",
+    "next-auth": "5.0.0-beta.30",
+    "next-themes": "^0.4.6",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "react-hook-form": "^7.71.1",
+    "sonner": "^2.0.7",
     "superjson": "^2.2.6",
     "tailwind-merge": "^3.4.0",
-    "zod": "^3.25.0",
+    "zod": "^4.3.6",
     "zustand": "^5.0.10"
   },
   "devDependencies": {
-    "@tailwindcss/postcss": "^4.1.0",
-    "@testing-library/jest-dom": "^6.9.0",
-    "@testing-library/react": "^16.3.0",
-    "@types/node": "^22.19.0",
-    "@types/react": "^19.2.0",
-    "@types/react-dom": "^19.2.0",
-    "@vitejs/plugin-react": "^4.7.0",
-    "drizzle-kit": "^0.31.0",
-    "eslint": "^9.39.0",
-    "eslint-config-next": "^16.0.0",
+    "@tailwindcss/postcss": "^4.1.18",
+    "@tanstack/react-query-devtools": "^5.91.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^25.0.10",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.2",
+    "drizzle-kit": "^0.31.8",
+    "eslint": "^9.39.2",
+    "eslint-config-next": "^16.1.5",
     "jsdom": "^27.4.0",
-    "postcss": "^8.5.0",
-    "prettier": "^3.8.0",
-    "prettier-plugin-tailwindcss": "^0.7.0",
-    "tailwindcss": "^4.1.0",
-    "typescript": "^5.9.0",
-    "vitest": "^4.0.0"
+    "postcss": "^8.5.6",
+    "prettier": "^3.8.1",
+    "prettier-plugin-tailwindcss": "^0.7.2",
+    "tailwindcss": "^4.1.18",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
   }
 }

package/template/app/auth/signin/page.tsx

@@ -15,7 +15,7 @@ export default function SignInPage() {
         >
           <button
             type="submit"
-            className="flex items-center gap-3 rounded-lg bg-slate-800 px-6 py-3 text-white transition-colors hover:bg-slate-700"
+            className="flex items-center gap-3 rounded-lg bg-slate-800 px-6 py-3 text-white transition-colors hover:bg-slate-700 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white/50 focus-visible:ring-offset-2 focus-visible:ring-offset-slate-900"
           >
             <GitHubIcon />
             Sign in with GitHub
@@ -28,7 +28,12 @@ export default function SignInPage() {
 
 function GitHubIcon() {
   return (
-    <svg className="h-5 w-5" fill="currentColor" viewBox="0 0 24 24">
+    <svg
+      className="h-5 w-5"
+      fill="currentColor"
+      viewBox="0 0 24 24"
+      aria-hidden="true"
+    >
       <path
         fillRule="evenodd"
         d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"

package/template/app/layout.tsx

@@ -2,6 +2,7 @@ import type { Metadata } from 'next'
 import { Inter } from 'next/font/google'
 import './globals.css'
 import { Providers } from './providers'
+import { Toaster } from '@/components/ui/sonner'
 
 const inter = Inter({
   subsets: ['latin'],
@@ -22,6 +23,7 @@ export default function RootLayout({
     <html lang="en" suppressHydrationWarning>
       <body className={`${inter.variable} font-sans antialiased`}>
         <Providers>{children}</Providers>
+        <Toaster />
       </body>
     </html>
   )

package/template/app/page.tsx

@@ -56,12 +56,16 @@ function FeatureCard({
 }) {
   return (
     <Link
-      className="flex max-w-xs flex-col gap-4 rounded-xl bg-white/10 p-4 hover:bg-white/20 transition-colors"
+      className="flex max-w-xs flex-col gap-4 rounded-xl bg-white/10 p-4 transition-colors hover:bg-white/20"
       href={href}
       target="_blank"
       rel="noopener noreferrer"
     >
-      <h3 className="text-2xl font-bold">{title} →</h3>
+      <h3 className="text-2xl font-bold">
+        {title} →
+        {/* Screen reader text for external link */}
+        <span className="sr-only"> (opens in a new tab)</span>
+      </h3>
       <p className="text-slate-300">{description}</p>
     </Link>
   )

package/template/app/providers.tsx

@@ -1,6 +1,7 @@
 'use client'
 
 import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { ReactQueryDevtools } from '@tanstack/react-query-devtools'
 import { httpBatchLink } from '@trpc/client'
 import { SessionProvider } from 'next-auth/react'
 import { useState } from 'react'
@@ -14,12 +15,17 @@ function getBaseUrl() {
 }
 
 export function Providers({ children }: { children: React.ReactNode }) {
+  // Lazy init QueryClient to avoid re-creating on every render
+  // See: https://tanstack.com/query/latest/docs/framework/react/guides/ssr
   const [queryClient] = useState(
     () =>
       new QueryClient({
         defaultOptions: {
           queries: {
-            staleTime: 5 * 1000,
+            // 5 minutes - prevents excessive refetches
+            staleTime: 1000 * 60 * 5,
+            // 1 hour - garbage collection time for inactive queries
+            gcTime: 1000 * 60 * 60,
             refetchOnWindowFocus: false,
           },
         },
@@ -40,7 +46,10 @@ export function Providers({ children }: { children: React.ReactNode }) {
   return (
     <SessionProvider>
       <trpc.Provider client={trpcClient} queryClient={queryClient}>
-        <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+        <QueryClientProvider client={queryClient}>
+          {children}
+          <ReactQueryDevtools initialIsOpen={false} />
+        </QueryClientProvider>
       </trpc.Provider>
     </SessionProvider>
   )

package/template/components/auth/user-button.tsx

@@ -8,7 +8,13 @@ export function UserButton() {
 
   if (status === 'loading') {
     return (
-      <div className="h-8 w-8 animate-pulse rounded-full bg-slate-600" />
+      <div
+        className="h-8 w-8 animate-pulse rounded-full bg-slate-600"
+        role="status"
+        aria-label="Loading user information"
+      >
+        <span className="sr-only">Loading…</span>
+      </div>
     )
   }
 
@@ -16,7 +22,7 @@ export function UserButton() {
     return (
       <button
         onClick={() => signIn('github')}
-        className="rounded-lg bg-white/10 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-white/20"
+        className="rounded-lg bg-white/10 px-4 py-2 text-sm font-medium text-white transition-colors hover:bg-white/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white/50"
       >
         Sign In
       </button>
@@ -28,7 +34,7 @@ export function UserButton() {
       {session.user.image && (
         <Image
           src={session.user.image}
-          alt={session.user.name ?? 'User'}
+          alt={session.user.name ?? 'User avatar'}
           width={32}
           height={32}
           className="rounded-full"
@@ -37,7 +43,7 @@ export function UserButton() {
       <span className="text-sm text-white">{session.user.name}</span>
       <button
         onClick={() => signOut()}
-        className="rounded-lg bg-white/10 px-3 py-1 text-sm text-white transition-colors hover:bg-white/20"
+        className="rounded-lg bg-white/10 px-3 py-1 text-sm text-white transition-colors hover:bg-white/20 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-white/50"
       >
         Sign Out
       </button>

package/template/components/examples/contact-form.tsx

@@ -0,0 +1,171 @@
+'use client'
+
+/**
+ * Example Contact Form
+ *
+ * Demonstrates best practices for React Hook Form + Zod + shadcn/ui:
+ * - Type inference with z.infer<typeof schema>
+ * - Always set defaultValues (prevents uncontrolled warnings)
+ * - zodResolver for validation
+ * - shadcn/ui FormField pattern
+ * - Error handling with FormMessage
+ * - Toast feedback on submit
+ *
+ * IMPORTANT: Always validate on BOTH client and server (security!)
+ * Client validation can be bypassed - server validation is required.
+ */
+
+import { zodResolver } from '@hookform/resolvers/zod'
+import { useForm } from 'react-hook-form'
+import { z } from 'zod'
+
+import { Button } from '@/components/ui/button'
+import {
+  Form,
+  FormControl,
+  FormDescription,
+  FormField,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from '@/components/ui/form'
+import { Input } from '@/components/ui/input'
+import { Textarea } from '@/components/ui/textarea'
+import { useToast } from '@/hooks/use-toast'
+
+// Define schema with Zod - single source of truth for types
+const contactFormSchema = z.object({
+  name: z
+    .string()
+    .min(2, { message: 'Name must be at least 2 characters' })
+    .max(50, { message: 'Name must be less than 50 characters' }),
+  email: z.string().email({ message: 'Please enter a valid email address' }),
+  message: z
+    .string()
+    .min(10, { message: 'Message must be at least 10 characters' })
+    .max(500, { message: 'Message must be less than 500 characters' }),
+})
+
+// Infer TypeScript type from schema
+type ContactFormData = z.infer<typeof contactFormSchema>
+
+export function ContactForm() {
+  const { toast } = useToast()
+
+  // Initialize form with zodResolver and defaultValues
+  // CRITICAL: Always set defaultValues to prevent uncontrolled->controlled warnings
+  const form = useForm<ContactFormData>({
+    resolver: zodResolver(contactFormSchema),
+    defaultValues: {
+      name: '',
+      email: '',
+      message: '',
+    },
+  })
+
+  async function onSubmit(data: ContactFormData) {
+    try {
+      // Example: Send to API (always validate server-side too!)
+      // const response = await fetch('/api/contact', {
+      //   method: 'POST',
+      //   headers: { 'Content-Type': 'application/json' },
+      //   body: JSON.stringify(data),
+      // })
+      //
+      // if (!response.ok) {
+      //   const { errors } = await response.json()
+      //   // Map server errors to form fields
+      //   Object.entries(errors).forEach(([field, message]) => {
+      //     form.setError(field as keyof ContactFormData, { message: message as string })
+      //   })
+      //   return
+      // }
+
+      console.log('Form submitted:', data)
+
+      toast({
+        title: 'Message sent!',
+        description: 'We\'ll get back to you as soon as possible.',
+      })
+
+      form.reset()
+    } catch (error) {
+      toast({
+        variant: 'destructive',
+        title: 'Something went wrong',
+        description: 'Please try again later.',
+      })
+    }
+  }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+        <FormField
+          control={form.control}
+          name="name"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Name</FormLabel>
+              <FormControl>
+                {/* Always spread {...field} in FormControl */}
+                <Input placeholder="Your name…" {...field} />
+              </FormControl>
+              <FormDescription>How should we address you?</FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="email"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Email</FormLabel>
+              <FormControl>
+                <Input
+                  type="email"
+                  placeholder="you@example.com"
+                  autoComplete="email"
+                  spellCheck={false}
+                  {...field}
+                />
+              </FormControl>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <FormField
+          control={form.control}
+          name="message"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>Message</FormLabel>
+              <FormControl>
+                <Textarea
+                  placeholder="Tell us what's on your mind…"
+                  className="min-h-[120px] resize-none"
+                  {...field}
+                />
+              </FormControl>
+              <FormDescription>
+                {field.value.length}/500 characters
+              </FormDescription>
+              <FormMessage />
+            </FormItem>
+          )}
+        />
+
+        <Button
+          type="submit"
+          className="w-full"
+          disabled={form.formState.isSubmitting}
+        >
+          {form.formState.isSubmitting ? 'Sending…' : 'Send Message'}
+        </Button>
+      </form>
+    </Form>
+  )
+}

package/template/hooks/use-posts.ts

@@ -0,0 +1,111 @@
+/**
+ * Example TanStack Query v5 Hooks
+ *
+ * Demonstrates best practices:
+ * - queryOptions factory for reusable query definitions
+ * - Object syntax (required in v5)
+ * - useMutation with onSuccess invalidation
+ * - isPending for loading states (not deprecated isLoading)
+ * - Proper typing with TypeScript
+ *
+ * These hooks wrap tRPC queries but the patterns apply to any data fetching.
+ */
+
+import { useQueryClient } from '@tanstack/react-query'
+import { trpc } from '@/lib/trpc'
+
+/**
+ * Hook to fetch all posts
+ *
+ * Uses tRPC's built-in React Query integration.
+ * The query key is automatically managed by tRPC.
+ */
+export function usePosts() {
+  return trpc.example.getPosts.useQuery(undefined, {
+    // v5: staleTime and gcTime are set globally in providers.tsx
+    // Override here if needed for specific queries
+  })
+}
+
+/**
+ * Hook to fetch a single post by ID
+ *
+ * Note: For conditional queries, use the `enabled` option.
+ * Don't use enabled with useSuspenseQuery - use conditional rendering instead.
+ */
+export function usePost(id: number | undefined) {
+  return trpc.example.getPost.useQuery(
+    { id: id! },
+    {
+      // Only fetch when id is defined
+      enabled: !!id,
+    }
+  )
+}
+
+/**
+ * Hook to create a new post
+ *
+ * Demonstrates:
+ * - useMutation pattern
+ * - Invalidating queries on success
+ * - Proper error handling
+ */
+export function useCreatePost() {
+  const queryClient = useQueryClient()
+  const utils = trpc.useUtils()
+
+  return trpc.example.createPost.useMutation({
+    onSuccess: () => {
+      // Invalidate posts query to refetch the list
+      // This triggers a refetch of all queries matching this key
+      utils.example.getPosts.invalidate()
+    },
+    // onError is still available on mutations (removed from queries in v5)
+    onError: (error) => {
+      console.error('Failed to create post:', error.message)
+    },
+  })
+}
+
+/**
+ * Hook to delete a post
+ */
+export function useDeletePost() {
+  const utils = trpc.useUtils()
+
+  return trpc.example.deletePost.useMutation({
+    onSuccess: () => {
+      utils.example.getPosts.invalidate()
+    },
+  })
+}
+
+/**
+ * Example: Using the hooks in a component
+ *
+ * ```tsx
+ * function PostsList() {
+ *   const { data: posts, isPending, isError, error } = usePosts()
+ *   const createPost = useCreatePost()
+ *
+ *   // v5: Use isPending for initial loading state
+ *   if (isPending) return <div>Loading...</div>
+ *   if (isError) return <div>Error: {error.message}</div>
+ *
+ *   return (
+ *     <div>
+ *       <button
+ *         onClick={() => createPost.mutate({ title: 'New Post' })}
+ *         disabled={createPost.isPending}
+ *       >
+ *         {createPost.isPending ? 'Creating...' : 'Create Post'}
+ *       </button>
+ *       <ul>
+ *         {posts.map(post => <li key={post.id}>{post.title}</li>)}
+ *       </ul>
+ *     </div>
+ *   )
+ * }
+ * ```
+ */

package/template/lib/utils.ts

@@ -1,5 +1,5 @@
-import { type ClassValue, clsx } from 'clsx'
-import { twMerge } from 'tailwind-merge'
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
 
 export function cn(...inputs: ClassValue[]) {
   return twMerge(clsx(inputs))

package/template/stores/example-store.ts

@@ -1,5 +1,5 @@
 import { create } from 'zustand'
-import { persist } from 'zustand/middleware'
+import { persist, type PersistStorage } from 'zustand/middleware'
 
 /**
  * Example Zustand store for managing global UI state
@@ -14,6 +14,10 @@ import { persist } from 'zustand/middleware'
  * - Server data (use React Query instead)
  * - Form state (use React Hook Form or local state)
  * - Local component state (use useState)
+ *
+ * IMPORTANT: Always use version + migrate for localStorage persistence
+ * to handle schema changes gracefully. Otherwise, users with old data
+ * in localStorage may experience errors or unexpected behavior.
  */
 
 interface UIState {
@@ -51,8 +55,24 @@ export const useUIStore = create<UIState>()(
     }),
     {
       name: 'ui-storage', // localStorage key
+      // Version your schema to handle migrations
+      version: 1,
+      // Migrate from previous versions
+      migrate: (persistedState: unknown, version: number) => {
+        const state = persistedState as Partial<UIState>
+        if (version === 0) {
+          // Example migration: v0 -> v1
+          // Add default values for new fields
+          return {
+            ...state,
+            sidebarOpen: state.sidebarOpen ?? true,
+            theme: state.theme ?? 'system',
+          }
+        }
+        return state as UIState
+      },
       partialize: (state) => ({
-        // Only persist these fields
+        // Only persist these fields (exclude functions and transient state)
         sidebarOpen: state.sidebarOpen,
         theme: state.theme,
       }),
@@ -116,6 +136,21 @@ export const useCartStore = create<CartState>()(
     }),
     {
       name: 'cart-storage',
+      // Version your schema to handle migrations
+      version: 1,
+      // Migrate from previous versions
+      migrate: (persistedState: unknown, version: number) => {
+        const state = persistedState as Partial<CartState>
+        if (version === 0) {
+          // Example migration: v0 -> v1
+          // Ensure items array exists
+          return {
+            ...state,
+            items: state.items ?? [],
+          }
+        }
+        return state as CartState
+      },
     }
   )
 )

package/template/tsconfig.json

@@ -1,7 +1,11 @@
 {
   "compilerOptions": {
     "target": "ES2017",
-    "lib": ["dom", "dom.iterable", "esnext"],
+    "lib": [
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
     "allowJs": true,
     "skipLibCheck": true,
     "strict": true,
@@ -11,7 +15,7 @@
     "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "incremental": true,
     "plugins": [
       {
@@ -19,9 +23,19 @@
       }
     ],
     "paths": {
-      "@/*": ["./*"]
+      "@/*": [
+        "./*"
+      ]
     }
   },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
-  "exclude": ["node_modules"]
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
 }

package/template/hooks/.gitkeep

@@ -1 +0,0 @@
-# Custom React hooks go here