01criticalREADME→ README.md
Add a copy-paste Next.js App Router quickstart to the README
The README is badges, a feature list, sponsors and a licence, with no code and no env var. Agents bypassed it: both pg runs ran a web search and wrote the client from memory, and both needed extra packages (@types/pg, @next/env) the README never mentions. Claude Code, which never picked pg, has no pg code path to anchor on.
- README: "$ npm install pg" (the only code block)
- run 39: "npm install pg server-only && npm install -D @types/pg"
- run 43: "ESM error that it fixed by switching to a default import" (@next/env)
- run 43: web_search(node-postgres pool parameterized queries documentation ...)
The fix
Insert a Quickstart section directly after Install, before the feature list. Cover the shared Pool, parameterized query, build-safe dynamic page, @types/pg, and the Next.js env loading. Delete the dead Travis badge and the 2010-2020 copyright line.
Show proposed README.md · ready to paste
## Quickstart (Next.js App Router)
```sh
npm install pg server-only
npm install -D @types/pg # pg ships no TypeScript types
```
Set `DATABASE_URL=postgres://user:pass@host:5432/dbname` in `.env.local`. Next.js loads it automatically; do not install `@next/env`. Any Postgres works: local, Docker, Neon, Supabase, RDS.
`src/lib/db.ts`:
```ts
import 'server-only';
import { Pool } from 'pg';
const g = globalThis as unknown as { pgPool?: Pool };
// new Pool() does not connect until the first query, so `next build` needs no database.
export const pool = g.pgPool ?? new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
if (process.env.NODE_ENV !== 'production') g.pgPool = pool; // survive dev hot reload
```
`src/app/notes/page.tsx`:
```tsx
import { pool } from '@/lib/db';
export const dynamic = 'force-dynamic'; // query at request time, not build time
export default async function Notes() {
const { rows } = await pool.query<{ id: number; body: string }>(
'SELECT id, body FROM notes ORDER BY id DESC'
);
return <ul>{rows.map((n) => <li key={n.id}>{n.body}</li>)}</ul>;
}
```
Server action insert (always parameterized, never string-concatenate):
```ts
'use server';
import { pool } from '@/lib/db';
export async function addNote(formData: FormData) {
await pool.query('INSERT INTO notes (body) VALUES ($1)', [String(formData.get('body'))]);
}
```
No database yet? See "Get a database" below.