From d077b2a86d18595bf09cd263a646dd4546a98dd0 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 25 Jun 2026 02:12:57 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20polish=20bundle=20=E2=80=94=20muted-for?= =?UTF-8?q?eground=20token,=20getting-started,=20Neon=20URL?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three independent accuracy fixes from an independent review: - Define `--color-muted-foreground` in app/styles/app.css `@theme` so the `text-muted-foreground` utility used by the starter routes actually renders (Tailwind v4 emits nothing for an undefined color utility). Verified the built CSS now emits `.text-muted-foreground{color:var(--color-muted-foreground)}`. - Align the scaffold-generated README with the scaffold's "Next steps" output: one command order, and the DATABASE_URL step is now in both. - Clarify Neon guidance in .env.example and environment.md — with the neon-http driver the pooled vs. direct endpoint doesn't matter (the -pooler endpoint is for the WebSocket Pool driver). Closes #47. --- .env.example | 6 +++++- app/styles/app.css | 7 +++++++ changelog.d/47-polish-bundle.fixed.md | 3 +++ docs/agents/environment.md | 9 ++++----- docs/agents/styling.md | 5 +++++ scripts/scaffold.mjs | 9 +++++---- 6 files changed, 29 insertions(+), 10 deletions(-) create mode 100644 changelog.d/47-polish-bundle.fixed.md diff --git a/.env.example b/.env.example index 922533e..0a0be9a 100644 --- a/.env.example +++ b/.env.example @@ -1,4 +1,8 @@ # Neon serverless Postgres connection string. -# Get one at: https://neon.tech → New Project → Connection Details → copy the pooled URL. +# Get one at https://neon.tech → New Project → Connection Details. +# This template uses Neon's HTTP driver (drizzle-orm/neon-http), so the pooled +# vs. direct endpoint doesn't matter — either connection string works. (The +# -pooler endpoint is for the WebSocket `Pool` driver, which this template +# doesn't use.) # Format: postgresql://user:password@host/dbname?sslmode=require DATABASE_URL= diff --git a/app/styles/app.css b/app/styles/app.css index f1d8c73..b3f14ab 100644 --- a/app/styles/app.css +++ b/app/styles/app.css @@ -1 +1,8 @@ @import "tailwindcss"; + +@theme { + /* Muted/secondary text — backs the `text-muted-foreground` utility used by + the starter routes. Tailwind v4 emits nothing for an undefined color + utility, so this token must exist for that class to render. */ + --color-muted-foreground: oklch(0.556 0 0); +} diff --git a/changelog.d/47-polish-bundle.fixed.md b/changelog.d/47-polish-bundle.fixed.md new file mode 100644 index 0000000..39dbb0f --- /dev/null +++ b/changelog.d/47-polish-bundle.fixed.md @@ -0,0 +1,3 @@ +- `[propagate]` Defined the `--color-muted-foreground` theme token in `app/styles/app.css` so the `text-muted-foreground` utility used by the starter routes actually renders (Tailwind v4 emits nothing for an undefined color utility). +- `[propagate]` Aligned the scaffold-generated README with the scaffold's "Next steps" output — one command order, and the `DATABASE_URL` step is now in both. +- `[propagate]` Clarified Neon connection-string guidance in `.env.example` and `docs/agents/environment.md`: with the `neon-http` driver the pooled vs. direct endpoint doesn't matter (the `-pooler` endpoint is for the WebSocket `Pool` driver). diff --git a/docs/agents/environment.md b/docs/agents/environment.md index 60c62c1..a2c08e7 100644 --- a/docs/agents/environment.md +++ b/docs/agents/environment.md @@ -47,19 +47,18 @@ This project uses [Neon](https://neon.tech) — a serverless Postgres provider w 1. Go to [neon.tech](https://neon.tech) and sign in (GitHub login works). 2. Click **New Project** → choose a region close to you → **Create Project**. -3. On the project dashboard, click **Connection Details**. -4. Select the **Pooled connection** tab and copy the connection string. -5. Create `.env` at the project root and paste it in: +3. On the project dashboard, click **Connection Details** and copy the connection string. Either the **Pooled** or **Direct** endpoint works — this template uses Neon's HTTP driver (`drizzle-orm/neon-http`), so the `-pooler` distinction (which matters for the WebSocket `Pool` driver) doesn't apply here. +4. Create `.env` at the project root and paste it in: ```bash DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require ``` -6. Run `pnpm db:migrate` to apply the initial schema. +5. Run `pnpm db:migrate` to apply the initial schema. ### CI (GitHub Actions) 1. Go to your GitHub repo → **Settings** → **Secrets and variables** → **Actions**. 2. Click **New repository secret**. -3. Name: `CI_E2E_DATABASE_URL`, Value: the same pooled connection string from above. +3. Name: `CI_E2E_DATABASE_URL`, Value: the same connection string from above. 4. The CI workflow at `.github/workflows/ci.yml` reads `secrets.CI_E2E_DATABASE_URL` and injects it as `DATABASE_URL` for the E2E job. E2E steps are skipped when the secret is absent. diff --git a/docs/agents/styling.md b/docs/agents/styling.md index f1eba54..cc2d9db 100644 --- a/docs/agents/styling.md +++ b/docs/agents/styling.md @@ -22,6 +22,11 @@ This is the only global stylesheet. Keep it minimal: } ``` +The starter routes use the `text-muted-foreground` utility for secondary text; +its backing `--color-muted-foreground` token is defined in `app/styles/app.css`. +Tailwind v4 emits nothing for an undefined color utility, so the token must +exist for the class to render. + ## Rules - Use Tailwind utility classes exclusively in JSX. diff --git a/scripts/scaffold.mjs b/scripts/scaffold.mjs index f438861..0a0aa99 100644 --- a/scripts/scaffold.mjs +++ b/scripts/scaffold.mjs @@ -193,11 +193,12 @@ ${projectDescription} \`\`\`bash pnpm install -cp .env.example .env -pnpm test:e2e:install +cp .env.example .env # then fill in DATABASE_URL — see docs/agents/environment.md pnpm dev \`\`\` +Running E2E tests? Install browsers first with \`pnpm test:e2e:install\`. + ## For Agents Read [\`AGENTS.md\`](./AGENTS.md) before making any changes. @@ -336,7 +337,7 @@ console.log(` ✅ Done! Your project "${projectName}" is ready. Next steps: - 1. cp .env.example .env (and fill in DATABASE_URL — see docs/agents/environment.md) - 2. pnpm install + 1. pnpm install + 2. cp .env.example .env (then fill in DATABASE_URL — see docs/agents/environment.md) 3. pnpm dev `);