diff --git a/README.md b/README.md index ee80690..986dc21 100644 --- a/README.md +++ b/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 ``` diff --git a/content/blog/setup-guide.md b/content/blog/setup-guide.md index 4641e3c..c2f179f 100644 --- a/content/blog/setup-guide.md +++ b/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) -- [Step 1: Fork the Repository](#step-1-fork-the-repository) -- [Step 2: Set Up Convex](#step-2-set-up-convex) -- [Step 3: Sync Your Blog Posts](#step-3-sync-your-blog-posts) -- [Step 4: Run Locally](#step-4-run-locally) -- [Step 5: Get Your Convex HTTP URL](#step-5-get-your-convex-http-url) -- [Step 6: Configure Netlify Redirects](#step-6-configure-netlify-redirects) -- [Step 7: Deploy to Netlify](#step-7-deploy-to-netlify) -- [Step 8: Set Up Production Convex](#step-8-set-up-production-convex) -- [Writing Blog Posts](#writing-blog-posts) -- [Adding Images](#adding-images) -- [Customizing Your Blog](#customizing-your-blog) -- [API Endpoints](#api-endpoints) -- [Troubleshooting](#troubleshooting) -- [Project Structure](#project-structure) -- [Next Steps](#next-steps) +- [Fork and Deploy Your Own Markdown Blog](#fork-and-deploy-your-own-markdown-blog) + - [Table of Contents](#table-of-contents) + - [Prerequisites](#prerequisites) + - [Step 1: Fork the Repository](#step-1-fork-the-repository) + - [Step 2: Set Up Convex](#step-2-set-up-convex) + - [Create a Convex Project](#create-a-convex-project) + - [Verify the Schema](#verify-the-schema) + - [Step 3: Sync Your Blog Posts](#step-3-sync-your-blog-posts) + - [Step 4: Run Locally](#step-4-run-locally) + - [Step 5: Get Your Convex HTTP URL](#step-5-get-your-convex-http-url) + - [Step 6: Configure Netlify Redirects](#step-6-configure-netlify-redirects) + - [Step 7: Deploy to Netlify](#step-7-deploy-to-netlify) + - [Option A: Netlify CLI](#option-a-netlify-cli) + - [Option B: Netlify Dashboard](#option-b-netlify-dashboard) + - [Netlify Build Configuration](#netlify-build-configuration) + - [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 -2. Check build logs for specific errors -3. Ensure Node.js version is 18 or higher +Common errors and fixes: + +**"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 diff --git a/prds/netlify-deploy-fix.md b/prds/netlify-deploy-fix.md new file mode 100644 index 0000000..34c90ea --- /dev/null +++ b/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) diff --git a/src/pages/Home.tsx b/src/pages/Home.tsx index 206b227..f15c253 100644 --- a/src/pages/Home.tsx +++ b/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.{" "} + + Fork it + + , 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 - . Read the setup guide to fork and - deploy your own. + . Read the{" "} + + project on GitHub + {" "} + to fork and deploy your own.