add file storage, local and prod

.gitignore

@@ -41,3 +41,6 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# uploads
+public/uploads

CLAUDE.md

@@ -68,6 +68,7 @@ src/
     ├── auth-client.ts           # Better Auth client hooks
     ├── db.ts                    # Database connection
     ├── schema.ts                # Drizzle schema (users, sessions, etc.)
+    ├── storage.ts               # File storage abstraction (Vercel Blob / local)
     └── utils.ts                 # Utility functions (cn, etc.)
 ```
 
@@ -92,6 +93,9 @@ OPENROUTER_MODEL=openai/gpt-5-mini  # or any model from openrouter.ai/models
 
 # App
 NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# File Storage (optional)
+BLOB_READ_WRITE_TOKEN=  # Leave empty for local dev, set for Vercel Blob in production
 ```
 
 ## Available Scripts
@@ -162,14 +166,22 @@ The project includes technical documentation in `docs/`:
    - Always run migrations after schema changes
    - PostgreSQL is the database (not SQLite, MySQL, etc.)
 
-7. **Component Creation**
+7. **File Storage**
+
+   - Use the storage abstraction from `@/lib/storage`
+   - Automatically uses local storage (dev) or Vercel Blob (production)
+   - Import: `import { upload, deleteFile } from "@/lib/storage"`
+   - Example: `const result = await upload(buffer, "avatar.png", "avatars")`
+   - Storage switches based on `BLOB_READ_WRITE_TOKEN` environment variable
+
+8. **Component Creation**
 
    - Use existing shadcn/ui components when possible
    - Follow the established patterns in `src/components/ui/`
    - Support both light and dark modes
    - Use TypeScript with proper types
 
-8. **API Routes**
+9. **API Routes**
    - Follow Next.js 15 App Router conventions
    - Use Route Handlers (route.ts files)
    - Return Response objects
@@ -217,6 +229,14 @@ The project includes technical documentation in `docs/`:
 3. Reference streaming docs: `docs/technical/ai/streaming.md`
 4. Remember to use OpenRouter, not direct OpenAI
 
+**Working with file storage:**
+
+1. Import storage functions: `import { upload, deleteFile } from "@/lib/storage"`
+2. Upload files: `const result = await upload(fileBuffer, "filename.png", "folder")`
+3. Delete files: `await deleteFile(result.url)`
+4. Storage automatically uses local filesystem in dev, Vercel Blob in production
+5. Local files are saved to `public/uploads/` and served at `/uploads/`
+
 ## Package Manager
 
 This project uses **pnpm** (see `pnpm-lock.yaml`). When running commands:

README.md

@@ -7,6 +7,7 @@ A complete agentic coding boilerplate with authentication, PostgreSQL database,
 - **🔐 Authentication**: Better Auth with Google OAuth integration
 - **🗃️ Database**: Drizzle ORM with PostgreSQL
 - **🤖 AI Integration**: Vercel AI SDK with OpenRouter (access to 100+ AI models)
+- **📁 File Storage**: Automatic local/Vercel Blob storage with seamless switching
 - **🎨 UI Components**: shadcn/ui with Tailwind CSS
 - **⚡ Modern Stack**: Next.js 15, React 19, TypeScript
 - **📱 Responsive**: Mobile-first design approach
@@ -113,6 +114,11 @@ OPENROUTER_MODEL="openai/gpt-5-mini"
 
 # App URL (for production deployments)
 NEXT_PUBLIC_APP_URL="http://localhost:3000"
