feat: explicit cors config shape ('default' | 'disabled' | { headers })

[mandarini]

Makes the withSupabase cors option an explicit shape ('default' | 'disabled' | { headers }) instead of the ambiguous boolean | Record<string, string>. The old forms remain accepted but are deprecated, so this is non-breaking. Addresses SDK-1149 from the API review report.

What kind of change does this PR introduce?

Feature (API cleanup), plus docs and tests. Non-breaking.

What is the current behavior?

cors accepts boolean | Record<string, string>:

• true (default) applies the standard supabase-js CORS headers
• false disables CORS handling
• a Record<string, string> sets custom headers

This mixes a boolean sentinel with a bare header hash under one field, which is hard to type, document, and evolve.

What is the new behavior?

cors now accepts an explicit shape:

• 'default' applies the standard supabase-js CORS headers (still the default)
• 'disabled' disables CORS handling
• { headers } sets custom headers

The old boolean and bare Record<string, string> forms are still accepted but marked @deprecated in the JSDoc, following the same pattern as the existing allow to auth deprecation. They can be removed in a future major.

Changes:

• src/cors.ts: widen the internal CorsConfig union, add an exported isCorsDisabled() predicate, and teach buildCorsHeaders to read the { headers } shape (distinguished from a bare record via an 'headers' in config check).
• src/with-supabase.ts: replace the three inline cors !== false checks with isCorsDisabled(config.cors).
• src/types.ts: update the public cors field to the new union with deprecation tags, set @defaultValue to 'default', and refresh the JSDoc and inline example.
• Tests: extend cors.test.ts and with-supabase.test.ts with coverage for 'default', 'disabled', and { headers }, plus a dedicated isCorsDisabled suite. Existing deprecated-form tests are kept.
• Docs: update README.md and docs/getting-started.md to lead with the new shape and note the deprecated forms.

Additional context

CORS is only handled by the root @supabase/server export. All four adapters (Hono, H3, Elysia, NestJS) already do Omit<WithSupabaseConfig, 'cors'> and delegate CORS to their framework, so the widened union flows through unchanged and no adapter edits were needed.

Verification: npm run typecheck, npm run lint, and npm test (196 tests) all pass. Backward compatibility confirmed: cors: false and bare-record configs still compile (with a deprecation hint) and behave as before.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@supabase/server@102

commit: eb50f34