01criticalREADME→ packages/core/supabase-js/README.md
Publish a README so the npm package page isn't empty
The README is absent on the package index. Agents begin by reading package.json and the repo files, never the Supabase site, so the npm README is the only vendor text in context. The repo AGENTS.md sends agents to `README.md` as the 'usage and quick start', which they never see. No transcript mentions Supabase.
- Surfaces: README (as shown on the package index): (absent)
- AGENTS.md: Usage and quick start: README.md
- run 390: No local Postgres or `DATABASE_URL`, so I'll use `pg`
The fix
Ship a README.md in the published package directory (and make sure `files` doesn't exclude it). Lead with install, env vars and where to get them, the one Next.js path for the notes-table, pgvector and storage jobs, and three common mistakes. Paste the patch.
Show proposed packages/core/supabase-js/README.md · ready to paste
# @supabase/supabase-js
> JavaScript client for Supabase: Postgres (via PostgREST), Auth, Storage, Realtime, Edge Functions. Needs a Supabase project (hosted or `supabase start`).
## Install
npm install @supabase/supabase-js
## Env vars (.env.local)
NEXT_PUBLIC_SUPABASE_URL=https://<project-ref>.supabase.co
NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=<publishable or legacy anon key>
Get both from Dashboard > Project Settings > API Keys, or from `supabase status` when running locally. Never put the service_role / secret key in a NEXT_PUBLIC_ var.
## Next.js (App Router) - one path
// lib/supabase.ts
import { createClient } from '@supabase/supabase-js'
export function getSupabase() {
const url = process.env.NEXT_PUBLIC_SUPABASE_URL
const key = process.env.NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY
if (!url || !key) return null // keeps `next build` green without credentials
return createClient(url, key)
}
## Job: list rows from a `notes` table
create table notes (id bigint generated always as identity primary key, body text not null, created_at timestamptz default now());
alter table notes enable row level security;
create policy 'public read' on notes for select using (true);
// app/notes/page.tsx (export const dynamic = 'force-dynamic')
const { data, error } = await getSupabase()!.from('notes').select('*').order('created_at', { ascending: false })
## Job: file uploads
Create a bucket in Dashboard > Storage, then:
await supabase.storage.from('avatars').upload(`${userId}/${file.name}`, file)
const { data } = supabase.storage.from('avatars').getPublicUrl(path)
## Job: vector search (pgvector)
create extension if not exists vector;
create table documents (id bigint generated always as identity primary key, content text, embedding vector(1536));
-- add a match_documents(query_embedding vector(1536), match_count int) SQL function, then:
const { data } = await supabase.rpc('match_documents', { query_embedding, match_count: 5 })
## Common mistakes
1. Empty results, no error: the table has RLS enabled but no policy.
2. Module-scope createClient with missing env breaks `next build`: create lazily.
3. Secret key in client code or a NEXT_PUBLIC_ var.
## Verify
npm run build && curl -s localhost:3000/notes | grep -c '<li'