+
+# File Storage (Optional - for file upload functionality)
+# Leave empty to use local storage (public/uploads/) in development
+# Set to enable Vercel Blob storage in production
+BLOB_READ_WRITE_TOKEN=""
 ```
 
 **4. Database Setup**
@@ -163,6 +169,25 @@ Your application will be available at [http://localhost:3000](http://localhost:3
 5. Copy the API key and add it to your `.env` file as `OPENROUTER_API_KEY`
 6. Browse available models at <a href="https://openrouter.ai/models" target="_blank">OpenRouter Models</a>
 
+### File Storage Configuration
+
+The project includes a flexible storage abstraction that automatically switches between local filesystem storage (development) and Vercel Blob storage (production).
+
+**For Development (Local Storage):**
+- Leave `BLOB_READ_WRITE_TOKEN` empty or unset in your `.env` file
+- Files are automatically stored in `public/uploads/`
+- Files are served at `/uploads/` URL path
+- No external service or configuration needed
+
+**For Production (Vercel Blob):**
+1. Go to <a href="https://vercel.com/dashboard" target="_blank">Vercel Dashboard</a>
+2. Navigate to your project → **Storage** tab
+3. Click **Create** → **Blob**
+4. Copy the `BLOB_READ_WRITE_TOKEN` from the integration
+5. Add it to your production environment variables
+
+The storage service automatically detects which backend to use based on the presence of the `BLOB_READ_WRITE_TOKEN` environment variable.
+
 ## 🗂️ Project Structure
 
 ```
@@ -182,6 +207,7 @@ src/
     ├── auth-client.ts    # Client-side auth utilities
     ├── db.ts             # Database connection
     ├── schema.ts         # Database schema
+    ├── storage.ts        # File storage abstraction
     └── utils.ts          # General utilities
 ```
 
@@ -236,6 +262,7 @@ Ensure these are set in your production environment:
 - `OPENROUTER_API_KEY` - OpenRouter API key (optional, for AI chat functionality)
 - `OPENROUTER_MODEL` - Model name from OpenRouter (optional, defaults to openai/gpt-5-mini)
 - `NEXT_PUBLIC_APP_URL` - Your production domain
+- `BLOB_READ_WRITE_TOKEN` - Vercel Blob token (optional, uses local storage if not set)
 
 ## 🎥 Tutorial Video
 

create-agentic-app/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "create-agentic-app",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "create-agentic-app",
-      "version": "1.1.17",
+      "version": "1.1.18",
       "license": "MIT",
       "dependencies": {
         "chalk": "^5.3.0",

create-agentic-app/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-app",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "description": "Scaffold a new agentic AI application with Next.js, Better Auth, and AI SDK",
   "type": "module",
   "bin": {

create-agentic-app/template/CLAUDE.md

@@ -68,6 +68,7 @@ src/
     ├── auth-client.ts           # Better Auth client hooks
     ├── db.ts                    # Database connection
     ├── schema.ts                # Drizzle schema (users, sessions, etc.)
+    ├── storage.ts               # File storage abstraction (Vercel Blob / local)
     └── utils.ts                 # Utility functions (cn, etc.)
 ```
 
@@ -92,6 +93,9 @@ OPENROUTER_MODEL=openai/gpt-5-mini  # or any model from openrouter.ai/models
 
 # App
 NEXT_PUBLIC_APP_URL=http://localhost:3000
