From 6e21b3ed1fc7a0f2ec0d46e0a5ee4e33084c8a54 Mon Sep 17 00:00:00 2001
From: vicrodh <103399283+vicrodh@users.noreply.github.com>
Date: Wed, 14 Jan 2026 19:43:18 -0600
Subject: [PATCH] docs(dev): add script and docs for local API key loading

- Create dev-with-env.sh script to load .env before build
- Add npm run dev:tauri command that uses the script
- Document why .env must be loaded before compilation
- Explain compile-time vs runtime environment variables

The issue: option_env!() reads vars at compile time, but .env
loads at runtime. Solution: source .env before cargo build.

cp
---
 DEV_API_KEYS.md         | 45 +++++++++++++++++++++++++++++++++++++++++
 package.json            |  1 +
 scripts/dev-with-env.sh | 10 +++++++++
 3 files changed, 56 insertions(+)
 create mode 100644 DEV_API_KEYS.md
 create mode 100755 scripts/dev-with-env.sh

diff --git a/DEV_API_KEYS.md b/DEV_API_KEYS.md
new file mode 100644
index 000000000..52545416f
--- /dev/null
+++ b/DEV_API_KEYS.md
@@ -0,0 +1,45 @@
+# Development with API Keys
+
+## Problem
+
+The API keys in `.env` are embedded at **compile-time** using Rust's `option_env!()` macro, not at runtime. This means the `.env` file must be loaded into environment variables **before** compilation.
+
+## Solution for Local Development
+
+Use the custom script that loads `.env` before building:
+
+```bash
+npm run dev:tauri
+```
+
+This script:
+1. Sources the `.env` file into the shell environment
+2. Runs `npm run tauri dev` with those variables available during compilation
+
+## Alternative: Manual Export
+
+If you prefer to run `npm run tauri dev` directly, export the variables first:
+
+```bash
+# Load .env into current shell
+set -a
+source .env
+set +a
+
+# Now run dev
+npm run tauri dev
+```
+
+## Why This is Needed
+
+- **CI/CD builds**: Variables are injected via GitHub Secrets → environment → `option_env!()` at compile time
+- **Local development**: Variables must be in shell environment before `cargo build` runs
+- The `dotenvy::dotenv()` in `lib.rs` only loads variables at **runtime**, but `option_env!()` reads them at **compile time**
+
+## Embedded Keys
+
+The following keys are embedded at compile time:
+- `LAST_FM_API_KEY` / `LAST_FM_API_SHARED_SECRET`
+- `DISCOGS_API_CLIENT_KEY` / `DISCOGS_API_CLIENT_SECRET`
+- `SPOTIFY_API_CLIENT_ID` / `SPOTIFY_API_CLIENT_SECRET`
+- `TIDAL_API_CLIENT_ID` / `TIDAL_API_CLIENT_SECRET`
diff --git a/package.json b/package.json
index 70cba541f..00fe3ec74 100644
--- a/package.json
+++ b/package.json
@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "vite dev",
+    "dev:tauri": "./scripts/dev-with-env.sh",
     "build": "vite build",
     "preview": "vite preview",
     "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
diff --git a/scripts/dev-with-env.sh b/scripts/dev-with-env.sh
new file mode 100755
index 000000000..48938030f
--- /dev/null
+++ b/scripts/dev-with-env.sh
@@ -0,0 +1,10 @@
+#!/bin/bash
+# Development script that loads .env variables before building
+
+set -a
+if [ -f .env ]; then
+  source .env
+fi
+set +a
+
+npm run tauri dev