Skip to content

docs(fumadocs): document NOTRA_API_KEY turbo passthrough and empty-blog troubleshooting #118

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
tembo wants to merge 1 commit into from
Closed

docs(fumadocs): document NOTRA_API_KEY turbo passthrough and empty-blog troubleshooting #118

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 26 additions & 3 deletions apps/fumadocs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,12 +25,35 @@ API key on the server, and means there are no Notra calls from the browser.
```

- **Environment** — set `NOTRA_API_KEY`:
- Local: `apps/fumadocs/.env.local` (gitignored).
- Production: add `NOTRA_API_KEY` to the Vercel project's environment variables.
- Local: `apps/fumadocs/.env.local` (gitignored). Bun auto-loads this file, so
local builds pick up the key without any extra wiring.
- Production: add `NOTRA_API_KEY` to the Vercel project's environment variables
**and** keep it listed in `passThroughEnv` in `apps/fumadocs/turbo.json`.
Turbo runs in strict env mode, so it strips any variable the build task does
not explicitly declare — a Vercel env var that is not in `passThroughEnv`
never reaches `scripts/fetch-notra-posts.ts`.

Without the key the fetch is skipped and the last committed snapshot is kept,
so the build never fails.

New posts appear on the next deploy. The `Refresh blog posts from Notra` GitHub
workflow triggers a weekly Vercel rebuild; you can also point a Notra publish
workflow triggers a daily Vercel rebuild; you can also point a Notra publish
webhook at the same Vercel deploy hook for instant updates.

### Troubleshooting: the deployed blog is empty

If the live blog renders no posts even though they are published in Notra, the
build almost certainly ran without the API key:

1. Check the Vercel build log for
`[notra] NOTRA_API_KEY is not set — skipping fetch`. When you see it, the
fetch was skipped and the committed (often empty) snapshot was shipped.
2. Confirm `NOTRA_API_KEY` is set on the Vercel project **and** that
`"passThroughEnv": ["NOTRA_API_KEY"]` is present in `apps/fumadocs/turbo.json`.
Missing the `passThroughEnv` entry is the usual cause: the key exists in
Vercel but turbo's strict env mode hides it from the build.
3. Redeploy. A successful run logs
`[notra] wrote N published post(s) to src/lib/notra-posts.generated.ts`.

Local builds can mask this because Bun loads `.env.local` directly, bypassing
turbo's env filtering — so a missing `passThroughEnv` only surfaces in CI/Vercel.