From c492b338b4a5412dffc13061a13cab0811cfcc68 Mon Sep 17 00:00:00 2001 From: Wayne Sutton Date: Sun, 14 Dec 2025 21:42:09 -0800 Subject: [PATCH] fix: require VITE_CONVEX_URL env var for edge functions and clarify publishing workflow - Add VITE_CONVEX_URL requirement to Netlify env vars for edge function runtime - Improve error messages in edge functions when Convex URL is missing - Add "How publishing works" explanation to README, setup guide, and docs - Update deployment instructions across all documentation --- README.md | 9 +++++++-- content/blog/setup-guide.md | 5 ++++- content/pages/docs.md | 8 ++++++-- netlify/edge-functions/api.ts | 10 +++++----- netlify/edge-functions/rss.ts | 7 ++++--- netlify/edge-functions/sitemap.ts | 7 ++++--- src/pages/Home.tsx | 2 +- 7 files changed, 31 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 2deed4a..9f4dd16 100644 --- a/README.md +++ b/README.md @@ -2,6 +2,8 @@ A minimalist markdown site built with React, Convex, and Vite. Optimized for SEO, AI agents, and LLM discovery. +**How publishing works:** Write posts in markdown, run `npm run sync`, and they appear on your live site immediately. No rebuild or redeploy needed. Convex handles real-time data sync, so all connected browsers update automatically. + ## Features - Markdown-based blog posts with frontmatter @@ -196,14 +198,17 @@ For detailed setup, see the [Convex Netlify Deployment Guide](https://docs.conve npx convex deploy ``` +Note the production URL (e.g., `https://your-deployment.convex.cloud`). + 2. Connect your repository to Netlify 3. Configure build settings: - Build command: `npm ci --include=dev && npx convex deploy --cmd 'npm run build'` - Publish directory: `dist` -4. Add environment variable: +4. Add environment variables in Netlify dashboard: - `CONVEX_DEPLOY_KEY` - Generate from [Convex Dashboard](https://dashboard.convex.dev) > Project Settings > Deploy Key + - `VITE_CONVEX_URL` - Your production Convex URL (e.g., `https://your-deployment.convex.cloud`) -The `CONVEX_DEPLOY_KEY` lets Netlify automatically deploy functions and set `VITE_CONVEX_URL` on each build. Edge functions dynamically proxy RSS, sitemap, and API requests to your Convex HTTP endpoints. +The `CONVEX_DEPLOY_KEY` deploys functions at build time. The `VITE_CONVEX_URL` is required for edge functions (RSS, sitemap, API) to proxy requests at runtime. **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. diff --git a/content/blog/setup-guide.md b/content/blog/setup-guide.md index e779517..3eb275e 100644 --- a/content/blog/setup-guide.md +++ b/content/blog/setup-guide.md @@ -12,6 +12,8 @@ readTime: "8 min read" 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. +**How publishing works:** Once deployed, you write posts in markdown, run `npm run sync`, and they appear on your live site immediately. No rebuild or redeploy needed. Convex handles real-time data sync, so all connected browsers update automatically. + ## Table of Contents - [Fork and Deploy Your Own Markdown Blog](#fork-and-deploy-your-own-markdown-blog) @@ -208,9 +210,10 @@ npm run deploy - Publish directory: `dist` 5. Add environment variables: - `CONVEX_DEPLOY_KEY`: Generate from [Convex Dashboard](https://dashboard.convex.dev) > Project Settings > Deploy Key + - `VITE_CONVEX_URL`: Your production Convex URL (e.g., `https://your-deployment.convex.cloud`) 6. Click "Deploy site" -The `CONVEX_DEPLOY_KEY` allows Netlify to automatically deploy your Convex functions and set the correct `VITE_CONVEX_URL` on each build. +The `CONVEX_DEPLOY_KEY` deploys functions at build time. The `VITE_CONVEX_URL` is required for edge functions to proxy RSS, sitemap, and API requests at runtime. ### Netlify Build Configuration diff --git a/content/pages/docs.md b/content/pages/docs.md index 221c12d..f16cb8a 100644 --- a/content/pages/docs.md +++ b/content/pages/docs.md @@ -7,6 +7,8 @@ order: 0 Reference documentation for setting up, customizing, and deploying this markdown site. +**How publishing works:** Write posts in markdown, run `npm run sync`, and they appear on your live site immediately. No rebuild or redeploy needed. Convex handles real-time data sync, so connected browsers update automatically. + ## Quick start ```bash @@ -194,9 +196,11 @@ body { 1. Connect GitHub repo to Netlify 2. Build command: `npm ci --include=dev && npx convex deploy --cmd 'npm run build'` 3. Publish directory: `dist` -4. Add env variable: `CONVEX_DEPLOY_KEY` (from Convex Dashboard) +4. Add env variables: + - `CONVEX_DEPLOY_KEY` (from Convex Dashboard > Project Settings > Deploy Key) + - `VITE_CONVEX_URL` (your production Convex URL, e.g., `https://your-deployment.convex.cloud`) -The build automatically sets `VITE_CONVEX_URL` from the deploy key. +Both are required: deploy key for builds, URL for edge function runtime. ### Convex production diff --git a/netlify/edge-functions/api.ts b/netlify/edge-functions/api.ts index a8e797a..f25feb5 100644 --- a/netlify/edge-functions/api.ts +++ b/netlify/edge-functions/api.ts @@ -10,11 +10,11 @@ export default async function handler( if (!convexUrl) { return new Response( - JSON.stringify({ error: "Configuration error: Missing Convex URL" }), - { - status: 500, - headers: { "Content-Type": "application/json" }, - }, + JSON.stringify({ + error: + "VITE_CONVEX_URL not set. Add it to Netlify environment variables.", + }), + { status: 500, headers: { "Content-Type": "application/json" } }, ); } diff --git a/netlify/edge-functions/rss.ts b/netlify/edge-functions/rss.ts index b6f132e..4be54ad 100644 --- a/netlify/edge-functions/rss.ts +++ b/netlify/edge-functions/rss.ts @@ -9,9 +9,10 @@ export default async function handler( Deno.env.get("VITE_CONVEX_URL") || Deno.env.get("CONVEX_URL"); if (!convexUrl) { - return new Response("Configuration error: Missing Convex URL", { - status: 500, - }); + return new Response( + "Configuration error: VITE_CONVEX_URL not set. Add it to Netlify environment variables.", + { status: 500, headers: { "Content-Type": "text/plain" } }, + ); } // Construct the Convex site URL for the HTTP endpoint diff --git a/netlify/edge-functions/sitemap.ts b/netlify/edge-functions/sitemap.ts index e0fdcde..4d9d84a 100644 --- a/netlify/edge-functions/sitemap.ts +++ b/netlify/edge-functions/sitemap.ts @@ -9,9 +9,10 @@ export default async function handler( Deno.env.get("VITE_CONVEX_URL") || Deno.env.get("CONVEX_URL"); if (!convexUrl) { - return new Response("Configuration error: Missing Convex URL", { - status: 500, - }); + return new Response( + "Configuration error: VITE_CONVEX_URL not set. Add it to Netlify environment variables.", + { status: 500, headers: { "Content-Type": "text/plain" } }, + ); } // Construct the Convex site URL for the HTTP endpoint diff --git a/src/pages/Home.tsx b/src/pages/Home.tsx index f15c253..4a80f52 100644 --- a/src/pages/Home.tsx +++ b/src/pages/Home.tsx @@ -22,7 +22,7 @@ const siteConfig = { , 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.`, + bio: `Write in markdown, sync to a real-time database, and deploy in minutes. Every time you sync new posts, they appear immediately without redeploying. Built with React, TypeScript, and Convex for instant updates.`, featuredEssays: [ { title: "Setup Guide", slug: "setup-guide" }, { title: "How to Publish", slug: "how-to-publish" },