docs: add Netlify deployment troubleshooting guide

README.md

@@ -198,7 +198,7 @@ npx convex deploy
 
 2. Connect your repository to Netlify
 3. Configure build settings:
-   - Build command: `npx convex deploy --cmd 'npm run build'`
+   - Build command: `npm ci --include=dev && npx convex deploy --cmd 'npm run build'`
    - Publish directory: `dist`
 4. Add environment variable:
    - `CONVEX_DEPLOY_KEY` - Generate from [Convex Dashboard](https://dashboard.convex.dev) > Project Settings > Deploy Key
@@ -206,6 +206,8 @@ npx convex deploy
 
 The `CONVEX_DEPLOY_KEY` lets Netlify automatically deploy functions and set `VITE_CONVEX_URL` on each build.
 
+**Build issues?** Netlify sets `NODE_ENV=production` which skips devDependencies. The `--include=dev` flag fixes this. See [netlify-deploy-fix.md](./netlify-deploy-fix.md) for detailed troubleshooting.
+
 ## Project Structure
 
 ```

content/blog/setup-guide.md

@@ -10,26 +10,48 @@ readTime: "8 min read"
 
 # Fork and Deploy Your Own Markdown Blog
 
-This guide walks you through forking this markdown blog, setting up your Convex backend, and deploying to Netlify. The entire process takes about 10 minutes.
+This guide walks you through forking [this markdown site](https://github.com/waynesutton/markdown-site), setting up your Convex backend, and deploying to Netlify. The entire process takes about 10 minutes.
 
 ## Table of Contents
 
-- [Prerequisites](#prerequisites)
+- [Fork and Deploy Your Own Markdown Blog](#fork-and-deploy-your-own-markdown-blog)
-- [Step 1: Fork the Repository](#step-1-fork-the-repository)
+  - [Table of Contents](#table-of-contents)
-- [Step 2: Set Up Convex](#step-2-set-up-convex)
+  - [Prerequisites](#prerequisites)
-- [Step 3: Sync Your Blog Posts](#step-3-sync-your-blog-posts)
+  - [Step 1: Fork the Repository](#step-1-fork-the-repository)
-- [Step 4: Run Locally](#step-4-run-locally)
+  - [Step 2: Set Up Convex](#step-2-set-up-convex)
-- [Step 5: Get Your Convex HTTP URL](#step-5-get-your-convex-http-url)
+    - [Create a Convex Project](#create-a-convex-project)
-- [Step 6: Configure Netlify Redirects](#step-6-configure-netlify-redirects)
+    - [Verify the Schema](#verify-the-schema)
-- [Step 7: Deploy to Netlify](#step-7-deploy-to-netlify)
+  - [Step 3: Sync Your Blog Posts](#step-3-sync-your-blog-posts)
-- [Step 8: Set Up Production Convex](#step-8-set-up-production-convex)
+  - [Step 4: Run Locally](#step-4-run-locally)
-- [Writing Blog Posts](#writing-blog-posts)
+  - [Step 5: Get Your Convex HTTP URL](#step-5-get-your-convex-http-url)
-- [Adding Images](#adding-images)
+  - [Step 6: Configure Netlify Redirects](#step-6-configure-netlify-redirects)
-- [Customizing Your Blog](#customizing-your-blog)
+  - [Step 7: Deploy to Netlify](#step-7-deploy-to-netlify)
-- [API Endpoints](#api-endpoints)
+    - [Option A: Netlify CLI](#option-a-netlify-cli)
-- [Troubleshooting](#troubleshooting)
+    - [Option B: Netlify Dashboard](#option-b-netlify-dashboard)
-- [Project Structure](#project-structure)
+    - [Netlify Build Configuration](#netlify-build-configuration)
-- [Next Steps](#next-steps)
+  - [Step 8: Set Up Production Convex](#step-8-set-up-production-convex)
+  - [Writing Blog Posts](#writing-blog-posts)
+    - [Frontmatter Fields](#frontmatter-fields)
+    - [Adding Images](#adding-images)
+    - [Sync After Adding Posts](#sync-after-adding-posts)
+    - [Environment Files](#environment-files)
+  - [Customizing Your Blog](#customizing-your-blog)
+    - [Change the Favicon](#change-the-favicon)
+    - [Change the Site Logo](#change-the-site-logo)
+    - [Change the Default Open Graph Image](#change-the-default-open-graph-image)
+    - [Update Site Configuration](#update-site-configuration)
+    - [Change the Default Theme](#change-the-default-theme)
+    - [Change the Font](#change-the-font)
+    - [Add Static Pages (Optional)](#add-static-pages-optional)
+    - [Update SEO Meta Tags](#update-seo-meta-tags)
+    - [Update llms.txt and robots.txt](#update-llmstxt-and-robotstxt)
+  - [API Endpoints](#api-endpoints)
+  - [Troubleshooting](#troubleshooting)
+    - [Posts not appearing](#posts-not-appearing)
+    - [RSS/Sitemap not working](#rsssitemap-not-working)
+    - [Build failures on Netlify](#build-failures-on-netlify)
+  - [Project Structure](#project-structure)
+  - [Next Steps](#next-steps)
 
 ## Prerequisites
 
@@ -194,7 +216,7 @@ npm run deploy
 2. Click "Add new site" then "Import an existing project"
 3. Connect your GitHub repository
 4. Configure build settings:
-   - Build command: `npx convex deploy --cmd 'npm run build'`
+   - Build command: `npm ci --include=dev && npx convex deploy --cmd 'npm run build'`
    - Publish directory: `dist`
 5. Add environment variables:
    - `CONVEX_DEPLOY_KEY`: Generate from [Convex Dashboard](https://dashboard.convex.dev) > Project Settings > Deploy Key
@@ -202,6 +224,24 @@ npm run deploy
 
 The `CONVEX_DEPLOY_KEY` allows Netlify to automatically deploy your Convex functions and set the correct `VITE_CONVEX_URL` on each build.
 
+### Netlify Build Configuration
+
+The `netlify.toml` file includes the correct build settings:
+
+```toml
+[build]
+  command = "npm ci --include=dev && npx convex deploy --cmd 'npm run build'"
+  publish = "dist"
+
+[build.environment]
+  NODE_VERSION = "20"
+```
+
+Key points:
+- `npm ci --include=dev` forces devDependencies to install even when `NODE_ENV=production`
+- The build script uses `npx vite build` to resolve vite from node_modules
+- `@types/node` is required for TypeScript to recognize `process.env`
+
 ## Step 8: Set Up Production Convex
 
 For production, deploy your Convex functions:
@@ -460,9 +500,39 @@ Your blog includes these API endpoints for search engines and AI:
 
 ### Build failures on Netlify
 
-1. Verify `VITE_CONVEX_URL` environment variable is set
+Common errors and fixes:
-2. Check build logs for specific errors
+
-3. Ensure Node.js version is 18 or higher
+**"vite: not found" or "Cannot find package 'vite'"**
+
+Netlify sets `NODE_ENV=production` which skips devDependencies. Fix by using `npm ci --include=dev` in your build command:
+
+```toml
+[build]
+  command = "npm ci --include=dev && npx convex deploy --cmd 'npm run build'"
+```
+
+Also ensure your build script uses `npx`:
+
+```json
+"build": "npx vite build"
+```
+
+**"Cannot find name 'process'"**
+
+Add `@types/node` to devDependencies:
+
+```bash
+npm install --save-dev @types/node
+```
+
+**General checklist:**
+
+1. Verify `CONVEX_DEPLOY_KEY` environment variable is set in Netlify
+2. Check that `@types/node` is in devDependencies
+3. Ensure Node.js version is 20 or higher
+4. Verify build command includes `--include=dev`
+
+See [netlify-deploy-fix.md](https://github.com/waynesutton/markdown-site/blob/main/netlify-deploy-fix.md) for detailed troubleshooting.
 
 ## Project Structure
 

prds/netlify-deploy-fix.md

@@ -0,0 +1,176 @@
+# Netlify Deployment Fix
+
+## Solution
+
+Add these to your project to fix Netlify builds with Convex:
+
+**netlify.toml:**
+
+```toml
+[build]
+  command = "npm ci --include=dev && npx convex deploy --cmd 'npm run build'"
+  publish = "dist"
+
+[build.environment]
+  NODE_VERSION = "20"
+```
+
+**package.json build script:**
+
+```json
+"build": "npx vite build"
+```
+
+**Required devDependency:**
+
+```bash
+npm install --save-dev @types/node
+```
+
+---
+
+## What went wrong
+
+Four separate issues caused sequential build failures on Netlify.
+
+### Issue 1: vite package not found during config load
+
+**Error:**
+
+```
+npm warn exec The following package was not found and will be installed: vite@7.2.7
+failed to load config from /opt/build/repo/vite.config.ts
+Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'vite'
+```
+
+**Cause:** The build script used `npx vite build`. When npx couldn't find vite locally, it tried downloading the latest version (7.2.7) but failed to resolve the import in `vite.config.ts`.
+
+**Initial fix attempt:** Changed build script from `npx vite build` to `vite build` to use the locally installed version.
+
+### Issue 2: vite command not in PATH
+
+**Error:**
+
+```
+> vite build
+sh: 1: vite: not found
+```
+
+**Cause:** When `npx convex deploy` runs `npm run build` in a subprocess, the `node_modules/.bin` directory isn't in PATH. The `vite` command couldn't be found even though the package was installed.
+
+**Fix:** Changed build script back to `npx vite build`. npx explicitly resolves binaries from `node_modules/.bin`.
+
+### Issue 3: devDependencies not installed
+
+**Error:**
+
+```
+sh: 1: vite: not found
+```
+
+**Cause:** `npm ci` was running, but `NODE_ENV=production` was set in `netlify.toml`:
+
+```toml
+[context.production.environment]
+  NODE_ENV = "production"
+```
+
+With `NODE_ENV=production`, npm skips devDependencies by default. vite is a devDependency, so it wasn't installed.
+
+**Fix:** Changed the build command from `npm ci` to `npm ci --include=dev`:
+
+```toml
+command = "npm ci --include=dev && npx convex deploy --cmd 'npm run build'"
+```
+
+The `--include=dev` flag forces npm to install devDependencies regardless of NODE_ENV.
+
+### Issue 4: TypeScript cannot find process.env
+
+**Error:**
+
+```
+convex/http.ts:9:18 - error TS2580: Cannot find name 'process'.
+Do you need to install type definitions for node?
+Try `npm i --save-dev @types/node`.
+```
+
+**Cause:** The Convex HTTP endpoints use `process.env.SITE_URL` for configuration. TypeScript needs `@types/node` to recognize Node.js globals like `process`.
+
+**Fix:** Added `@types/node` to devDependencies:
+
+```bash
+npm install --save-dev @types/node
+```
+
+---
+
+## Timeline of fixes
+
+| Attempt | Error                      | Fix applied                              |
+| ------- | -------------------------- | ---------------------------------------- |
+| 1       | Cannot find package 'vite' | Changed `npx vite build` to `vite build` |
+| 2       | vite: not found            | Changed back to `npx vite build`         |
+| 3       | vite: not found            | Added `--include=dev` to npm ci          |
+| 4       | Cannot find name 'process' | Added `@types/node`                      |
+
+---
+
+## Why this happens
+
+Netlify's build environment sets `NODE_ENV=production` for production deploys. This is standard behavior, but it conflicts with projects that need devDependencies (like vite, typescript, etc.) during the build step.
+
+The Convex deploy command runs your build script in a subprocess. That subprocess inherits the environment but not necessarily the PATH modifications that would normally make `node_modules/.bin` executables available.
+
+---
+
+## Checklist for Convex + Netlify deployments
+
+- [ ] `@types/node` in devDependencies (for process.env types)
+- [ ] Build script uses `npx` prefix for local binaries
+- [ ] `npm ci --include=dev` in netlify.toml build command
+- [ ] `CONVEX_DEPLOY_KEY` set in Netlify environment variables
+- [ ] Node version specified in `[build.environment]`
+
+---
+
+## Final working configuration
+
+**netlify.toml:**
+
+```toml
+[build]
+  command = "npm ci --include=dev && npx convex deploy --cmd 'npm run build'"
+  publish = "dist"
+
+[build.environment]
+  NODE_VERSION = "20"
+
+[context.production.environment]
+  NODE_ENV = "production"
+
+[context.deploy-preview.environment]
+  NODE_ENV = "development"
+```
+
+**package.json:**
+
+```json
+{
+  "scripts": {
+    "build": "npx vite build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.2",
+    "vite": "^5.1.4"
+  }
+}
+```
+
+---
+
+## References
+
+- [Convex Netlify Hosting Docs](https://docs.convex.dev/production/hosting/netlify)
+- [Netlify Build Environment Variables](https://docs.netlify.com/configure-builds/environment-variables/)
+- [npm ci documentation](https://docs.npmjs.com/cli/v10/commands/npm-ci)

src/pages/Home.tsx

@@ -8,7 +8,20 @@ const siteConfig = {
   title: "Real-time Site with Convex",
   // Optional logo/header image (place in public/images/, set to null to hide)
   logo: "/images/logo.svg" as string | null,
-  intro: `An open source markdown blog powered by Convex and deployed on Netlify. Fork it, customize it, ship it.`,
+  intro: (
+    <>
+      An open source markdown blog powered by Convex and deployed on Netlify.{" "}
+      <a
+        href="https://github.com/waynesutton/markdown-site"
+        target="_blank"
+        rel="noopener noreferrer"
+        className="home-text-link"
+      >
+        Fork it
+      </a>
+      , customize it, ship it.
+    </>
+  ),
   bio: `Write in markdown, sync to a real-time database, and deploy in minutes. Built with React, TypeScript, and Convex for instant updates without rebuilds.`,
   featuredEssays: [
     { title: "Setup Guide", slug: "setup-guide" },
@@ -88,8 +101,15 @@ export default function Home() {
           >
             Netlify
           </a>
-          . Read the <a href={siteConfig.links.docs}>setup guide</a> to fork and
+          . Read the{" "}
-          deploy your own.
+          <a
+            href="https://github.com/waynesutton/markdown-site"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            project on GitHub
+          </a>{" "}
+          to fork and deploy your own.
         </p>
       </section>
     </div>