From c9b5060b2423328d868f9d5ecfcd914efe0e7a5a Mon Sep 17 00:00:00 2001 From: Andy Grunwald Date: Sun, 24 May 2026 12:12:17 +0200 Subject: [PATCH 1/6] fix(db): load apps/api/.env when running prisma migrate dev The `migrate:dev` script runs Prisma from packages/db, where no .env file exists (only .env.example). Prisma reads its DATABASE_URL and DIRECT_DATABASE_URL from process.env at the current working directory, so the command was failing to find connection details and could not run migrations without the developer also creating a duplicate .env inside packages/db. Wrap the command with dotenv-cli pointing at ../../apps/api/.env so a single env file (the API's own .env, already loaded by apps/api/src/app/constants.ts) serves both the API and DB migrations in local development. Co-Authored-By: Claude Opus 4.7 (1M context) --- packages/db/package.json | 3 ++- yarn.lock | 33 ++++++++++++++++++++++++++++++++- 2 files changed, 34 insertions(+), 2 deletions(-) diff --git a/packages/db/package.json b/packages/db/package.json index ad01499e..c44b5937 100644 --- a/packages/db/package.json +++ b/packages/db/package.json @@ -6,7 +6,7 @@ "types": "./dist/index.d.ts", "scripts": { "db:generate": "prisma generate", - "migrate:dev": "prisma migrate dev", + "migrate:dev": "dotenv -e ../../apps/api/.env -- prisma migrate dev", "migrate:prod": "prisma migrate deploy", "clean": "rimraf node_modules .turbo dist", "build": "tsc && prisma generate" @@ -17,6 +17,7 @@ }, "devDependencies": { "@types/node": "^24.10.0", + "dotenv-cli": "^11.0.0", "ts-node": "^10.9.2", "typescript": "^5.7.2" } diff --git a/yarn.lock b/yarn.lock index fc23a6a4..b28545a0 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3247,6 +3247,7 @@ __metadata: dependencies: "@prisma/client": "npm:^6.19.0" "@types/node": "npm:^24.10.0" + dotenv-cli: "npm:^11.0.0" prisma: "npm:^6.19.0" ts-node: "npm:^10.9.2" typescript: "npm:^5.7.2" @@ -9866,7 +9867,30 @@ __metadata: languageName: node linkType: hard -"dotenv@npm:^16.6.1": +"dotenv-cli@npm:^11.0.0": + version: 11.0.0 + resolution: "dotenv-cli@npm:11.0.0" + dependencies: + cross-spawn: "npm:^7.0.6" + dotenv: "npm:^17.1.0" + dotenv-expand: "npm:^12.0.0" + minimist: "npm:^1.2.6" + bin: + dotenv: cli.js + checksum: 10c0/c3e6e58a484b3204eeb167a8f78c9cb04c4bae951069e7860eccbbbf96964e3bd808b3632dfe841e5d882b2c5d77c447f20abd06edd4db623ce719d94a7fb44e + languageName: node + linkType: hard + +"dotenv-expand@npm:^12.0.0": + version: 12.0.3 + resolution: "dotenv-expand@npm:12.0.3" + dependencies: + dotenv: "npm:^16.4.5" + checksum: 10c0/0824bdc74fc816a28b0744b7853a23e046602e9616c82121dfdae21ebc13c6e89afeb773e794e97c35d48be2be0a990fbca721ee3869a49c04210a58a3cf296f + languageName: node + linkType: hard + +"dotenv@npm:^16.4.5, dotenv@npm:^16.6.1": version: 16.6.1 resolution: "dotenv@npm:16.6.1" checksum: 10c0/15ce56608326ea0d1d9414a5c8ee6dcf0fffc79d2c16422b4ac2268e7e2d76ff5a572d37ffe747c377de12005f14b3cc22361e79fc7f1061cce81f77d2c973dc @@ -9880,6 +9904,13 @@ __metadata: languageName: node linkType: hard +"dotenv@npm:^17.1.0": + version: 17.4.2 + resolution: "dotenv@npm:17.4.2" + checksum: 10c0/164f8e77a646c8446867d5b588d26ea6005c8ea7c5eb41cf926f6113d23f2191355f6e0cfd95ea9bab98394a5b0a3f1e51a8399711b666fe55cc7b0bd745f942 + languageName: node + linkType: hard + "dunder-proto@npm:^1.0.0, dunder-proto@npm:^1.0.1": version: 1.0.1 resolution: "dunder-proto@npm:1.0.1" From e4dd25e01afea7d92e55855c6253919348c829c8 Mon Sep 17 00:00:00 2001 From: Andy Grunwald Date: Sun, 24 May 2026 12:12:23 +0200 Subject: [PATCH 2/6] fix(api): pre-seed dummy AWS SES credentials in .env.example The api-server's env validator throws on empty AWS_SES_ACCESS_KEY_ID or AWS_SES_SECRET_ACCESS_KEY, which prevents new contributors from booting the server out of the box after a plain `cp apps/api/.env.example apps/api/.env`. Seed harmless placeholder values (foo / bar) so the server starts without further configuration. Contributors who actually want to send mail still need to replace these with real keys; the placeholders only satisfy the boot-time presence check. Co-Authored-By: Claude Opus 4.7 (1M context) --- apps/api/.env.example | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apps/api/.env.example b/apps/api/.env.example index 2d8beb7f..1ab33a6e 100644 --- a/apps/api/.env.example +++ b/apps/api/.env.example @@ -48,8 +48,8 @@ S3_FORCE_PATH_STYLE=true # AWS SES (Required - for sending emails) # ============================================================================== AWS_SES_REGION=eu-north-1 -AWS_SES_ACCESS_KEY_ID= -AWS_SES_SECRET_ACCESS_KEY= +AWS_SES_ACCESS_KEY_ID=foo +AWS_SES_SECRET_ACCESS_KEY=bar # Configuration sets for email tracking SES_CONFIGURATION_SET=plunk-configuration-set # Default: with open/click tracking From 72ef3f1f5aa2df79fc4a63cc21e3a8a349ec165c Mon Sep 17 00:00:00 2001 From: Andy Grunwald Date: Sun, 24 May 2026 12:12:31 +0200 Subject: [PATCH 3/6] docs: clarify local dev setup steps in CONTRIBUTING.md New contributors hit two snags when following the existing instructions: 1. The clone example used a `` placeholder and an `app` directory name that doesn't match the actual repo, so the rest of the commands silently failed for anyone copy-pasting. 2. There was no instruction to copy `apps/api/.env.example` to `apps/api/.env`, which is now required for both the API and the DB migrations (see the migrate:dev wrapper). Replace the placeholder with the real repo URL, add the missing `apps/api/.env` copy step, and note that AWS_SES_ACCESS_KEY_ID and AWS_SES_SECRET_ACCESS_KEY must be non-empty for the server to start (the dummies in .env.example are intentional). Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f2d860ee..b0c166c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -45,8 +45,8 @@ For local development without Docker: ```bash # Clone and install -git clone -cd app +git clone git@github.com:useplunk/plunk.git +cd plunk yarn install # Start infrastructure services (PostgreSQL, Redis, MinIO) @@ -54,7 +54,12 @@ yarn services:up # Set up environment variables cp .env.example .env +cp apps/api/.env.example apps/api/.env + # Edit .env with your configuration +# Important! To start the api-server, the two variables `AWS_SES_ACCESS_KEY_ID` and `AWS_SES_SECRET_ACCESS_KEY` must not be empty. +# Dummy values are pre-set to enable local development (without the ability to send emails). +# If you plan to send emails in your development environment, replace the dummy values in `apps/api/.env`. # Run database migrations yarn workspace @plunk/db migrate:dev From 2c39b19b121fd9a24506164b5670a6dc2475fd51 Mon Sep 17 00:00:00 2001 From: Andy Grunwald Date: Sun, 24 May 2026 12:19:33 +0200 Subject: [PATCH 4/6] docs: drop stale root .env copy step from CONTRIBUTING.md The instruction to `cp .env.example .env` referenced a root-level .env.example that does not exist in the repo (only `.env.self-host.example` sits at the root, and that one is for self-hosting, not local dev). After the previous commit's `cp apps/api/.env.example apps/api/.env` step, the remaining root copy was both invalid and confusing. Remove it and clarify the follow-up comment to point at apps/api/.env specifically, so contributors aren't left wondering which .env to edit. Co-Authored-By: Claude Opus 4.7 (1M context) --- CONTRIBUTING.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b0c166c4..fe0a289b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,10 +53,9 @@ yarn install yarn services:up # Set up environment variables -cp .env.example .env cp apps/api/.env.example apps/api/.env -# Edit .env with your configuration +# Edit apps/api/.env with your configuration # Important! To start the api-server, the two variables `AWS_SES_ACCESS_KEY_ID` and `AWS_SES_SECRET_ACCESS_KEY` must not be empty. # Dummy values are pre-set to enable local development (without the ability to send emails). # If you plan to send emails in your development environment, replace the dummy values in `apps/api/.env`. From fb2b691ef530b9fbbf6f4d2dc8e37a707e59cf26 Mon Sep 17 00:00:00 2001 From: Andy Grunwald Date: Sun, 24 May 2026 17:35:51 +0200 Subject: [PATCH 5/6] Revert "fix(db): load apps/api/.env when running prisma migrate dev" This reverts commit c9b5060b2423328d868f9d5ecfcd914efe0e7a5a. --- packages/db/package.json | 3 +-- yarn.lock | 33 +-------------------------------- 2 files changed, 2 insertions(+), 34 deletions(-) diff --git a/packages/db/package.json b/packages/db/package.json index c44b5937..ad01499e 100644 --- a/packages/db/package.json +++ b/packages/db/package.json @@ -6,7 +6,7 @@ "types": "./dist/index.d.ts", "scripts": { "db:generate": "prisma generate", - "migrate:dev": "dotenv -e ../../apps/api/.env -- prisma migrate dev", + "migrate:dev": "prisma migrate dev", "migrate:prod": "prisma migrate deploy", "clean": "rimraf node_modules .turbo dist", "build": "tsc && prisma generate" @@ -17,7 +17,6 @@ }, "devDependencies": { "@types/node": "^24.10.0", - "dotenv-cli": "^11.0.0", "ts-node": "^10.9.2", "typescript": "^5.7.2" } diff --git a/yarn.lock b/yarn.lock index b28545a0..fc23a6a4 100644 --- a/yarn.lock +++ b/yarn.lock @@ -3247,7 +3247,6 @@ __metadata: dependencies: "@prisma/client": "npm:^6.19.0" "@types/node": "npm:^24.10.0" - dotenv-cli: "npm:^11.0.0" prisma: "npm:^6.19.0" ts-node: "npm:^10.9.2" typescript: "npm:^5.7.2" @@ -9867,30 +9866,7 @@ __metadata: languageName: node linkType: hard -"dotenv-cli@npm:^11.0.0": - version: 11.0.0 - resolution: "dotenv-cli@npm:11.0.0" - dependencies: - cross-spawn: "npm:^7.0.6" - dotenv: "npm:^17.1.0" - dotenv-expand: "npm:^12.0.0" - minimist: "npm:^1.2.6" - bin: - dotenv: cli.js - checksum: 10c0/c3e6e58a484b3204eeb167a8f78c9cb04c4bae951069e7860eccbbbf96964e3bd808b3632dfe841e5d882b2c5d77c447f20abd06edd4db623ce719d94a7fb44e - languageName: node - linkType: hard - -"dotenv-expand@npm:^12.0.0": - version: 12.0.3 - resolution: "dotenv-expand@npm:12.0.3" - dependencies: - dotenv: "npm:^16.4.5" - checksum: 10c0/0824bdc74fc816a28b0744b7853a23e046602e9616c82121dfdae21ebc13c6e89afeb773e794e97c35d48be2be0a990fbca721ee3869a49c04210a58a3cf296f - languageName: node - linkType: hard - -"dotenv@npm:^16.4.5, dotenv@npm:^16.6.1": +"dotenv@npm:^16.6.1": version: 16.6.1 resolution: "dotenv@npm:16.6.1" checksum: 10c0/15ce56608326ea0d1d9414a5c8ee6dcf0fffc79d2c16422b4ac2268e7e2d76ff5a572d37ffe747c377de12005f14b3cc22361e79fc7f1061cce81f77d2c973dc @@ -9904,13 +9880,6 @@ __metadata: languageName: node linkType: hard -"dotenv@npm:^17.1.0": - version: 17.4.2 - resolution: "dotenv@npm:17.4.2" - checksum: 10c0/164f8e77a646c8446867d5b588d26ea6005c8ea7c5eb41cf926f6113d23f2191355f6e0cfd95ea9bab98394a5b0a3f1e51a8399711b666fe55cc7b0bd745f942 - languageName: node - linkType: hard - "dunder-proto@npm:^1.0.0, dunder-proto@npm:^1.0.1": version: 1.0.1 resolution: "dunder-proto@npm:1.0.1" From b7580075b02bba300146a11adaa341638b7069b9 Mon Sep 17 00:00:00 2001 From: Andy Grunwald Date: Sun, 24 May 2026 17:50:10 +0200 Subject: [PATCH 6/6] docs: Fix local development setup guide, by providing the right DATABASE_URL / DIRECT_DATABASE_URL env vars --- CONTRIBUTING.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe0a289b..c3019200 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,7 @@ yarn services:up # Set up environment variables cp apps/api/.env.example apps/api/.env +cp packages/db/.env.example packages/db/.env # Edit apps/api/.env with your configuration # Important! To start the api-server, the two variables `AWS_SES_ACCESS_KEY_ID` and `AWS_SES_SECRET_ACCESS_KEY` must not be empty.