+
+# File Storage (optional)
+BLOB_READ_WRITE_TOKEN=  # Leave empty for local dev, set for Vercel Blob in production
 ```
 
 ## Available Scripts
@@ -162,14 +166,22 @@ The project includes technical documentation in `docs/`:
    - Always run migrations after schema changes
    - PostgreSQL is the database (not SQLite, MySQL, etc.)
 
-7. **Component Creation**
+7. **File Storage**
+
+   - Use the storage abstraction from `@/lib/storage`
+   - Automatically uses local storage (dev) or Vercel Blob (production)
+   - Import: `import { upload, deleteFile } from "@/lib/storage"`
+   - Example: `const result = await upload(buffer, "avatar.png", "avatars")`
+   - Storage switches based on `BLOB_READ_WRITE_TOKEN` environment variable
+
+8. **Component Creation**
 
    - Use existing shadcn/ui components when possible
    - Follow the established patterns in `src/components/ui/`
    - Support both light and dark modes
    - Use TypeScript with proper types
 
-8. **API Routes**
+9. **API Routes**
    - Follow Next.js 15 App Router conventions
    - Use Route Handlers (route.ts files)
    - Return Response objects
@@ -217,6 +229,14 @@ The project includes technical documentation in `docs/`:
 3. Reference streaming docs: `docs/technical/ai/streaming.md`
 4. Remember to use OpenRouter, not direct OpenAI
 
+**Working with file storage:**
+
+1. Import storage functions: `import { upload, deleteFile } from "@/lib/storage"`
+2. Upload files: `const result = await upload(fileBuffer, "filename.png", "folder")`
+3. Delete files: `await deleteFile(result.url)`
+4. Storage automatically uses local filesystem in dev, Vercel Blob in production
+5. Local files are saved to `public/uploads/` and served at `/uploads/`
+
 ## Package Manager
 
 This project uses **pnpm** (see `pnpm-lock.yaml`). When running commands:

create-agentic-app/template/README.md

@@ -7,6 +7,7 @@ A complete agentic coding boilerplate with authentication, PostgreSQL database,
 - **🔐 Authentication**: Better Auth with Google OAuth integration
 - **🗃️ Database**: Drizzle ORM with PostgreSQL
 - **🤖 AI Integration**: Vercel AI SDK with OpenRouter (access to 100+ AI models)
+- **📁 File Storage**: Automatic local/Vercel Blob storage with seamless switching
 - **🎨 UI Components**: shadcn/ui with Tailwind CSS
 - **⚡ Modern Stack**: Next.js 15, React 19, TypeScript
 - **📱 Responsive**: Mobile-first design approach
@@ -113,6 +114,11 @@ OPENROUTER_MODEL="openai/gpt-5-mini"
 
 # App URL (for production deployments)
 NEXT_PUBLIC_APP_URL="http://localhost:3000"
+
+# File Storage (Optional - for file upload functionality)
+# Leave empty to use local storage (public/uploads/) in development
+# Set to enable Vercel Blob storage in production
+BLOB_READ_WRITE_TOKEN=""
 ```
 
 **4. Database Setup**
