From dd9843172b5d1d6d06f2179841412b9b7d0753b7 Mon Sep 17 00:00:00 2001 From: Santhi Prakash <38608178+santhiprakash@users.noreply.github.com> Date: Fri, 14 Aug 2026 02:20:48 +0530 Subject: [PATCH] docs(contributing): align development guide with dotenvx workflow (#3286) * docs(contributing): align development guide with dotenvx workflow - Problem: development.mdx told contributors to use a root `.env` file and export DATABASE_URL manually, while AGENTS.md and compose.dev.yml use `.env.local` loaded through dotenvx for dev and migration commands. - Fix: update the setup, migration, dev-server, and database sections to match the dotenvx commands documented in AGENTS.md. - Verification: preflight_ship.py (upstream bug marker present); duplicate PR check clean; docs-only change. * docs(contributing): add cp command to env setup step - Problem: setup step said to copy .env.example but the bash block only listed variable assignments. - Fix: add explicit cp .env.example .env.local command and label the following block as edits. - Verification: manual review of development.mdx; addresses CodeRabbit review on #3286. * docs(contributing): align AGENTS.md env copy target with dotenvx - Problem: AGENTS.md told contributors to copy .env.example to .env while all dev commands use .env.local. - Fix: update the copy instruction to .env.local for consistency with the dotenvx workflow. - Verification: manual review; folded into #3286 dotenvx alignment PR. * docs(contributing): dotenvx-wrap remaining dev script references - Problem: scripts table and troubleshooting still showed bare pnpm dev/db commands after the dotenvx workflow update. - Fix: prefix dev, db, and port-override examples with dotenvx run -f .env.local --. - Verification: manual review of development.mdx; folded into #3286. --------- Co-authored-by: Amruth Pillai --- AGENTS.md | 2 +- docs/contributing/development.mdx | 34 ++++++++++++++++++------------- 2 files changed, 21 insertions(+), 15 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e64c479f2..3d5c1d3e6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -107,7 +107,7 @@ The production server runs migrations during startup before serving traffic. Man ### Environment -Copy `.env.example` to `.env`. The three required variables are: +Copy `.env.example` to `.env.local`. The three required variables are: - `APP_URL` (default `http://localhost:3000`) - `DATABASE_URL` (default `postgresql://postgres:postgres@localhost:5432/postgres`) diff --git a/docs/contributing/development.mdx b/docs/contributing/development.mdx index 4207a8415..d3fa96ac9 100644 --- a/docs/contributing/development.mdx +++ b/docs/contributing/development.mdx @@ -57,8 +57,14 @@ This guide walks you through setting up Reactive Resume for local development. W - Create a `.env` file in the project root: - + Copy `.env.example` to `.env.local` in the project root: + + ```bash + cp .env.example .env.local + ``` + + Then edit `.env.local` as needed — for local development on the host, set at minimum: + ```bash # Application PORT=3000 @@ -96,16 +102,16 @@ This guide walks you through setting up Reactive Resume for local development. W The server startup path runs migrations before serving traffic. To apply migrations manually without starting the app, - export `DATABASE_URL` because Drizzle Kit reads directly from `process.env`: + load `.env.local` with `dotenvx` because Drizzle Kit reads directly from `process.env`: ```bash - DATABASE_URL="postgresql://postgres:postgres@localhost:5432/postgres" pnpm run db:migrate + dotenvx run -f .env.local -- pnpm run db:migrate ``` ```bash - pnpm run dev + dotenvx run -f .env.local -- pnpm run dev ``` Your local Reactive Resume instance will be available at [http://localhost:3000](http://localhost:3000). @@ -122,7 +128,7 @@ Here are the most commonly used scripts during development: | Command | Description | | ------------------------------ | ----------------------------------------------------------- | -| `pnpm dev` | Start the web and server development processes | +| `dotenvx run -f .env.local -- pnpm dev` | Start the web and server development processes | | `pnpm build` | Build the production web bundle and server bundle | | `pnpm start` | Start the built production server | | `pnpm typecheck` | Run TypeScript type checking | @@ -135,9 +141,9 @@ Here are the most commonly used scripts during development: | Command | Description | | ---------------------- | -------------------------------------------- | -| `pnpm run db:generate` | Generate migration files from schema changes | -| `pnpm run db:migrate` | Apply pending migrations | -| `pnpm run db:studio` | Open Drizzle Studio (database GUI) | +| `dotenvx run -f .env.local -- pnpm run db:generate` | Generate migration files from schema changes | +| `dotenvx run -f .env.local -- pnpm run db:migrate` | Apply pending migrations | +| `dotenvx run -f .env.local -- pnpm run db:studio` | Open Drizzle Studio (database GUI) | ### Internationalization @@ -180,7 +186,7 @@ reactive-resume/ Use Drizzle Studio to explore and manage your database: ```bash -pnpm run db:studio +dotenvx run -f .env.local -- pnpm run db:studio ``` This opens a web-based GUI at [https://local.drizzle.studio](https://local.drizzle.studio). @@ -190,11 +196,11 @@ This opens a web-based GUI at [https://local.drizzle.studio](https://local.drizz 1. Edit the schema in `packages/db/src/schema/*` 2. Generate a migration: ```bash - pnpm run db:generate + dotenvx run -f .env.local -- pnpm run db:generate ``` 3. Apply the migration: ```bash - pnpm run db:migrate + dotenvx run -f .env.local -- pnpm run db:migrate ``` Always review generated migrations before applying them, especially when working with existing data. @@ -268,7 +274,7 @@ pnpm run typecheck The Vite web server uses `PORT` (default `3000`), and the Hono server uses `SERVER_PORT` (default `3001`). Either stop the conflicting process or choose alternate ports: ```bash - PORT=3002 SERVER_PORT=3003 pnpm dev + PORT=3002 SERVER_PORT=3003 dotenvx run -f .env.local -- pnpm dev ``` @@ -296,7 +302,7 @@ pnpm run typecheck The route tree may need regeneration. Run the dev server which auto-generates routes: ```bash - pnpm run dev + dotenvx run -f .env.local -- pnpm run dev ``` Or run type checking to see specific errors: ```bash