skills/supabase__server
1
0
Fork 0
mirror of https://github.com/supabase/server.git synced 2026-09-14 15:28:52 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
docs/auth-mode-ordering
supabase__server/CONTRIBUTING.md
T
Tomás Pozo 18818e0b5d Pre-v1 API cleanup: rename allow/authType/claims, narrow authKeyName, refresh adapter docs (#48) 
* feat: rename `allow` config option to `auth`

Aligns the SDK with Supabase CLI terminology — `auth: 'user'` reads
more naturally than `allow: 'user'`. The legacy `allow` key still
works (with a one-time `console.warn` per process) and will be
removed in a future major release; when both `auth` and `allow` are
provided, `auth` wins. Also exports new `AuthMode` / `AuthModeWithKey`
types alongside deprecated `Allow` / `AllowWithKey` aliases.

* feat!: rename auth mode values `'always'` → `'none'` and `'public'` → `'publishable'`

Aligns auth-mode values with Supabase CLI terminology. `'none'` reads more
directly than `'always'` for "no authentication required", and
`'publishable'` matches the `SUPABASE_PUBLISHABLE_KEY(S)` env var names.
`'secret'` and `'user'` are unchanged.

BREAKING CHANGE: the `'always'` and `'public'` mode values no longer work.
Replace `auth: 'always'` with `auth: 'none'`, `auth: 'public'` with
`auth: 'publishable'`, and `auth: 'public:<name>'` with
`auth: 'publishable:<name>'`. Runtime checks like
`ctx.authType === 'public'` must be updated to
`ctx.authType === 'publishable'`.

* feat!: rename `authType` field to `authMode` on `AuthResult` and `SupabaseContext`

Lines the field name up with its type — `authMode: AuthMode`. Reads more
naturally for both humans and AI agents working with the API.

BREAKING CHANGE: the `authType` field was renamed to `authMode` on
`AuthResult` (returned by `verifyAuth` / `verifyCredentials`) and on
`SupabaseContext` (passed to handlers). Find-and-replace
`ctx.authType` → `ctx.authMode` and `auth.authType` → `auth.authMode`
across your codebase.

* feat!: rename `claims` field to `jwtClaims` on `AuthResult` and `SupabaseContext`

Pairs naturally with `userClaims` and makes the snake_case JWT payload
distinct from the normalized identity view at a glance.

* refactor!: narrow `SupabaseContext.authKeyName` to `string | undefined`

The field used to be `string | null | undefined` (optional + explicitly
nullable), forcing consumers to handle two absence values. Collapse to a
single representation by dropping `null`: the property is simply omitted
for `'user'` and `'none'` modes, which don't match a named key.

`AuthResult.keyName` keeps its `string | null` shape — it's the
low-level type where the field is always present and `null` actively
signals "no named key for this mode."

* docs: add publishable-key example to README quick start

The auth-modes table documented the publishable mode but the quick start
only showed user, none, secret, dual, and server-to-server examples,
leaving readers without a concrete shape for publishable. Slot it
between the "no auth" and "secret" examples so the progression reads
no key → publishable (anon, key-gated) → secret (admin, key-gated).

The example clarifies the resulting client behavior — `supabase` is
anonymous, RLS still applies, and the publishable key is a client gate
rather than a user identity — which is the most common point of
confusion vs. `auth: 'secret'`.

* docs: update skill description

* docs: update ssr references accross docs and skill

* docs(adapters): add ecosystem index + community contribution guide

Adds src/adapters/README.md (index, maintenance model, contribution
checklist) and docs/adapters/h3.md. Moves docs/hono-adapter.md into
docs/adapters/. Slims the top-level README Framework Adapters section
to a canonical adapter table + brief examples. Updates CONTRIBUTING.md,
docs/getting-started.md, and the supabase-server skill to reference the
new paths.

* docs: sweep adapter and SSR docs to use renamed API

The cherry-picked docs commits were authored before the API renames in
this branch, so the new content arrived using `allow:`, `'always'`,
`'public'`, `claims`, `authType`, and `AllowWithKey`. Update the
newly-arrived files in line with the renamed API:

- docs/adapters/h3.md — `allow:` → `auth:`, `claims, authType` →
  `jwtClaims, authMode` throughout
- docs/ssr-frameworks.md — composed Next.js adapter example now uses
  `auth:` / `AuthModeWithKey` / `jwtClaims` / `authMode`
- src/adapters/README.md — adapter-test checklist mentions the four
  current modes (`'user'`, `'publishable'`, `'secret'`, `'none'`)
- CONTRIBUTING.md — same wording fix in the adapter-PR section
- skills/supabase-server/SKILL.md — top-level skill description points
  at `auth:` and the new mode values; legacy patterns folded into the
  existing migration trigger
- src/adapters/hono/middleware.ts — inline comment example uses `auth:`
  in both halves rather than mixing legacy and current option names
- README.md — collapsed Hono and H3 quick-start snippets use `auth:`

Migration prose (`README.md` callout, `docs/auth-modes.md` callout,
`docs/api-reference.md` deprecated-aliases section, `SKILL.md`
migration callouts) intentionally still references the old names; they
document the migration itself.

* docs: reframe Beta disclaimer for v1 launch + extract MIGRATION.md

The Beta callout ("APIs and documentation may change") directly
contradicts the SemVer commitment that v1 makes. For launch material
that pins to v1, the contradiction undermines the stability message
the version number is meant to carry.

Replace it with a v1.0 callout that leads with stability under SemVer
and follows with honest "active development continues" framing — new
adapters and ergonomic improvements in minor releases, breaking
changes only ever in a major bump.

Move the v0 → v1 rename map out of the README and into a dedicated
MIGRATION.md. The README quick start was buried under 20+ lines of
migration tables that only matter to upgraders, not first-time
readers — exactly the wrong tradeoff at launch. New short callout
points upgraders at MIGRATION.md.

SKILL.md gets the same Beta → v1.0 swap. The agent-operational
migration rules (lines 12-14: "always emit `auth:` in new code", "the
new mode values are `'none'` / `'publishable'`") are kept inline —
they're rules the agent applies every time it writes code, not
user-facing migration steps, so they don't belong in MIGRATION.md.

* docs: reframe v1.0 callout as "Public Beta" to match Supabase house style

The previous "Stable under SemVer; active development continues" framing
mixed two distinct axes — code stability (SemVer) and product
lifecycle stage (Public Beta / GA) — into the SemVer line. Several
Supabase docs run those independently: a release can be v1+ in SemVer
terms and still labeled Public Beta in lifecycle terms.

Lead with both signals in the headline: "v1.0 — Public Beta." Keep the
SemVer commitment ("breaking changes only ship as a major bump") so
launch copy can pin to v1, and pair it with the Public Beta lifecycle
stage so readers know the product line is still early. Same swap in
the SKILL.md mirror.
2026-05-06 12:16:14 +03:00

5.1 KiB
Raw Permalink Blame History

Contributing to @supabase/server

Thank you for your interest in contributing to @supabase/server! This document provides guidelines and instructions for contributing to the project.

Table of Contents

Getting Started

TBD

Development Setup

Prerequisites

  • Node.js: 20.x or higher
  • pnpm

Installation

  1. Fork and clone the repository:
git clone https://github.com/YOUR_USERNAME/server.git
cd server
  1. Install dependencies:
pnpm install
  1. Build the project to verify setup:
pnpm build

Development Workflow

Building

Build the library for distribution:

pnpm build

Watch mode for development (rebuilds on file changes):

pnpm run dev

Formatting

Format all code using Prettier:

pnpm format

Submitting Changes

Commit Messages

We use Conventional Commits for automated releases. Format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

  • feat: New feature (triggers minor version bump)
  • fix: Bug fix (triggers patch version bump)
  • docs: Documentation changes only
  • test: Adding or updating tests
  • chore: Maintenance tasks, dependency updates
  • refactor: Code changes that neither fix bugs nor add features
  • perf: Performance improvements
  • ci: CI/CD configuration changes

Breaking changes:

  • Use feat!: or fix!: for breaking changes (triggers major version bump)
  • Or include BREAKING CHANGE: in the commit footer

Examples:

feat: add support for view operations
fix: handle empty namespace list correctly
docs: update README with new examples
test: add integration tests for table updates
feat!: change auth config structure

BREAKING CHANGE: auth configuration now uses a discriminated union

Pull Request Process

  1. Create a branch from main:

    git checkout -b feat/my-feature

  2. Make your changes following the guidelines above

  3. Commit using conventional commit format:

    git commit -m "feat: add support for XYZ"

  4. Push to your fork:

    git push origin feat/my-feature

  5. Open a Pull Request with:

    • Clear title following conventional commit format
    • Description of what changed and why
    • Reference any related issues (e.g., "Fixes #123")
    • Screenshots/examples if adding user-facing features

  6. Respond to feedback - maintainers may request changes

PR Guidelines

  • Keep PRs focused - one feature or fix per PR
  • Update documentation if you change public APIs
  • Add tests for new functionality
  • Ensure all CI checks pass
  • Rebase on main if needed to resolve conflicts
  • Be responsive to review feedback

Contributing a framework adapter

Framework adapters (Hono, H3, …) are community-maintained and live in this repo under src/adapters/. They have additional requirements on top of the general PR guidelines above — tests covering every auth mode, no new runtime deps beyond a peer-dep, matching the existing adapter shape, and updating both adapter tables (in README.md and src/adapters/README.md).

See src/adapters/README.md for the full checklist before opening an adapter PR.

Release Process

This project uses release-please for automated releases. You don't need to manually manage versions or changelogs.

How It Works

  1. You commit using conventional commit format (see above)

  2. release-please creates/updates a release PR automatically when changes are pushed to main

    • Updates version in package.json
    • Updates CHANGELOG.md
    • Generates release notes

  3. Maintainer merges the release PR when ready to release

    • Creates a GitHub release and git tag
    • Automatically publishes to npm with provenance

Version Bumps

Versions follow Semantic Versioning:

  • Major (1.0.0 → 2.0.0): Breaking changes (feat!:, fix!:, or BREAKING CHANGE:)
  • Minor (1.0.0 → 1.1.0): New features (feat:)
  • Patch (1.0.0 → 1.0.1): Bug fixes (fix:)

Commits with types like docs:, test:, chore: don't trigger releases on their own.

For Maintainers Only

Publishing is fully automated via GitHub Actions:

  1. Merge the release-please PR when ready
  2. GitHub Actions will automatically publish to npm with provenance
  3. No manual npm publish needed

Questions?

  • Open an issue for bugs or feature requests
  • Check existing issues and PRs before creating new ones
  • Tag your issues appropriately (bug, enhancement, documentation, etc.)

License

By contributing to @supabase/server, you agree that your contributions will be licensed under the MIT License.

Reference in New Issue View Git Blame Copy Permalink