@@ -163,6 +169,25 @@ Your application will be available at [http://localhost:3000](http://localhost:3
 5. Copy the API key and add it to your `.env` file as `OPENROUTER_API_KEY`
 6. Browse available models at <a href="https://openrouter.ai/models" target="_blank">OpenRouter Models</a>
 
+### File Storage Configuration
+
+The project includes a flexible storage abstraction that automatically switches between local filesystem storage (development) and Vercel Blob storage (production).
+
+**For Development (Local Storage):**
+- Leave `BLOB_READ_WRITE_TOKEN` empty or unset in your `.env` file
+- Files are automatically stored in `public/uploads/`
+- Files are served at `/uploads/` URL path
+- No external service or configuration needed
+
+**For Production (Vercel Blob):**
+1. Go to <a href="https://vercel.com/dashboard" target="_blank">Vercel Dashboard</a>
+2. Navigate to your project → **Storage** tab
+3. Click **Create** → **Blob**
+4. Copy the `BLOB_READ_WRITE_TOKEN` from the integration
+5. Add it to your production environment variables
+
+The storage service automatically detects which backend to use based on the presence of the `BLOB_READ_WRITE_TOKEN` environment variable.
+
 ## 🗂️ Project Structure
 
 ```
@@ -182,6 +207,7 @@ src/
     ├── auth-client.ts    # Client-side auth utilities
     ├── db.ts             # Database connection
     ├── schema.ts         # Database schema
+    ├── storage.ts        # File storage abstraction
     └── utils.ts          # General utilities
 ```
 
@@ -236,6 +262,7 @@ Ensure these are set in your production environment:
 - `OPENROUTER_API_KEY` - OpenRouter API key (optional, for AI chat functionality)
 - `OPENROUTER_MODEL` - Model name from OpenRouter (optional, defaults to openai/gpt-5-mini)
 - `NEXT_PUBLIC_APP_URL` - Your production domain
+- `BLOB_READ_WRITE_TOKEN` - Vercel Blob token (optional, uses local storage if not set)
 
 ## 🎥 Tutorial Video
 

create-agentic-app/template/_gitignore

@@ -41,3 +41,6 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# uploads
+public/uploads

create-agentic-app/template/package.json

@@ -22,6 +22,7 @@
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-slot": "^1.2.3",
+    "@vercel/blob": "^2.0.0",
     "ai": "^5.0.86",
     "better-auth": "^1.3.34",
     "class-variance-authority": "^0.7.1",

create-agentic-app/template/src/app/api/diagnostics/route.ts

@@ -24,6 +24,10 @@ interface DiagnosticsResponse {
   ai: {
     configured: boolean;
   };
+  storage: {
+    configured: boolean;
+    type: "local" | "remote";
+  };
   overallStatus: StatusLevel;
 }
 
@@ -115,6 +119,10 @@ export async function GET(req: Request) {
     env.BETTER_AUTH_SECRET && env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET;
   const aiConfigured = env.OPENROUTER_API_KEY; // We avoid live-calling the AI provider here
 
+  // Storage configuration check
+  const storageConfigured = Boolean(process.env.BLOB_READ_WRITE_TOKEN);
+  const storageType: "local" | "remote" = storageConfigured ? "remote" : "local";
+
   const overallStatus: StatusLevel = (() => {
     if (!env.POSTGRES_URL || !dbConnected || !schemaApplied) return "error";
     if (!authConfigured) return "error";
@@ -138,6 +146,10 @@ export async function GET(req: Request) {
     ai: {
       configured: aiConfigured,
     },
+    storage: {
+      configured: storageConfigured,
+      type: storageType,
+    },
     overallStatus,
   };
 

create-agentic-app/template/src/app/page.tsx

@@ -43,7 +43,7 @@ export default function Home() {
             <div className="relative pb-[56.25%] h-0 overflow-hidden rounded-lg border">
               <iframe
                 className="absolute top-0 left-0 w-full h-full"
-                src="https://www.youtube.com/embed/T0zFZsr_d0Q"
+                src="https://www.youtube.com/embed/JQ86N3WOAh4"
                 title="Agentic Coding Boilerplate Tutorial"
                 allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
                 allowFullScreen

create-agentic-app/template/src/components/setup-checklist.tsx

@@ -26,6 +26,10 @@ type DiagnosticsResponse = {
   ai: {
     configured: boolean;
   };
+  storage: {
+    configured: boolean;
+    type: "local" | "remote";
+  };
   overallStatus: "ok" | "warn" | "error";
 };
 
@@ -102,6 +106,16 @@ export function SetupChecklist() {
         ? "Set OPENROUTER_API_KEY for AI chat"
         : undefined,
     },
+    {
+      key: "storage",
+      label: "File storage (optional)",
+      ok: true, // Always considered "ok" since local storage works
+      detail: data?.storage
+        ? data.storage.type === "remote"
+          ? "Using Vercel Blob storage"
+          : "Using local storage (public/uploads/)"
+        : undefined,
+    },
   ] as const;
 
   const completed = steps.filter((s) => s.ok).length;

create-agentic-app/template/src/lib/storage.ts

@@ -0,0 +1,102 @@
+import { put, del } from "@vercel/blob";
+import { writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+import { existsSync } from "fs";
+
+/**
+ * Result from uploading a file to storage
+ */
+export interface StorageResult {
+  url: string; // Public URL to access the file
+  pathname: string; // Path/key of the stored file
+}
+
+/**
+ * Uploads a file to storage (Vercel Blob or local filesystem)
+ * 
+ * @param buffer - File contents as a Buffer
+ * @param filename - Name of the file (e.g., "image.png")
+ * @param folder - Optional folder/prefix (e.g., "avatars")
+ * @returns StorageResult with url and pathname
+ * 
+ * @example
+ * ```ts
+ * const result = await upload(fileBuffer, "avatar.png", "avatars");
+ * console.log(result.url); // https://blob.vercel.io/... or /uploads/avatars/avatar.png
+ * ```
+ */
+export async function upload(
+  buffer: Buffer,
+  filename: string,
+  folder?: string
+): Promise<StorageResult> {
+  const hasVercelBlob = Boolean(process.env.BLOB_READ_WRITE_TOKEN);
+
+  if (hasVercelBlob) {
+    // Use Vercel Blob storage
+    const pathname = folder ? `${folder}/${filename}` : filename;
+    const blob = await put(pathname, buffer, {
+      access: "public",
+    });
+
+    return {
+      url: blob.url,
+      pathname: blob.pathname,
+    };
+  } else {
+    // Use local filesystem storage
+    const uploadsDir = join(process.cwd(), "public", "uploads");
+    const targetDir = folder ? join(uploadsDir, folder) : uploadsDir;
+
+    // Ensure the directory exists
+    if (!existsSync(targetDir)) {
+      await mkdir(targetDir, { recursive: true });
+    }
+
+    // Write the file
+    const filepath = join(targetDir, filename);
+    await writeFile(filepath, buffer);
+
+    // Return local URL
+    const pathname = folder ? `${folder}/${filename}` : filename;
+    const url = `/uploads/${pathname}`;
+
+    return {
+      url,
+      pathname,
+    };
+  }
+}
+
+/**
+ * Deletes a file from storage
+ * 
+ * @param url - The URL of the file to delete
+ * 
+ * @example
+ * ```ts
+ * await deleteFile("https://blob.vercel.io/...");
+ * // or
+ * await deleteFile("/uploads/avatars/avatar.png");
+ * ```
+ */
+export async function deleteFile(url: string): Promise<void> {
+  const hasVercelBlob = Boolean(process.env.BLOB_READ_WRITE_TOKEN);
+
+  if (hasVercelBlob) {
+    // Delete from Vercel Blob
+    await del(url);
+  } else {
+    // Delete from local filesystem
+    // Extract pathname from URL (e.g., /uploads/avatars/avatar.png -> avatars/avatar.png)
+    const pathname = url.replace(/^\/uploads\//, "");
+    const filepath = join(process.cwd(), "public", "uploads", pathname);
+
+    // Only attempt to delete if file exists
+    if (existsSync(filepath)) {
+      const { unlink } = await import("fs/promises");
+      await unlink(filepath);
+    }
+  }
+}
+

package.json

@@ -23,6 +23,7 @@
     "@radix-ui/react-dialog": "^1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-slot": "^1.2.3",
+    "@vercel/blob": "^2.0.0",
     "ai": "^5.0.86",
     "better-auth": "^1.3.34",
     "class-variance-authority": "^0.7.1",

pnpm-lock.yaml

@@ -33,6 +33,9 @@ importers:
       '@radix-ui/react-slot':
         specifier: ^1.2.3
         version: 1.2.3(@types/react@19.2.5)(react@19.2.0)
+      '@vercel/blob':
+        specifier: ^2.0.0
+        version: 2.0.0
       ai:
         specifier: ^5.0.86
         version: 5.0.86(zod@4.1.12)
@@ -662,6 +665,10 @@ packages:
     resolution: {integrity: sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==}
     engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
 
+  '@fastify/busboy@2.1.1':
+    resolution: {integrity: sha512-vBZP4NlzfOlerQTnba4aqZoMhE/a9HY7HRqoOPaETQcSQuWEIyZMHGfVu6w9wGtGK5fED5qRs2DteVCjOH60sA==}
+    engines: {node: '>=14'}
+
   '@floating-ui/core@1.7.3':
     resolution: {integrity: sha512-sGnvb5dmrJaKEZ+LDIpguvdX3bDlEllmv4/ClQ9awcmCZrlx5jQyyMWFM5kBI+EyNOCDDiKk8il0zeuX3Zlg/w==}
 
@@ -1663,6 +1670,10 @@ packages:
     cpu: [x64]
     os: [win32]
 
+  '@vercel/blob@2.0.0':
+    resolution: {integrity: sha512-oAj7Pdy83YKSwIaMFoM7zFeLYWRc+qUpW3PiDSblxQMnGFb43qs4bmfq7dr/+JIfwhs6PTwe1o2YBwKhyjWxXw==}
+    engines: {node: '>=20.0.0'}
+
   '@vercel/oidc@3.0.3':
     resolution: {integrity: sha512-yNEQvPcVrK9sIe637+I0jD6leluPxzwJKx/Haw6F4H77CdDsszUn5V3o96LPziXkSNE2B83+Z3mjqGKBK/R6Gg==}
     engines: {node: '>= 20'}
@@ -1768,6 +1779,9 @@ packages:
     resolution: {integrity: sha512-hsU18Ae8CDTR6Kgu9DYf0EbCr/a5iGL0rytQDobUcdpYOKokk8LEjVphnXkDkgpi0wYVsqrXuP0bZxJaTqdgoA==}
     engines: {node: '>= 0.4'}
 
+  async-retry@1.3.3:
+    resolution: {integrity: sha512-wfr/jstw9xNi/0teMHrRW7dsz3Lt5ARhYNZ2ewpadnhaIp5mbALhOAP+EAdsC7t4Z6wqsDVv9+W6gm1Dk9mEyw==}
+
   available-typed-arrays@1.0.7:
     resolution: {integrity: sha512-wvUjBtSGN7+7SjNpq/9M2Tg350UZD3q62IFZLbRAR1bSMlCo1ZaeW+BJ+D090e4hIIZLBcTDWe4Mh4jvUDajzQ==}
     engines: {node: '>= 0.4'}
@@ -2728,6 +2742,10 @@ packages:
     resolution: {integrity: sha512-wa56o2/ElJMYqjCjGkXri7it5FbebW5usLw/nPmCMs5DeZ7eziSYZhSmPRn0txqeW4LnAmQQU7FgqLpsEFKM4A==}
     engines: {node: '>= 0.4'}
 
+  is-buffer@2.0.5:
+    resolution: {integrity: sha512-i2R6zNFDwgEHJyQUtJEk0XFi1i0dPFn/oqjK3/vPCcDeJvW5NQ83V8QbicfF1SupOaB0h8ntgBC2YiE7dfyctQ==}
+    engines: {node: '>=4'}
+
   is-bun-module@2.0.0:
     resolution: {integrity: sha512-gNCGbnnnnFAUGKeZ9PdbyeGYJqewpmc2aKHUEMO5nQPWU9lOmv7jcmQIv+qHD8fXW6W7qfuCwX4rY9LNRjXrkQ==}
 
@@ -3622,6 +3640,10 @@ packages:
     resolution: {integrity: sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==}
     engines: {node: '>=18'}
 
+  retry@0.13.1:
+    resolution: {integrity: sha512-XQBQ3I8W1Cge0Seh+6gjj03LbmRFWuoszgK9ooCpwYIrhhoO80pfq4cUkU5DkknwfOfFteRwlZ56PYOGYyFWdg==}
+    engines: {node: '>= 4'}
+
   rettime@0.7.0:
     resolution: {integrity: sha512-LPRKoHnLKd/r3dVxcwO7vhCW+orkOGj9ViueosEBK6ie89CijnfRlhaDhHq/3Hxu4CkWQtxwlBG0mzTQY6uQjw==}
 
@@ -3999,6 +4021,10 @@ packages:
   undici-types@6.21.0:
     resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
 
+  undici@5.29.0:
+    resolution: {integrity: sha512-raqeBD6NQK4SkWhQzeYKd1KmIG6dllBOTt55Rmkt4HtI9mwdWtJljnrXjAFUBLTSN67HWrOIZ3EPF4kjUw80Bg==}
+    engines: {node: '>=14.0'}
+
   unicorn-magic@0.3.0:
     resolution: {integrity: sha512-+QBBXBCvifc56fsbuxZQ6Sic3wqqc3WWaqxs58gvJrcOuN83HGTCwz3oS5phzU9LthRNE9VrJCFCLUgHeeFnfA==}
     engines: {node: '>=18'}
@@ -4665,6 +4691,8 @@ snapshots:
       '@eslint/core': 0.17.0
       levn: 0.4.1
 
+  '@fastify/busboy@2.1.1': {}
+
   '@floating-ui/core@1.7.3':
     dependencies:
       '@floating-ui/utils': 0.2.10
@@ -5629,6 +5657,14 @@ snapshots:
   '@unrs/resolver-binding-win32-x64-msvc@1.11.1':
     optional: true
 
+  '@vercel/blob@2.0.0':
+    dependencies:
+      async-retry: 1.3.3
+      is-buffer: 2.0.5
+      is-node-process: 1.2.0
+      throttleit: 2.1.0
+      undici: 5.29.0
+
   '@vercel/oidc@3.0.3': {}
 
   accepts@2.0.0:
@@ -5758,6 +5794,10 @@ snapshots:
 
   async-function@1.0.0: {}
 
+  async-retry@1.3.3:
+    dependencies:
+      retry: 0.13.1
+
   available-typed-arrays@1.0.7:
     dependencies:
       possible-typed-array-names: 1.1.0
@@ -6842,6 +6882,8 @@ snapshots:
       call-bound: 1.0.4
       has-tostringtag: 1.0.2
 
+  is-buffer@2.0.5: {}
+
   is-bun-module@2.0.0:
     dependencies:
       semver: 7.7.3
@@ -7840,6 +7882,8 @@ snapshots:
       onetime: 7.0.0
       signal-exit: 4.1.0
 
+  retry@0.13.1: {}
+
   rettime@0.7.0: {}
 
   reusify@1.1.0: {}
@@ -8330,6 +8374,10 @@ snapshots:
 
   undici-types@6.21.0: {}
 
+  undici@5.29.0:
+    dependencies:
+      '@fastify/busboy': 2.1.1
+
   unicorn-magic@0.3.0: {}
 
   unified@11.0.5:

src/app/api/diagnostics/route.ts

@@ -24,6 +24,10 @@ interface DiagnosticsResponse {
   ai: {
     configured: boolean;
   };
+  storage: {
+    configured: boolean;
+    type: "local" | "remote";
+  };
   overallStatus: StatusLevel;
 }
 
@@ -115,6 +119,10 @@ export async function GET(req: Request) {
     env.BETTER_AUTH_SECRET && env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET;
   const aiConfigured = env.OPENROUTER_API_KEY; // We avoid live-calling the AI provider here
 
+  // Storage configuration check
+  const storageConfigured = Boolean(process.env.BLOB_READ_WRITE_TOKEN);
+  const storageType: "local" | "remote" = storageConfigured ? "remote" : "local";
+
   const overallStatus: StatusLevel = (() => {
     if (!env.POSTGRES_URL || !dbConnected || !schemaApplied) return "error";
     if (!authConfigured) return "error";
@@ -138,6 +146,10 @@ export async function GET(req: Request) {
     ai: {
       configured: aiConfigured,
     },
+    storage: {
+      configured: storageConfigured,
+      type: storageType,
+    },
     overallStatus,
   };
 

src/app/page.tsx

@@ -43,7 +43,7 @@ export default function Home() {
             <div className="relative pb-[56.25%] h-0 overflow-hidden rounded-lg border">
               <iframe
                 className="absolute top-0 left-0 w-full h-full"
-                src="https://www.youtube.com/embed/T0zFZsr_d0Q"
+                src="https://www.youtube.com/embed/JQ86N3WOAh4"
                 title="Agentic Coding Boilerplate Tutorial"
                 allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
                 allowFullScreen

src/components/setup-checklist.tsx

@@ -26,6 +26,10 @@ type DiagnosticsResponse = {
   ai: {
     configured: boolean;
   };
+  storage: {
+    configured: boolean;
+    type: "local" | "remote";
+  };
   overallStatus: "ok" | "warn" | "error";
 };
 
@@ -102,6 +106,16 @@ export function SetupChecklist() {
         ? "Set OPENROUTER_API_KEY for AI chat"
         : undefined,
     },
+    {
+      key: "storage",
+      label: "File storage (optional)",
+      ok: true, // Always considered "ok" since local storage works
+      detail: data?.storage
+        ? data.storage.type === "remote"
+          ? "Using Vercel Blob storage"
+          : "Using local storage (public/uploads/)"
+        : undefined,
+    },
   ] as const;
 
   const completed = steps.filter((s) => s.ok).length;

src/lib/storage.ts

@@ -0,0 +1,102 @@
+import { put, del } from "@vercel/blob";
+import { writeFile, mkdir } from "fs/promises";
+import { join } from "path";
+import { existsSync } from "fs";
+
+/**
+ * Result from uploading a file to storage
+ */
+export interface StorageResult {
+  url: string; // Public URL to access the file
+  pathname: string; // Path/key of the stored file
+}
+
+/**
+ * Uploads a file to storage (Vercel Blob or local filesystem)
+ * 
+ * @param buffer - File contents as a Buffer
+ * @param filename - Name of the file (e.g., "image.png")
+ * @param folder - Optional folder/prefix (e.g., "avatars")
+ * @returns StorageResult with url and pathname
+ * 
+ * @example
+ * ```ts
+ * const result = await upload(fileBuffer, "avatar.png", "avatars");
+ * console.log(result.url); // https://blob.vercel.io/... or /uploads/avatars/avatar.png
+ * ```
+ */
+export async function upload(
+  buffer: Buffer,
+  filename: string,
+  folder?: string
+): Promise<StorageResult> {
+  const hasVercelBlob = Boolean(process.env.BLOB_READ_WRITE_TOKEN);
+
+  if (hasVercelBlob) {
+    // Use Vercel Blob storage
+    const pathname = folder ? `${folder}/${filename}` : filename;
+    const blob = await put(pathname, buffer, {
+      access: "public",
+    });
+
+    return {
+      url: blob.url,
+      pathname: blob.pathname,
+    };
+  } else {
+    // Use local filesystem storage
+    const uploadsDir = join(process.cwd(), "public", "uploads");
+    const targetDir = folder ? join(uploadsDir, folder) : uploadsDir;
+
+    // Ensure the directory exists
+    if (!existsSync(targetDir)) {
+      await mkdir(targetDir, { recursive: true });
+    }
+
+    // Write the file
+    const filepath = join(targetDir, filename);
+    await writeFile(filepath, buffer);
+
+    // Return local URL
+    const pathname = folder ? `${folder}/${filename}` : filename;
+    const url = `/uploads/${pathname}`;
+
+    return {
+      url,
+      pathname,
+    };
+  }
+}
+
+/**
+ * Deletes a file from storage
+ * 
+ * @param url - The URL of the file to delete
+ * 
+ * @example
+ * ```ts
+ * await deleteFile("https://blob.vercel.io/...");
+ * // or
+ * await deleteFile("/uploads/avatars/avatar.png");
+ * ```
+ */
+export async function deleteFile(url: string): Promise<void> {
+  const hasVercelBlob = Boolean(process.env.BLOB_READ_WRITE_TOKEN);
+
+  if (hasVercelBlob) {
+    // Delete from Vercel Blob
+    await del(url);
+  } else {
+    // Delete from local filesystem
+    // Extract pathname from URL (e.g., /uploads/avatars/avatar.png -> avatars/avatar.png)
+    const pathname = url.replace(/^\/uploads\//, "");
+    const filepath = join(process.cwd(), "public", "uploads", pathname);
+
+    // Only attempt to delete if file exists
+    if (existsSync(filepath)) {
+      const { unlink } = await import("fs/promises");
+      await unlink(filepath);
+    }
+  }
+}
+