x/wiki
1
0
Fork 0
mirror of https://github.com/waynesutton/markdown-site.git synced 2026-01-11 20:08:57 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add Netlify deployment troubleshooting guide

Browse Source
This commit is contained in:
Wayne Sutton
2025-12-14 12:30:05 -08:00
parent 031792a64b
commit 9fa49cffbb
4 changed files with 293 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README.md
View File

@@ -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
```

112
content/blog/setup-guide.md
View File

@@ -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

176
prds/netlify-deploy-fix.md Normal file
View File

@@ -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)

26
src/pages/Home.tsx
View File

@@ -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
deploy your own.
. Read the{" "}
<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>