88 Commits

This Branch

This Branch

All Branches

Author	SHA1	Message	Date
Miranda Limonczenko	9a60894bfa	docs(functions): edit the secrets guide against the new style guide (#50763) ... Production secrets sat after two non-procedure sections, so the reader setting up a key crossed reference material to get from the local steps to the production ones. Move it up to follow Local secrets, which runs all four procedure sections unbroken before the reference sections. Group "Where local values come from" and "Default secrets" under a Reference heading. Both answer "what are its parts?", so both are Structure under the style guide's information types, and Reference is the group the worked outline ends with. They demote from H2 to H3, which keeps them in the page TOC, since it is built from h2 and h3. No heading is renamed, so the anchors Studio deep-links into (#default-secrets, #using-the-cli) and the one the secrets-limit troubleshooting page uses (#accessing-environment-variables) are intact. Changing a heading's level preserves its slug. Glue the new shape needs: an outline of the three section groups at the top, a transition out of the troubleshooting section, and an opening line under Reference.	2026-09-30 14:36:29 -07:00
Miranda Limonczenko	e29f4e0736	docs(database): style pass on the database functions guide (#50820) ... Inline rewording only. Nothing moves and no claim changes. Addresses reader-facing "we", UI labels in quotes rather than bold, "allows you to", "e.g.", future tense, and title-case common nouns in body prose.	2026-09-30 14:36:17 -07:00
Miranda Limonczenko	19188ece58	docs(functions): style pass on the Edge Function auth guide (#50884) ... Apply the docs style guide to Securing Edge Functions. Inline changes only. - Open the page with a value statement - Split the sentences that ran past the 26-word aim, and keep one relationship per sentence - Replace dash-bounded asides with separate sentences - Lift `(the default)` out of parentheses so it reads as a claim - Name the section instead of "above" and "the sections below" - Introduce the mode table in the sentence before it - Raise the `auth: 'none'` admonition to `danger`, and state it in the positive form - Stop restating that admonition in the Public functions section - Spell out Row Level Security, and name `@supabase/server` rather than "the SDK" - Use Supabase Dashboard and Supabase Platform consistently - Use "function" rather than "endpoint", and spell out "db" - Link `@supabase/server` once, and name it as a GitHub destination - Rewrite the Secret keys alt text to describe both rows, the column headers, and the masked key format	2026-09-30 14:36:05 -07:00
Miranda Limonczenko	36371de151	docs: trim CONTRIBUTING to repo mechanics and point at the style guide (#50743) ... Part 3 of 3. Stack: #50742 → #50744 → #50743. Review #50742 and #50744 first. Closes DOCS-1177 ## Problem `CONTRIBUTING.md` mixed how to write a page with how the repo is laid out. That's why it reached 568 lines, and why a contributor looking for either half reads past the other. #50742 gives the writing half its own home. ## Solution Trim `CONTRIBUTING.md` to repo mechanics, 568 lines down to 163. **Removed**, now in the style guide: general principles, information types, document types, components and elements, styling and grammar, word usage. **Kept**: the skills table, repo organization, guide and reference structure, content reuse, search. Content listings keeps its data file, ID rules, and test command here; the when-to-use-one part is in the style guide. **Added**: a table linking each style guide file. Wire the contributor-facing entry points at the guide: - `apps/docs/AGENTS.md` — gains a style guide section listing each file separately, so an agent can load one file without the others. This auto-loads for anything under `apps/docs`, making it the highest-leverage pointer in the repo. - Root `AGENTS.md` — claimed the skills are "the source of truth for conventions." For docs content style that's now the guide, with the skills as the process that applies it. - `.github/pull_request_template.md`, `.coderabbit.yaml`, `apps/docs/README.md`, `apps/docs/DEVELOPERS.md` — updated paths. Drop the `.prettierignore` exemption for `apps/docs/CONTRIBUTING.md`. It's short enough to format now, and a repo that publishes a style guide shouldn't exempt its own contributing doc. ## Notes for review Discoverability in a markdown-only guide is entirely these pointers, so they're the load-bearing part of this PR rather than cleanup. Both surviving anchor links into `CONTRIBUTING.md` target `#ai-agent-skills-for-docs-authoring`, which is kept. No dangling anchors. This PR sits last in the stack on purpose. It deletes the style sections that seven skill instructions referenced, so it has to land after #50744 rewires them. ## Manual testing 1. Open `apps/docs/CONTRIBUTING.md` and confirm every remaining section is repo mechanics, and the style guide table links resolve. 2. Confirm `apps/docs/AGENTS.md` names each style guide file, in size order: `WORD_LIST`, `01-voice-and-tone`, `02-elements`, `03-page-structure`. 3. Run `grep -rn "apps/docs/WORD_LIST" --include="*.md" --include="*.yaml" . | grep -v node_modules` and confirm only the intentional stub matches. 4. Run `npx prettier --config prettier.config.mjs --check apps/docs/CONTRIBUTING.md`. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated contributor guidance to distinguish writing conventions from repository mechanics, with the style guide as the reference for documentation style. * Added style guide links and clarified when to use the writing and editing skills. * Revised the docs contribution guide with a style guide file list and steps for adding content listings. * Updated the pull request checklist to direct contributors to the documentation skills for style guidance. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-25 20:22:47 -07:00
Miranda LimonczenkoandNik Richers	f5fcecf3d7	docs: point the authoring skills at the style guide (#50744) ... Part 2 of 3. Stack: #50742 → #50744 → #50743. Review #50742 first. ## Problem Six skills restated style rules inline, so a rule could be corrected in the guide and stay wrong in a skill. `edit-the-docs` alone carried a second copy of the procedure format, the information-type classification rules, and the tables outline example. Two reference files said in their own text that they should be retired once a style guide existed. ## Solution Replace the restatements with pointers to the file that owns each rule. **Retired, as each file asked:** - `style-fallback.md` is deleted. It ended by telling an agent to follow the nearest comparable page, which launders whatever that page happens to do into a rule. The guide's References section replaces it. - `common-pitfalls.md` becomes a pointer, per the note at its own line 94. **Rewired**: `write-the-docs`, `edit-the-docs`, `review-the-docs`, `pm-the-docs`'s checklist, and `drafting-mechanics.md`. Skills cite a specific file rather than the directory, so one file can be loaded instead of the whole guide. `review-the-docs` gains a docs-tooling check for the inverse case: a style rule added to a skill belongs in the guide, with the skill pointing at it. ## Notes for review **`edit-the-docs`' PR 1 / PR 2 boundary is unchanged on purpose.** That split is by kind of diff — PR 1 is inline changes only, nothing moves a line — which is what makes each PR reviewable. The guide's files split by the size of the thing they govern, and the two cut across each other: choosing an admonition is an element decision but an inline diff, and chunking is a page-structure decision but currently applied in PR 1. Forcing them to match would stop PR 1 being a pure inline pass. Dropping the dash-aside rule from `write-the-docs` here lost it entirely, since it had no home in the guide. #50742 restores it in `01-voice-and-tone.md`. I audited the other four rules this PR removes from that checklist; only that one was lost. The skill's document-type list keeps `troubleshooting`, which CodeRabbit flagged as a fifth type not in the guide. The repo has 219 troubleshooting pages and a content-type gate that treats them as authorable, so the gap was in the guide. #50742 now lists five document types. ## Manual testing 1. Run `grep -rn "style-fallback\|apps/docs/WORD_LIST" .agents/skills/` and confirm no matches. 2. Open each rewired skill and confirm every style guide link resolves, including anchors such as `03-page-structure.md#chunking`. 3. Invoke `/edit-the-docs` and confirm it reads the guide rather than restating rules. 4. Run `npx prettier --config prettier.config.mjs --check ".agents/skills/*-the-docs/**/*.md"`. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated documentation writing, editing, and review guidance to reference the dedicated style guide for voice, terminology, page structure, and content elements. * Clarified how to classify and organize sections, and expanded style-consistency checks. * Updated related checklists and references to distinguish style guidance from repository contribution instructions. * Consolidated common drafting advice into the style guide and updated the page-type table layout. <!-- end of auto-generated comment: release notes by coderabbit.ai --> ## Stack order This PR moved above the `CONTRIBUTING.md` trim after review. The trim deletes the style sections that seven skill instructions still referenced, so trimming first left those references dangling until this PR landed. Rewiring the skills first removes that intermediate state: the skills point at the guide while `CONTRIBUTING.md` is still whole, and the trim then breaks nothing. --------- Co-authored-by: Nik Richers <nik@validmind.ai>	2026-09-25 20:11:58 -07:00
Miranda LimonczenkoandNik Richers	8fa75be01b	docs: add a standalone style guide (#50742) ... Part 1 of 3. Stack: #50742 → #50744 → #50743. ## Problem We have several problems: - Style guidance lives in lots of places and need consolidation - Our CONTRIBUTING guide has turned into one massive style document that needs to be broken up ## Solution Add `apps/docs/style-guide/` as plain markdown. | File | Covers | | --- | --- | | `README.md` | What the guide covers, who it's for, how to contribute, and the references it defers to | | `WORD_LIST.md` | Terminology, spelling, capitalization, and the `agent` / `LLM` / `AI` distinction. Moved from `apps/docs/` with history intact | | `01-voice-and-tone.md` | Audience, brevity, sentence construction | | `02-elements.md` | Which component renders each piece, and linking conventions | | `03-page-structure.md` | Document types, information types, grouping, chunking, timeless documentation | ### New content This guide is mostly rearrangement and glue, but it includes some new content: - Links and cross-reference formatting - WORD_LIST entries for LLM and AI agent - Timeless documentation guidance - Accessibility guidance - Sharper guidance on brevity and chunking ## Manual testing 1. Open `apps/docs/style-guide/` on this branch and confirm `README.md` renders below the file list. 2. Follow every link in `README.md` and read the document through. 3. You can test by locally pointing an agent at the style-guide and seeing that it makes great choices when revising a document. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a documentation style guide covering voice and tone, page structure, and guidance for writing procedures, code, tables, diagrams, media, and links. * Added a word list with preferred spelling, capitalization, and usage, including guidance on inclusive and concise language. * Added recommendations for reviewing documentation drafts and runnable examples. * Replaced the existing word list page’s content with a link to its new location in the style guide. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Nik Richers <nik@validmind.ai>	2026-09-25 20:04:52 -07:00
Miranda Limonczenko	7ce4ee53ae	chore(docs) Retire supa-mdx-lint (#50602) ... Closes [DOCS-1289](https://linear.app/supabase/issue/DOCS-1289/get-the-linter-to-fix-what-it-flags-or-retirereplace-the-linter) Stacked on #50600, which points contributors at the authoring skills. Merge that one first. ## Problem Contributors experienced friction with the linter. They felt nickle and dimed for tiny nits and felt detracted from the work itself. PRs would become noisy with tiny one-word suggestions. Additionally, our homegrown linter is not very intelligent, causing frequent overrides. ## Solution This removes the linter entirely in favor of directing contributors to use SKILLS instead. The removal entails... - **CI.** Delete the three `docs_lint` workflows: the PR check, the external-PR comment companion, and the nightly `--fix` bot. Drop the stale `zizmor.yml` ignore entry for the deleted workflow. - **Tooling.** Delete `supa-mdx-lint.config.toml` and the 14 rule files. Drop the `lint:mdx` script and the `@supabase/supa-mdx-lint` dependency from docs, learn, and ui-library, and regenerate the lockfile. - **Content.** Remove the 181 directives. A separate commit carries Prettier's reformatting of the tables and blank lines those comments had suppressed, so the deletion commit stays readable. No prose changes. - **Style guide.** The word list states each rule directly instead of describing what the linter flagged. Every term survives, including the phrase groups that mirrored `Rule004ExcludeWords`. - **Skills.** `write-the-docs`, `edit-the-docs`, and `review-the-docs` drop `pnpm lint:mdx` from their self-review commands and check the word list directly. `ask-the-docs`'s CI reference drops both workflows. ## Manual testing 1. Run `git grep -i supa-mdx-lint -- . ':!pnpm-lock.yaml'`. No matches. 2. Run `pnpm install --frozen-lockfile --lockfile-only`. It passes, so the lockfile matches the three trimmed manifests. 3. Run `git diff master...HEAD --name-only --diff-filter=ACMR | grep -E '\.(md|mdx)$' | xargs npx prettier --config prettier.config.mjs --check`. All changed markdown passes. 4. Open the [reformatted filter table](https://docs-git-docs-retire-mdx-linter-supabase.vercel.app/docs/guides/observability/logs#filter-events) on the preview and compare it with [production](https://supabase.com/docs/guides/observability/logs#filter-events). The table renders the same. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Documentation guidance now uses manual prose and terminology review with the shared word list. * Clarified storage configuration and common Realtime channel mistakes. * Improved table formatting, text wrapping, and selected reference links. * Updated documentation authoring and review guidance. * **Chores** * Retired automated MDX linting from workflows and local validation commands. * Removed lint-suppression markers throughout documentation without changing instructions. * Added targeted documentation review guidance for pull requests. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-22 10:00:41 -07:00
Miranda Limonczenko	1608b16687	chore(docs) Direct contributors to the docs authoring skills (#50600) ... Prerequisite for [DOCS-1289](https://linear.app/supabase/issue/DOCS-1289/get-the-linter-to-fix-what-it-flags-or-retirereplace-the-linter). ## Problem The `write-the-docs` and `edit-the-docs` skills carry the docs style guide, so a contributor who uses them writes to the guide without having read it. Right now nothing points a contributor at them. `apps/docs/CONTRIBUTING.md` describes the skills as an option for agent users, halfway down a 559-line page, and no other contributor-facing file mentions them at all. ## Solution - **CodeRabbit reminder.** One path instruction for `apps/docs/content/**/*.mdx`. When a page collects two or more style, terminology, or structure issues, CodeRabbit adds a single comment pointing the author at `/write-the-docs` or `/edit-the-docs`. A single nit gets no pointer, so the comment reads as a signal rather than boilerplate. - **Docs CONTRIBUTING.** The intro lists the skills by task, draft through self-review, before the style rules, and links the existing skills section for framing and architecture. The section opener now reads as an expectation rather than a conditional, with the agent mechanics moved to a second paragraph. - **Root CONTRIBUTING.** A pre-flight check under Pull Requests, with the same task list nested under it. Matches the docs checklist item in #50591. - **Word list.** Names the skills that apply the list. - **Docs README and DEVELOPERS.** One sentence in each Contributing section. **Not in this PR:** CodeRabbit reminds, it doesn't enforce. Feeding the two `SKILL.md` files to `knowledge_base.code_guidelines` would make it review docs content against the style guide. That's a decision for DOCS-1289 itself. **Verification caveat:** this PR changes no MDX under `apps/docs/content/`, so the new path instruction doesn't fire on its own review. ## Manual testing 1. See all new content references in the diff. 2. Review for clarity and value. 3. Consider suggesting other ways to promote the usage of this skill to all docs contributors.	2026-09-21 10:07:21 -07:00
Miranda Limonczenko	84e46779af	chore(github) Revise pull request template, include docs skills (#50591) ... Related to DOCS-1289 <img width="2150" height="1540" alt="CleanShot 2026-09-18 at 10 56 14 AM@2x" src="https://github.com/user-attachments/assets/2a5d69e0-9037-4263-88c7-a624a167e775" /> ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Github chore ## What is the current behavior? The template has not been revised in two years. It is serviceable but simple. With some minor improvements, we can save time in the review process and nudge contributors toward better PR descriptions. ## What is the new behavior? This PR changes the pull request template: - Adds `write-the-docs` and `edit-the-docs` skill, which was the main ask for the Linear issue to socialize our skills so that we can retire the linter - Add "Problem" and "Solution" rather than "What is the current behavior" and "What is the new behavior...". They mean approximately the same thing but I think it's easier to understand and reason about. - Makes "Additional context" an optional field by commenting it out and stating "Optional". I find Additional context an annoying dumping ground for AI slop. - Adds a new section for writing manual instructions. Very valuable to speed up the review process. - Add an optional section for crafting a preview link table. ## Manual testing 1. Open the new template in a markdown visualizer 2. View content. See it is formatted well, links work, and content makes sense. 3. Uncomment the optional sections. See table is formatted correctly with the correct link formula. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Documentation - Reworked the pull request template into a structured format covering the problem, solution, review instructions, and checklist. - Added optional sections for preview links and additional context. - Updated preview-link guidance with clearer instructions and example URLs. - Replaced question-based prompts and manual contribution-guideline confirmation with a clearer, checkbox-based review workflow. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-21 09:42:23 -07:00
Miranda Limonczenko	36749659e6	docs(functions): answer the recurring secrets questions from reader feedback (#50422) ... Five reports on this page, four of them the same confusion: which .env file does what. Where local values come from is a new section listing the files that feed a local environment: supabase/functions/.env, a file you name yourself, the root .env that config.toml reads through env(), and [edge_runtime.secrets]. It says a value in one is not a value in the other. That is what CLI-818 asked for in as many words, the duplication FDBKIN-11884 complains about, and the config route FDBKIN-12716 raises. It sits with the other reference section rather than inside the local procedure, because it answers what the parts are rather than how to do something. Accessing environment variables splits into an Edge Function and a Deno script you run yourself, where neither env file applies. Deno.env.get needs --allow-env, so both commands pass it; without the flag the script prompts, and fails outright when nothing is there to answer. FDBKIN-7937. Production secrets now states who can set one, and the reserved prefix. Also calls Deno.env.get a method rather than a handler, which is what it is. The wording came in with the style pass at the bottom of the stack; fixing it here avoids restacking four branches for one word. Two claims from the source reports are deliberately not here. FDBKIN-34962 reports that adding a secret requires OWNER. The access control matrix in guides/platform/access-control.mdx says Owner or Administrator can create and delete, and Developer can view. The reporter found their version by external searching, so the page states what our own matrix says. supabase/agent-skills#452 reports that a secret value cannot be recovered after saving. SecretResponse_Output in the Management API spec returns value as a required field, and the Dashboard renders it, so that does not hold up from what I can check here. Left out rather than guessed at; the issue stays open. The reserved prefix is not a third-party host restriction as supabase/agent-skills#553 frames it. CreateSecretBody carries pattern ^(?!SUPABASE_).*, AddNewSecretForm.tsx:42 rejects the same, and the CLI filters SUPABASE_-prefixed names out of the local function environment. It is ours, and the page says so.	2026-09-18 16:09:15 -07:00
Miranda Limonczenko	06aafbae4b	docs(functions): give local secrets a procedure that produces a working key (#50420) ... The Managing secrets guide is the only place that tells you where a local secret has to sit for the Edge Function runtime to load it. Neither the supabase agent skill nor Supacademy covers it. The page named supabase/functions/.env once, in prose, and never had the reader create it. The eval in supabase/evals#285 reproduces what that produces: across three runs on codex-gpt-5.6-luna-no-skills, every run built a function reading its key from the environment, started the stack, and answered missing_api_key. Two of the three wrote supabase/functions/.env.example and stopped, which is a template with the variable name in it rather than the file the runtime reads. Local secrets is now a five-step procedure that creates the file with a working value, ignores it, creates the function that reads the key, starts the stack, and calls the function to confirm. That last step is the one that tells the reader whether it worked. The function is created before the stack starts, so a reader following the steps literally from a fresh project has something to call. The gitignore instruction moved out of its admonition and into step 2, carrying its consequence with it. It's an instruction the reader has to follow, so it belongs in the procedure rather than beside it. Recovery for a variable the function can't see gets its own section rather than trailing the procedure. "I set it and the function cannot read it" is the most repeated shape in the feedback on this page, and as loose sentences mid-section it had no entry in the table of contents.	2026-09-18 16:02:48 -07:00
Miranda Limonczenko	7012ba4a55	docs(functions): regroup the secrets guide by information type (#50419) ... Moves and heading levels only. No claims changed. Studio renders a Docs button at apps/studio/pages/project/[ref]/functions/secrets.tsx:43 pointing at #using-the-cli, but "Using the CLI" was bold text rather than a heading, so the anchor had no target and the button dropped the reader at the top of the page. It and "Using the Dashboard" are now real headings, which repairs it. Local secrets and Production secrets were h3 under "Accessing environment variables", but neither is about accessing one. Both are now h2 siblings, and the reference list moved to the end, so the page runs procedures first and facts last. Sections are ordered by what the reader is doing, not by subject: set a secret locally, read it in code, then set it in production. "Accessing environment variables" sat after production, which put the reading step after the shipping step. Local secrets held a two-item list of the loading mechanisms, which is a fact sitting inside a procedure. It is now the section's opening sentence, where a one-line fact can qualify the procedure without interrupting it. Every existing heading text is unchanged, so #default-secrets, #local-secrets, #production-secrets and #accessing-environment-variables all still resolve. Added a value statement opener, and an outcome after the production procedure. No intro outline: the page is short and its headings already scan. The frontmatter title was title case. Renaming it to sentence case moves a navigation label and a search entry, so the nav entry and the three pages that used the old title as link text change with it. The slug is untouched.	2026-09-18 15:55:32 -07:00
Miranda Limonczenko	82e9f6fb0e	docs(functions): tighten the voice in the secrets guide (#50418) ... Style only. No heading moves and no claim changes. The page carried the same caution admonition twice, word for word, and explained the local .env loading rules twice more: once as a list of the two mechanisms, then again as a pair of serve commands with the same prose around them. Both copies are gone, along with the trailing line about managing different environments that restated the --env-file bullet. The rest is voice. First person became second, future tense became present, and "allows you to" became a sentence with the reader as its subject. SB_REGION and SB_EXECUTION_ID had lost words. The two NEVER shouts became bold, per the emphasis rule. The alt text named the topic the heading already names. It now describes the Key and Value fields, the reveal and remove controls, and the Add another and Save buttons, which is what a reader who can't see the screenshot needs. Dropped the item count ahead of the local loading list, and made that list unordered, because the two mechanisms are alternatives rather than steps.	2026-09-18 13:45:30 -07:00
Miranda Limonczenko	e8547352c5	docs(auth): answer the four most repeated SSR auth questions (#50289) ... Closes DOCS-1313 Closes FDBKIN-4573 Closes FDBKIN-15214 Closes FDBKIN-10628 ## Problem Four asks come up repeatedly in feedback intake. The Eval is green and this feedback cannot be included in the Eval. Using the Evals work as an excuse to action on the feedback. 😄 Readers can't tell which auth call verifies a token and which only reads stored state. They don't know that the response the cookies were written to is the response they have to return, because that only ever existed as a code comment. Nobody is warned that refreshing in two places burns a single-use refresh token, which surfaces as users being signed out at random. And nothing in `apps/docs` says `proxy.ts` is Next.js 16 and later, so a reader on 15 writes a file the framework never calls. ## Solution - Add the fact that `getClaims()` refreshes a session close to expiring before it verifies. It was only in the typedoc remarks, and it is what makes the double refresh warning make sense. - Say that `setAll` rebuilds `supabaseResponse` on every write, so a response built earlier is stale, and show how to copy the cookies onto a different one. - Warn that a second refresh outside the reuse window revokes the session, linking refresh token reuse detection. - Note that `proxy.ts` is Next.js 16 and later, and that the file is `middleware.ts` before that. - Name the file in the proxy fence in `examples/prompts/nextjs-supabase-auth.md`, which gave agents the export name and no path. The auth methods partial is shared by five other pages, so that first change surfaces there too. ## Manual testing 1. Open the [SSR client guide](https://docs-git-docs-ssr-client-feedback-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client) on the deploy preview. The Next.js panel carries the version note, the refresh warning, and the response guidance. 2. Select the refresh token reuse detection link. It resolves to the sessions guide. 3. Open the [Next.js Auth prompt](https://docs-git-docs-ssr-client-feedback-supabase.vercel.app/docs/guides/ai-tools/ai-prompts/nextjs-supabase-auth). The proxy section names the file and says it is `proxy.ts` on Next.js 16 and later. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Documentation - Clarified that `getClaims` refreshes sessions when access tokens are near expiration, helping server-rendered sessions remain active. - Expanded Next.js SSR guidance for session-refresh setup, including file placement and version-specific naming. - Added warnings about refresh-token reuse and session revocation after repeated refreshes outside the reuse window. - Added guidance for preserving authentication cookies and cache-related headers when returning updated responses. - Clarified that refreshed tokens should be passed to Server Components to keep sessions active. - Clarified the required session-refresh handler export and example filename. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-16 12:48:23 -07:00
Miranda Limonczenko	a4106b01f5	docs(auth): correct what getClaims verifies, and fix the Express env setup (#50288) ... ## Problem These findings came from a technical audit and verification of the claims in the doc. I found two accuracy problems: - **The guide said `getClaims()` is safe to trust** because it "validates the JWT signature against the project's published public keys every time". That only describes projects on asymmetric signing keys. With a symmetric secret it calls the Auth server instead, which the page's own partial already said. The advanced guide then read as a flat contradiction: `getUser()` was "the only way" to know a session is valid. The real distinction is revocation, not verification. - **Running the Express sample verbatim doesn't work.** In the docs sandbox, it printed `SUPABASE_URL = undefined`, so `createServerClient` received undefined for both the URL and the key. The env var tab installed dotenv twice, once inline and once through the package manager tabs, and its "And initialize it" lead-in was followed by the second install rather than any initialization. The route sample then required dotenv without calling `config()`. ## Solution - Say what `getClaims()` verifies against in each signing key mode. - Reframe the advanced guide's `getUser()` answer around session revocation, so the two pages stop contradicting each other. - Switch the advanced guide's two middleware snippets from `getUser()` to `getClaims()`, matching the guide. - Rename its `Next.js middleware` heading and CloudFront bullet, which the proxy rename missed. - Load dotenv on the first line of the Express entry point, and drop the duplicate install. - Tag both Express fences `js`. They are CommonJS, not TypeScript. - Update the stale "middleware refreshing user sessions" comment in the rendered Next.js `server.ts` sample. ## Manual testing 1. Open the [SSR client guide](https://docs-git-docs-ssr-client-accuracy-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client) on the deploy preview, then the Express tab. dotenv is installed once, followed by `require('dotenv').config()`. 2. Open the [advanced guide](https://docs-git-docs-ssr-client-accuracy-supabase.vercel.app/docs/guides/auth/server-side/advanced-guide). The Next.js heading reads `Next.js proxy` and both snippets call `getClaims()`. Part of DOCS-1313. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Clarified the difference between token validation and detecting revoked server-side sessions. - Updated Next.js guidance and examples to use “proxy” terminology. - Refined CloudFront caching guidance for authenticated routes. - Improved Express setup instructions, including dotenv loading and JavaScript examples. - Expanded explanations of signing-key verification. - Updated Astro and Nuxt examples to forward cache headers correctly. - Updated session-refresh guidance in the Next.js example to reference the proxy. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-16 12:31:11 -07:00
Miranda Limonczenko	7bec687917	docs(auth): regroup the SSR client guide and cut repetition (#50287) ... ## Problem `_partials/auth_methods.mdx` was included six times in this one page. Radix unmounts inactive tab panels, so a browser reader sees it three times on the default Next.js view, and the generated markdown that agents read contained all six. That was about 25% of the 33.5 KB export, and it put the same `Summary of the methods` heading in the table of contents three times over. The page is also 900+ lines with no intro outline, the per-framework recaps were `h2` inside an `h2` section, and six of the nine panels had no step headings at all. ## Solution - Include the auth methods partial once, under a new `Choosing an auth method` section grouped with `Caching considerations`, and point to it from the procedure. This follows the mixed information types rule in `apps/docs/CONTRIBUTING.md`. - Add an intro outline linking the section groups and saying when to read the two reference sections. - Demote the eight in-tab `Congratulations` headings to `h3` so they nest under `Create a client`. - Add a `Create the Supabase clients` heading to Astro, Remix, Nuxt, React Router, Express, and Hono, and the recap Hono was missing. No claims changed here, only placement. ## Manual testing 1. Open the [SSR client guide](https://docs-git-docs-ssr-client-structure-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client) on the deploy preview. The table of contents lists `Summary of the methods` once. 2. Select each of the five links in the intro paragraph. Each one scrolls to its section. 3. Select each framework tab. Every panel has a step heading and a recap. Part of DOCS-1313. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added an introductory setup overview covering installation, environment variables, client creation, authentication methods, and caching. - Added dedicated guidance for choosing an authentication method. - Added Astro SSR and client sections, along with a complete Hono recap. - Reorganized framework headings for clearer navigation. - Consolidated authentication guidance by removing duplicate content from individual framework sections. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-16 12:12:06 -07:00
Miranda Limonczenko	91b7df64c2	fix(ui): report clipboard write failures instead of rejecting (#50292) ... Closes DOCS-1390 ## Problem Sentry [DOCS-AA](https://supabase.sentry.io/issues/7727380816/) reports `NotAllowedError: Failed to execute 'write' on 'Clipboard': Write permission denied.` as an unhandled promise rejection. The error names `write`, not `writeText`, which places it in the `ClipboardItem` branch of `copyToClipboard`. That branch has two problems: - The write runs inside a `setTimeout`, so the surrounding `try/catch` has already returned by the time it executes. A denied write routes to the promise's `reject`. - No caller attaches a `catch`. All call sites either fire-and-forget or `await` inside an async handler with no `try/catch`, so the rejection surfaces as an unhandled rejection. The user-visible effect is worse than the Sentry noise. On that branch the copy fails with no feedback at all, because the `toast.error` in the outer `catch` is unreachable from inside the `setTimeout`. The `writeText` branch does show the toast, so the two paths disagree. The issue is filed against auth docs, where it surfaced, but the fix belongs in `packages/ui`. The same branch runs in Studio and www. ## Solution - Handle the failure inside the `setTimeout`, where it happens: report it and resolve. - `copyToClipboard` no longer rejects on either path, matching what the `writeText` branch already did. No caller relied on rejection. - Add regression tests for a denied write on both branches. ## Manual testing 1. Run the unit tests. Four `copyToClipboard` cases pass, including the two new denial cases. ``` pnpm --filter studio exec vitest run lib/helpers.test.ts -t copyToClipboard ``` 2. Confirm the new test is a real guard. Revert `clipboard.ts` and rerun. The write case fails with `promise rejected ... instead of resolving`. 3. Confirm the ratchet is unchanged. ``` pnpm --filter studio run lint:ratchet ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Clipboard write failures now display an error notification instead of causing an unhandled rejection. * Copy operations resolve consistently when clipboard access is denied or unavailable, including Safari clipboard support. * Failed copy attempts no longer trigger completion callbacks, preventing misleading success behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-16 19:01:21 +00:00
Miranda Limonczenko	cf5bf65361	docs(auth): tighten the voice in the SSR client guide (#50286) ... ## Problem The SSR client guide, like all guides, have drifted from our style rules and writing best practices. This PR is to do an inline edit without re-arranging any sections. ## Solution - Open with what the guide does, then the SSR context. - Delete the `{/* TODO: Can this be consolidated? */}` comment. - Remove the three em dashes and the parenthetical asides in prose. - Rewrite the Next.js danger callout to lead with the consequence: anyone can forge the session cookie. - Give Astro, Remix, Nuxt, React Router, and Express the same bulleted recap Next.js, SvelteKit, and TanStack already had. ## Manual testing 1. Open the [SSR client guide](https://docs-git-docs-ssr-client-style-supabase.vercel.app/docs/guides/auth/server-side/creating-a-client) on the deploy preview. The first sentence says what the guide does. 2. Select each framework tab. Every panel ends with a bulleted recap. Part of DOCS-1313. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated server-side authentication guidance across supported frameworks. - Clarified cookie-based session storage, SSR package usage, and cache-header handling. - Added guidance on protecting against forged cookies and verifying sessions with `getClaims()`. - Expanded framework setup and authentication flow summaries for Astro, Remix, Nuxt, React Router, Express, and TanStack Start. - Clarified TanStack route protection, redirects, and server-side authorization requirements. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-16 11:41:47 -07:00
Miranda Limonczenko	3e6b40b238	chore(docs): revise CONTRIBUTING for common pitfalls with Information types (#50357) ... ## Problem Our CONTRIBUTING and WORD_LIST is doing a pretty good job at improving contributor documentation, but I consistently see some issues: - **Uses "This guide":** "This guide..." is no longer recommended based on discussions with Nik. Instead, recommendation is to omit those words while still including a value statement. I still do not recommend including a definition of the title term as an opening sentence. - **Mixed information types:** I still often see mixed information types or wordy, chunky paragraphs. Without a definition in place, my agent mistakenly thought there was just "Procedure, Context, and Reference." ## Solution - **A new Information types section** that clearly outlines definitions and usage with cross-references so that this guidance is not easily missed. - **Removed "This guide"** recommendation in favor of a value statement. Additionally added a clear rule about how to spell numbers consistently and gave more guidance about how to structure a large topic. ## Manual testing 1. Open [apps/docs/CONTRIBUTING.md](https://github.com/supabase/supabase/blob/docs/value-statements-and-counts/apps/docs/CONTRIBUTING.md) on this branch. The Information types section renders its table, the Recommendations list, and both fenced examples. 2. Click the two `Information types` links, one in General principles and one under Guides. Both jump to the section. 3. Open [apps/docs/WORD_LIST.md](https://github.com/supabase/supabase/blob/docs/value-statements-and-counts/apps/docs/WORD_LIST.md). The `numbers` entry sits under N, ahead of `numbers in product versions`. 4. Run `npx prettier --check apps/docs/CONTRIBUTING.md apps/docs/WORD_LIST.md` from the repo root. It reports no formatting changes. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Expanded the contribution guide with Information Mapping guidance for procedures, processes, principles, concepts, structures, and facts. - Clarified paragraph and section grouping, page-level classification, recommended ordering, navigation, transitions, outcomes, and connective prose. - Added guidance to use value-focused introductions and bold “Recommended” and “Not recommended” labels. - Added number-formatting guidance, including numeral usage, ranges, fractions, and when to omit step or item counts. - Updated related entries in the documentation word list. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-16 11:40:19 -07:00
Miranda Limonczenko	4d57edd622	docs(database): add data type guidance to the tables guide (#50025) ... Refs FDBKIN-4668 Part 5 of a 5-PR stack on `apps/docs/content/guides/database/tables.mdx`. Builds on #50024. ## Problem Reader feedback in FDBKIN-4668 reports developers mixing `timestamptz` and `timestamp` across production schemas for lack of guidance. This PR adds the guidance half of that ask. The issue also asks for linting in the schema designer, which is a Frontend change and stays open. The page listed 44 data types and recommended neither side of any pair a reader actually has to choose between: `timestamp` or `timestamptz`, `varchar` or `text`, `numeric` or `float`, `integer` or `bigint`. No example on the page had a timestamp column at all, and `timestamptz` appeared only inside the reference table. ## Solution Adds a short "Choosing a type" section to the Reference group, stating a safe default for each pair and why. Also changes `salary bigint` to `salary numeric` in the private schema example. That line was checked against the wrong-outcome test in #50023 and deliberately left there, because a reader storing cents in a `bigint` gets a working table. It changes here because **this branch is what makes it wrong**: once the page recommends `numeric` for money, an example doing the opposite two screens away teaches the reader the opposite of what the page just said. ## Manual testing Preview: https://docs-git-docs-tables-datatypes-supabase.vercel.app/docs/guides/database/tables#choosing-a-type 1. Open the preview at that anchor. "Choosing a type" renders above the data type table. 2. Open `#data-types` on the same preview. It still lands on the reference table, which Studio deep-links to from three components. 3. In a local database, insert `1234.56` into `private.salaries.salary` and select `salary * 3`. Returns `3703.68` exactly. ## Verification (`test-the-docs`) Run in the Compose sandbox against a local stack. | Check | Result | | --- | --- | | `create table private.salaries` with `salary numeric` | pass | | `insert ... values (1234.56, ...)` then `select salary, salary * 3` | pass — returns `1234.56` and `3703.68`, exact | The same example failed to run at all before this stack, because `public.actors` didn't exist on the page's path. #50023 fixes that. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated the Postgres tables guide with practical guidance for choosing column types. - Added recommendations for timestamps, text, monetary and decimal values, and identifiers. - Updated the example salary column to use the `numeric` type instead of `bigint`. - Expanded the column type reference section to help readers select appropriate types for common data. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-14 19:50:23 -07:00
Miranda Limonczenko	ef3cfad9ed	docs(database): add access control to the tables guide (#50024) ... Closes DOCS-1314 Brings the Eval to green. Part 4 of a 5-PR stack on `apps/docs/content/guides/database/tables.mdx`. Builds on #50023. ## Problem The page taught table creation and never said to protect a table. Across the original 573 lines, "row level security" appeared once, and that mention was about `security_invoker` on views. There was no `enable row level security`, no policy, and no `auth.uid()` anywhere. The gap was uneven between the two paths the page offers. The Table Editor enables row level security by default and warns that a table without it is publicly writable and readable. The SQL path on the same page produced an unprotected table and said nothing about it. Two further gaps followed from that one: - **Every example was a single access class.** `movies`, `categories`, `actors`, `performances`, and `private.salaries` are all the same shape. The page had no pattern for what most applications actually look like: a shared table everyone reads sitting beside a per-person table only its owner reads. The shared one is the one that gets skipped. - **Nothing told the reader to check the result.** No verify, no confirm, and no expected output anywhere on the page. ## Solution Adds a "Securing your tables" section between creating a table and loading data: - Enabling row level security and writing a first policy, with the consequence stated: a table with row level security and no policy returns no rows to anyone. - A worked example with two access classes, `movies` and `watchlists`. - A verification step. Two queries against `pg_tables` and `pg_policies` confirm that every table exists, has row level security enabled, and has at least one policy. Policy examples follow the idioms in the Row Level Security guide, including the wrapped `(select auth.uid())` form. The guide is cross-referenced rather than restated. ## Verification (`test-the-docs`) All 22 SQL fences on the page were run in document order against a local stack, the way a reader pasting top to bottom would. | Snippet / step | Class | Result | Notes | | --- | --- | --- | --- | | `create table movies` (Creating tables) | runnable-local | pass | | | `create table movies` ×2 (Primary keys) | illustrative-only | skipped | Re-shows the same table to explain `identity`; not a continuation | | `alter table movies enable row level security` | runnable-local | pass | | | `create policy "Anyone can read movies"` | runnable-local | pass | | | `create table watchlists` + 2 policies | runnable-local | pass | | | Verification query, `pg_tables` | runnable-local | pass | Lists both tables with `rowsecurity` true | | Verification query, `pg_policies` | runnable-local | pass | Lists all three policies | | `insert into movies` (Basic data loading) | runnable-local | pass | | | `create table categories` + foreign key | runnable-local | pass | | | `create table actors` / `performances` | runnable-local | pass | Failed before this stack; see below | | `create schema private` | runnable-local | pass | | | `create table private.salaries` | runnable-local | pass | Failed before this stack; see below | | Views section, 9 fences | illustrative-only | skipped | Depend on `students`, `courses`, and `grades`, which the page shows as rendered tables and never creates | **Tier A path:** `movies` → enable RLS → policy → `watchlists` + policies → both verification queries → `insert into movies` → `categories` + FK → `actors`/`performances` → `private` schema → `private.salaries`. Runs clean end to end. **Tier B, RLS behavior.** Every access claim in "Securing your tables" was exercised with two real users: | Check | Expected | Observed | | --- | --- | --- | | User A inserts into their own watchlist | succeeds | succeeds, A sees 1 row | | User B reads A's rows | 0 rows | 0 rows | | `anon` reads `movies` | rows returned | 2 rows | | `anon` reads `watchlists` | 0 rows | 0 rows | | User B inserts a row owned by A | rejected | `new row violates row-level security policy for table "watchlists"` | **Environment:** Compose sandbox (`sandbox/run.sh up-stack`), DinD + `supabase start`, Postgres 17. Fences ran in-container only, never on the host. **Note on the sandbox.** `supabase start` inside the nested daemon hit repeated `toomanyrequests: Rate exceeded` from ECR Public. The CLI retries and the stack does come up, but expect a slow first run. ## What this PR leaves to the one above it Data type guidance is #50025. ## Manual testing Preview: https://docs-git-docs-tables-rls-supabase.vercel.app/docs/guides/database/tables#securing-your-tables 1. Open the preview at that anchor. The three subsections render, and the numbered steps show their embedded SQL blocks. 2. In a local project, run the `movies` and `watchlists` snippets, then the two verification queries. Both tables appear with `rowsecurity` true and at least one policy each. 3. As a signed-out client, select from `movies` and from `watchlists`. `movies` returns rows; `watchlists` returns none. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Expanded the database tables guide with instructions to secure tables before adding rows. - Added guidance on enabling row-level security and creating policies for shared and per-person tables. - Clarified that policies control row access, while revoked table grants can cause permission errors. - Documented owner-scoped access using authenticated user IDs and ways to verify table protection. - Explained that read-only policies reject inserts through the Data API and provided alternatives. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-14 18:49:11 -07:00
Miranda Limonczenko	31a0f450cf	docs(database): correct the Dashboard table creation steps (#50023) ... Part 3 of a 5-PR stack on `apps/docs/content/guides/database/tables.mdx`. Builds on #50022. ## Problem Three claims fail the test that a reader following the page would hit a wrong outcome. **The Dashboard steps don't match the product.** They said to click **New Table**, save, then click **New Column**. Columns are defined inside the table creation panel, so a reader who follows the steps saves a table with no columns and then hunts for a button that isn't part of that flow. The labels are also sentence case in the product: **New table** and **New column**. **The Dashboard example diverges from the rest of the page.** The steps created a table named `todos` with a `task` column, while the SQL tab beside them and every later example use `movies`. A reader who took the Dashboard path and then ran the first Loading data snippet got `relation "movies" does not exist`. **The page's SQL doesn't compose.** Running every fence in document order showed that the many-to-many example under "Joining tables with foreign keys" opened by creating `movies` again. A reader who already created it got `relation "movies" already exists`, the block stopped, so `actors` was never created, and the `private.salaries` example two sections later then failed with `relation "public.actors" does not exist`. **One redundant statement broke two sections.** **The bulk loading example couldn't work.** `COPY` accepts text, CSV, and binary input, and the page listed JSON. `\COPY movies FROM './movies.csv'` expects a value for every column, and `movies` has three while the sample file has two. The options example passed `CSV HEADER` against a file with no header row, which silently dropped the first record. Found by CodeRabbit. ## Solution Rewrites the five Dashboard steps to match the panel and to produce `movies`, so both tabs leave the reader in the same place. Drops the redundant `create table movies` from the many-to-many block; the prose above it already says "You have a list of `movies`". Names the columns in both `COPY` commands, corrects the format list, points the `HEADER` example at a file that has one, and removes the space before each quoted CSV field. Dashboard changes verified against `TableEditor.tsx`, which renders `ColumnManagement` inside the creation panel; `TableEditorMenu.tsx` and `ColumnList.tsx` for the labels; and `DEFAULT_COLUMNS` in `TableEditor.constants.ts` for the `id` and `created_at` columns the editor adds. ## Checked and deliberately left - `grant all on table transcripts to authenticated`. Broader than the example needs, but a reader gets the working result the page promises, so it doesn't meet the bar for this branch. - "By default, views are accessed with their creator's permission." Accurate. `security_invoker` is opt-in. - `salary bigint` in the private schema example. Left here; it changes in #50025, where the page starts recommending `numeric` for money and the example becomes inconsistent with it. ## Flagged, not changed - The `api-create-table-sm.mp4` video in the Dashboard tab may show the older flow. Its contents weren't verified. - **Nothing in the Views section is runnable.** All nine of its fences depend on `students`, `courses`, and `grades`, which the page shows as rendered tables and never creates. Supplying that DDL is new content, so it isn't this branch's job, but it's worth a ticket. ## Manual testing Preview: https://docs-git-docs-tables-technical-supabase.vercel.app/docs/guides/database/tables 1. Open the preview and read the Dashboard tab under "Creating tables". It says **New table**, creates `movies`, and defines both columns in the same panel. 2. Open the Table Editor in a project and click **New table**. The panel has a **Name** field and a **Columns** section, and there is no separate **New Column** step. 3. In a fresh local database, run the SQL fences from "Creating tables" through `private.salaries` in page order. Each one succeeds. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated the “Creating tables” guide to use a `movies` table with `name` and `description` columns. - Reworded and consolidated the table-creation steps, including the `created_at` column in the SQL example. - Updated bulk data loading instructions for CSV imports, connection setup, named columns, and header-delimited files; removed JSON from the listed formats. - Simplified the many-to-many example by removing the redundant `movies` table definition. - Clarified schema selection based on the current `search_path`. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-14 17:32:36 -07:00
Miranda Limonczenko	5979218c97	docs(database): split out views and group the tables guide by information type (#50022) ... Part 2 of a 5-PR stack on `apps/docs/content/guides/database/tables.mdx`. Builds on #50021. ## Problem Four structural problems, all covered by the Guides section of CONTRIBUTING. **Views was a second topic living inside a guide about tables.** Roughly 180 lines, its own subsections four levels deep, sharing nothing with the tables above it beyond the word "table". **The page didn't say what it was for.** It opened with three paragraphs and a sample table before a reader could tell whether the page matched their goal. CONTRIBUTING asks a guide to begin with a sentence declaring its intent. **The top level mixed information types.** It was a flat list of every task, so "Schemas" and "Primary keys" sat beside "Creating tables" and background interrupted the action path. **Reference material interrupted the procedure.** A 44-row data type table sat between "Creating tables" and "Loading data", so a reader following the action path walked through it. Plus a duplicate video: the Dashboard tab under "Joining tables with foreign keys" embedded the same YouTube ID that frontmatter already serves as the table of contents video. ## Solution Moves and regrouping. - **Views moves to its own page**, `guides/database/views`, with its headings promoted one level and the two view-related links from Resources moved with it. - The page opens with an intent sentence, then a section outline, then a "What is a table?" section holding the definition and the spreadsheet comparison. - The remaining sections split into three groups by information type, ordered procedures, context, reference: **Creating and managing tables** holds creating, loading, and joining; **How tables are organized** holds primary keys, relationships, and schemas; **Reference** holds the data type table. - "Joining tables with foreign keys" held both classes, so it splits. The steps keep the heading and stay in the procedures group. The concept, what relational means and the diagram showing it, becomes **Relationships between tables** in the context group. The two cross-reference each other. - The duplicate video goes, and with the Dashboard tab empty the surrounding `Tabs` wrapper goes too. ## Anchors **Every heading keeps its text, so every anchor keeps its slug.** Demoting a heading changes its level, not its anchor. That matters because the inbound links are mostly outside `apps/docs`: Studio deep-links to `#data-types` from three components and `#primary-keys` from two, and `apps/www` links to `#creating-tables` and `#joining-tables-with-foreign-keys`. `#views` is the one exception, since that content left the page. Its single inbound link, in `guides/ai/engineering-for-scale.mdx`, now points at the new page, and both `NavigationMenu.constants.ts` entries are updated: the existing item becomes "Managing tables and data" and a "Views" item sits beside it. ## One deletion that isn't a move The "Columns" heading and its one sentence, "You must define the data type when you create a column." The heading held only the two subsections that moved out, and the sentence repeats a line 50 lines above it. ## Deferred Reordering "View security" behind an access-control foundation. That move only reads correctly once the foundation exists, so it travels with that content in #50024. ## Manual testing Preview: https://docs-git-docs-tables-structure-supabase.vercel.app/docs/guides/database/tables 1. Open the preview. The page opens with its intent, then a four-entry outline, then "What is a table?". Each outline link resolves, and the three groups below read as procedures, then context, then reference. 2. Open `#data-types`, `#primary-keys`, `#creating-tables`, and `#joining-tables-with-foreign-keys` on the preview. All four still land on their sections. 3. Open https://docs-git-docs-tables-structure-supabase.vercel.app/docs/guides/database/views. The new page renders, and "Views" appears in the sidebar beside "Managing tables and data". 4. Run `pnpm build:guides-markdown` from `apps/docs`. It generates 782 files, one more than before. Discard the change to `public/markdown/manifest.json`, which the repo commits as `[]`. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added a dedicated guide covering Postgres views, including creation, querying, security options, and materialized views. - Reorganized the Tables and data guide with clearer sections, navigation links, table organization details, and reference information. - Updated the many-to-many example to display SQL directly. - Split database navigation into separate “Managing tables and data” and “Views” entries. - Added a PostgreSQL log configuration entry and a C# client reference link. - Updated documentation links to point to the new Views guide. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-14 16:43:05 -07:00
Miranda Limonczenko	e022145be9	docs(database): apply house style to the tables guide (#50021) ... Part 1 of a 5-PR stack on `apps/docs/content/guides/database/tables.mdx`, one change type per PR. ## Problem The page addressed the reader as "we" in about 18 places. CONTRIBUTING reserves `we` for the Supabase team and asks that the reader be `you`. None of it was caught by the linter, because `Rule004ExcludeWords/first_person` only bans singular first person. Alongside that: scare quotes on established terms, parenthetical asides that CONTRIBUTING disallows, future tense where present tense reads better, an ordered list that repeated `1.` four times, and three relative links where `/docs/...` paths belong. **The three diagrams had alt text that named a topic instead of describing the picture.** "Schemas and tables" tells a screen reader nothing about a diagram showing two schema boxes, one labeled `public` holding six tables and one labeled `api` holding three. ## Solution Inline rewrites and cuts. **Nothing in this PR moves a line from one place to another.** Each alt now describes its diagram: the column types in the table diagram, the arrow between matching columns in the foreign key diagram, and the two labeled schemas with their table counts. Two deletions worth calling out: - The `<br />` spacer after the data type table. - The four-item benefits list under "When to use views". The four headings immediately below restate it verbatim. Also fixes "Every column is a predefined type", which states the relationship backwards. A column has a type; it isn't one. ## One dead link, surfaced by the conversion The Loading data intro pointed at `guides/database/api`, which isn't a page. It exists only as a redirect in `apps/www/lib/redirects.js`, and that redirect doesn't serve the docs deployment, so the link 404s there. As a relative link it was invisible to the link checker; converting it to a `/docs/...` path is what made the Docs E2E suite catch it. It now points at `/docs/guides/api`, the live page that 13 other guides already link to. ## What this PR leaves to the ones above it Section moves and the Views page split are #50022. Corrections to claims are #50023. New content is #50024 and #50025. ## Manual testing Preview: https://docs-git-docs-tables-style-supabase.vercel.app/docs/guides/database/tables 1. Open the preview. The intro reads "Excel spreadsheets" and "relational databases", and the only remaining "we" is "We provide a SQL editor within the Dashboard", which refers to Supabase rather than the reader. 2. Inspect the three images on the preview. Each `alt` describes the diagram rather than naming its topic. 3. Follow the **Data API** link under "Loading data". It resolves instead of returning 404. 4. Run `npx prettier --check apps/docs/content/guides/database/tables.mdx` and `pnpm lint:mdx` from `apps/docs`. Both pass. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Clarified guidance on table creation, data types, primary keys, bulk loading, relationships, schemas, views, and materialized views. - Improved wording, capitalization, terminology, and internal navigation throughout the tables guide. - Updated diagram alt text with more descriptive captions. - Updated the loading data section to link to the Data API guide. - Revised the bulk-loading example with an explicit column list, CSV options, and a simplified database connection command. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-14 16:31:11 -07:00
Miranda Limonczenko	bc917370d1	docs: recommend a local CLI install on the front page (#50356) ... Closes DOCS-1391 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. ## What is the current behavior? The docs front page is the only place that still recommends a global CLI install. It shows `npm install -g supabase` in both the CLI tab and the AI prompt, and tells the agent to run `supabase init`. Everywhere else in the docs installs the CLI as a project dev dependency, so the version is pinned in `package.json` and everyone on a team runs the same one. ## What is the new behavior? - `installCli` becomes `npm install supabase --save-dev`, matching [Install and run the CLI](https://supabase.com/docs/guides/local-development/cli/getting-started). - `initialize` becomes `npx supabase init`. A dev-dependency install leaves no global `supabase` command. - The AI prompt says "as a project dev dependency" and states the reason, so an agent doesn't fall back to a global install. - Updates the same wording in the monitoring and debugging prompt, which shares the constants. - Updates the `AiPrompt` markdown schema test assertion. ## Manual testing 1. Open the [docs front page preview](https://docs-git-docs-cli-local-install-supabase.vercel.app/docs). The AI Prompt tab reads "Install the Supabase CLI as a project dev dependency with `npm install supabase --save-dev`, so the version is pinned per project" and ends with `npx supabase init`. 2. Select the **CLI** tab. It shows `npm install supabase --save-dev` on the first line and `npx plugins add supabase-community/supabase-plugin` on the second. 3. Run `pnpm run -F docs test:local:unwatch internals/markdown-schema/AiPrompt.test.ts`. All tests pass.	2026-09-14 12:21:59 -07:00
Miranda LimonczenkoandClaude Opus 5	c7534b9e29	docs: document the stacked PRs workflow in edit-the-docs (#50018) ... Closes DOCS-1381 ## Problem The `edit-the-docs` skill describes a page edit as one continuous pass and has no notion of output. No commits, no branches, no PRs. It ends at edited files in the working tree. That leaves a reviewer one diff that mixes reworded prose, moved sections, and corrected claims, where a move can't be told from a rewrite. ## Solution - **Split the edit by change type:** style, structure, technical revision, and additions. Style runs before structure, so the structure diff reads as pure moves against already-clean prose. - **Ship one PR, one change type per commit.** A stack of PRs is an ask, not a default. When the edit both rewrites prose and moves sections and runs over roughly 150 changed lines, the skill says how large the diff is and offers the split. The requester decides, and no answer means one PR. A stack buys clean per-type diffs, and it costs a reviewer the whole-edit view, since no PR page shows it. - **State the scope boundary once.** The edit is exactly the buckets that have content. A dropped bucket is beyond the edit, and a later request for that change type is a new request. Additions stay author-driven, which keeps a mid-edit request from reopening an earlier commit. - **Scope the technical pass with a wrong-outcome test.** A claim changes only when leaving it would hand the reader an error, a different result than the page promises, or a fact that isn't true. An external best-practices rule doesn't clear that gate on its own, and a missing safeguard is an absence, so it goes to additions. Without the test, a verification pass becomes a rewrite. - **Add `reference/stacked-prs.md`** for the `gh stack` commands, branch naming, restack auditing, and the one command that diffs a whole stack at once. ### What driving the skill on a real page changed Running it end to end on a 684-line guide, then shipping the result, corrected five things a read-through didn't: - **The anchor gate grepped the wrong scope.** It said `apps/docs/content`. Five of the seven inbound anchors to that page lived outside it, in Studio components and `apps/www`, and those are the matches that break a Docs button in the product. The gate is now repo-wide and is step 1 of the structure pass, because moving a section preserves its slug and only renaming breaks it. That's what makes an aggressive regroup safe. - **Grouping sections by subject doesn't work.** On a page about tables every section is about tables, so subject grouping produces one task-named bucket that collects the background too. Classification is now by what the reader is doing, and the skill carries the outline that page settled on. - **Snippet testing finds claims, it doesn't just confirm them.** One example re-created a table an earlier example had made, which stopped that block and left a third example referencing a table nothing ever created. Every fence was individually correct; the sequence was not. So the rule is to run every fence in document order, because that order is what the reader pastes. - **Restacking silently drops upper-branch edits.** The conflict presents as new structure versus old content being re-added, and resolving toward the structure takes the edit with it. `stacked-prs.md` says to audit each branch with a grep per expected change rather than reading the diff. - **`build:guides-markdown` dirties a tracked file.** It writes `apps/docs/public/markdown/manifest.json`, which the repo commits as `[]`. Without a note the artifact lands in the next commit. ## Manual testing 1. Open `.agents/skills/edit-the-docs/SKILL.md` and read Phase 0. You can tell whether to ship one PR or offer a stack, and what to say when offering it, without opening the reference file. 2. Read the PR 3 section. The wrong-outcome test, the external-rule tiebreaker, and the absences line together tell you where a best-practices violation goes. 3. Run `npx prettier --check .agents/skills/edit-the-docs apps/docs/CONTRIBUTING.md`. Reports all matched files use Prettier code style. 4. Run `cat .claude/skills/edit-the-docs/reference/stacked-prs.md`. The branch table resolves through the `.claude/skills` symlink and shows `4+` as a pattern. 5. Run `git diff master -- .agents/skills/write-the-docs/SKILL.md`. Reports no changes, so nothing in `write-the-docs` routes a drafter into this workflow. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated guidance for editing existing documentation through distinct style, structure, technical, and additions phases. - Added work-sizing, scope, validation, confirmation, and handoff rules for stacked pull requests. - Documented support for multiple topic-based additions branches and their merge order. - Clarified when to use drafting versus editing workflows, including when a draft becomes a restructure. - Improved guidance for validating code examples, checking repository-wide references, handling generated artifacts, and updating pull request titles. - Updated contributor guidance and related documentation references. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-09-11 14:26:34 -07:00
Miranda Limonczenko	86f3a98399	fix(docs): stop reporting guide 404s to Sentry, redirect missing paths (#50279) ... Closes DOCS-1388 ## Problem Expected guide-path 404s were reported to Sentry as errors. They made up roughly 246k events and nearly all Docs volume, with 0 users impacted. The cause is a type check that never matched. `getGuidesMarkdownInternal` tested `error.cause instanceof FileNotFoundError`, but `GuideModelLoader.fromFs` rethrows `FileNotFoundError` directly and sets `cause` to the underlying `ENOENT` error. Every missing guide path fell through to the `else` branch and hit `Sentry.captureException`. Nine storage section paths and `database/postgrest` also 404 in production. They are section `url` values in the nav config with no landing page and no redirect. They are not reachable from the sidebar, because a nav item with children renders as an accordion button, so the traffic is inbound links and crawlers. ## Solution - Check the error itself as well as its cause, so expected 404s take the quiet branch. - Add `ignoreErrors` for `FileNotFound` to `sentry.server.config.ts`, matching the filtering the client config already does. - Redirect nine storage section paths to their first child page, following the existing `storage/cdn` and `storage/uploads` pattern. - Redirect `database/postgrest` to the Data API guide. The path has no git history, so its 27k hits are external inbound links. - Add the missing leading slash to the `storage/access-control` destination. It resolves correctly today, so this is a cleanup, not a fix. ## Redirect previews Redirects are served by the `www` config, so the **Redirect** column uses the www preview. The www preview cannot render `/docs/**` pages, so each link lands on a 404 after the hop. That is expected. Check the `Location` header, or use the **Destination** column to confirm the page itself. | Source | Redirect | Destination | | :--- | :--- | :--- | | `/docs/guides/storage/production` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/production) | [storage/production/scaling](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/production/scaling) | | `/docs/guides/storage/security` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/security) | [storage/security/ownership](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/security/ownership) | | `/docs/guides/storage/serving` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/serving) | [storage/serving/downloads](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/serving/downloads) | | `/docs/guides/storage/management` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/management) | [storage/management/copy-move-objects](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/management/copy-move-objects) | | `/docs/guides/storage/s3` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/s3) | [storage/s3/authentication](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/s3/authentication) | | `/docs/guides/storage/debugging` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/debugging) | [storage/debugging/logs](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/debugging/logs) | | `/docs/guides/storage/schema` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/schema) | [storage/schema/design](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/schema/design) | | `/docs/guides/storage/vector` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/vector) | [storage/vector/introduction](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/vector/introduction) | | `/docs/guides/storage/analytics/examples` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/analytics/examples) | [storage/analytics/examples/duckdb](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/analytics/examples/duckdb) | | `/docs/guides/database/postgrest` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/database/postgrest) | [api](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/api) | | `/docs/guides/storage/access-control` | [test](https://zone-www-dot-com-git-docs-sentry-404s-and-guide-fa783f-supabase.vercel.app/docs/guides/storage/access-control) | [storage/security/access-control](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/security/access-control) | All eleven return `308` on the www preview with the `Location` shown in the Destination column. Every destination returns `200`. ## Manual testing 1. Open any **Redirect** link above. The URL changes to the Destination path, confirming the redirect fires. 2. Open any **Destination** link. The page renders. 3. Confirm the sources 404 on production today, for example `https://supabase.com/docs/guides/storage/production`. 4. On the [docs preview](https://docs-git-docs-sentry-404s-and-guide-redirects-supabase.vercel.app/docs/guides/storage/schema), request a missing guide path and check the deployment logs. The line reads `Could not read Markdown at path`, not `Error processing Markdown file at path`. The second form is the branch that calls `Sentry.captureException`.	2026-09-11 14:05:24 -07:00
Miranda Limonczenko	15a7b0ab18	docs(database): correct the dashboard_user and storage admin role descriptions (#50274) ... Closes DOCS-1387 ## Problem The Postgres roles guide describes `dashboard_user` as "For running commands via the Supabase UI." That was the original intent, not current behavior. Dashboard queries run as `postgres` and carry a `-- source: dashboard` comment, which the [Postgres logs troubleshooting guide](https://supabase.com/docs/guides/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj) already documents. The two pages contradict each other. Two smaller problems in the same list: - `supabase_storage_admin` is described as an Auth middleware role, copied from the `supabase_auth_admin` entry above it. - Studio ships both stale strings in its own role tooltips. The docs list and `QUERY_PERFORMANCE_ROLE_DESCRIPTION` are near-verbatim copies of each other. ## Solution - Replace the `dashboard_user` description with what the Dashboard connects as instead, and point readers to the `-- source: dashboard` comment for finding Dashboard queries in the logs. - Attribute `supabase_storage_admin` to the Storage middleware. - Apply both corrections to the Query Performance and Query Insights role tooltips. ## Manual testing 1. Open the [roles guide on the deploy preview](https://docs-git-docs-dashboard-user-role-supabase.vercel.app/docs/guides/database/postgres/roles). 2. Scroll to `dashboard_user`. It states that the Dashboard doesn't connect as the role, and that Dashboard queries execute as `postgres` with a `-- source: dashboard` comment. 3. Select **find them in the Postgres logs**. The Postgres logs troubleshooting guide loads. 4. Scroll to `supabase_storage_admin`. It reads "Used by the Storage middleware," not "Auth middleware." 5. In Studio, open **Observability > Query Performance** and hover a `dashboard_user` or `supabase_storage_admin` value in the **Role** column. The tooltip shows the same two corrected descriptions. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Corrected the description of the `supabase_storage_admin` role to reference Storage middleware. - Clarified that the Dashboard does not connect using the `dashboard_user` role. - Documented that Dashboard queries run as `postgres` and can be identified in Postgres logs with a `source: dashboard` comment. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-11 11:57:25 -07:00
Miranda Limonczenko	23a5bd4707	fix: update inbound links to the pooling guide (#50187) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Bug fix. Link string changes only, no content changes. ## What is the current behavior? Nine inbound links in `apps/www` and `apps/studio` point at anchors on the connecting to Postgres guide that don't exist. All nine are already broken on production today: `#connection-pooler`, `#connection-pool`, `#how-connection-pooling-works`, `#serverside-poolers`, and `#connecting-with-drizzle` are all missing from the live page. #49869 moves the pooling content to a child page, so these links need current destinations either way. ## What is the new behavior? Point each link at the page that holds the content now. - **Studio, 3 links.** The Connect sheet's Drizzle link goes to the Drizzle guide. The connection pooling and pooling modes links go to `pooling-and-limits#how-connection-pooling-works`. - **www, 6 links.** Three blog posts, the Heroku comparison page, and the Dedicated poolers feature entry go to `pooling-and-limits`. The feature entry uses `#shared-pooler`. ## Additional context Split out of #49869. These paths belong to `@supabase/marketing` and `@supabase/Dashboard` in CODEOWNERS, and pulling both teams into a docs-only restructure for nine link strings isn't a good trade. Merge after #49928. The destinations don't exist on production until the docs pages land. ## Manual testing 1. Open [Supavisor: Scaling Postgres to 1 Million Connections](https://zone-www-dot-com-git-fix-pooler-docs-links-supabase.vercel.app/blog/supavisor-1-million). The "connection pooling" link in the opening paragraph resolves to `connecting-to-postgres/pooling-and-limits#how-connection-pooling-works`. 2. Open [Dedicated poolers](https://zone-www-dot-com-git-fix-pooler-docs-links-supabase.vercel.app/features/dedicated-poolers). The docs link resolves to `pooling-and-limits#shared-pooler`. 3. Open [Supabase vs Heroku Postgres](https://zone-www-dot-com-git-fix-pooler-docs-links-supabase.vercel.app/alternatives/supabase-vs-heroku-postgres). Both connection pooling links resolve to `pooling-and-limits#how-connection-pooling-works`. 4. Open [Connection pooling and limits](https://docs-git-docs-connecting-to-postgres-technical-supabase.vercel.app/docs/guides/database/connecting-to-postgres/pooling-and-limits) on the #49928 docs preview. The `how-connection-pooling-works` and `shared-pooler` headings both render with those IDs. 5. Open the Connect dialog on any project. Under Drizzle, the docs link opens the Drizzle guide. 6. Open Database settings, then Connection pooling. The pooler link opens Connection pooling and limits. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated connection pooling links across Studio, product pages, blogs, and comparison content to point to the relevant pooling guidance. * Refined links for Drizzle ORM, dedicated poolers, direct connections, and shared poolers. * Improved navigation to specific documentation sections explaining connection pooling modes and behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-09 17:10:55 -07:00
Miranda Limonczenko	bc102876bb	docs: apply the rest of the connecting to Postgres feedback (#49928) ... Closes FDBKIN-31335 Closes FDBKIN-13040 Closes FDBKIN-8653 Closes FDBKIN-19912 Closes DOCS-740 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. While we are revising this document, this PR gathers docs feedback via AI magic and applies that feedback. ## What is the current behavior? These findings stand on feedback intake rather than on the baseline. Worth doing, and the eval won't show a score change for any of them. - **Nothing explains the pooler host.** #49868 switched the strings to `[POOLER-HOST]`, but the page never says why you can't compose the host, and agents that recite `aws-0` get `Tenant or user not found`. agent-skills#92. - **The page gives the instruction to turn prepared statements off, but not the flag.** It also links the GitHub discussion rather than the troubleshooting entry that mirrors it. FDBKIN-8248, FDBKIN-7883. - **SSL goes undiscussed.** Four of six eval runs set `ssl: 'require'` unprompted. - **The pooled username format only appears inside example strings**, never as a rule. DOCS-740, FDBKIN-19912. - **Third-party tools have no answer.** Session mode is the right one, and the decision table had no row for a BI client or database GUI at all. FDBKIN-8653. - **Only one of transaction mode's three limitations is documented.** FDBKIN-13040 names prepared statements, cursors, and session-level settings. The page covered prepared statements. ## What is the new behavior? - Tell the reader to copy the host, port, and username rather than typing the placeholders, and explain the pooler cluster index next to the reference table. The placeholders themselves changed in #49868. - State the username rule: direct connections and the dedicated pooler use `postgres`, shared pooler connections use `postgres.<project-ref>`. - Add a per-driver prepared statements table for Postgres.js, Drizzle, Prisma, asyncpg, and JDBC, and link [Disabling prepared statements](https://supabase.com/docs/guides/troubleshooting/disabling-prepared-statements-qL8lEL) for the rest. Add JDBC's `prepareThreshold=0` to that entry too, so the two pages agree. - Document SSL: `require` rather than the `prefer` default, which falls back to plaintext. - Link the `CONNECT_TIMEOUT` entry for stale sockets in frozen serverless runtimes. - Add a decision table row for a third-party tool, and point at Quickstarts for named tools. - Cover all three transaction mode limitations. Cursors work inside a single transaction only, and session-level state is lost between transactions: `set` and `reset`, session-level advisory locks, `listen` and `notify`, and temporary tables. Renamed the section from "Prepared statements", since it now covers the cause rather than one symptom. - Promote Configure your client to an H2 and fold the SSL certificate section into it. The table of contents only renders H2 and H3, so the client settings were invisible as H4s. ## Manual testing 1. Open [Connect to your database](https://docs-git-docs-connecting-to-postgres-technical-supabase.vercel.app/docs/guides/database/connecting-to-postgres) on the deploy preview. 2. Read the Get your connection string lead-in. It tells you to copy the host, port, and username rather than typing the placeholders. 3. Check the table of contents. Configure your client is an H2 with Application-side pool size, Prepared statements, SSL, and Stale connections under it. 4. Follow the prepared statements link. It lands on the in-docs troubleshooting entry, not GitHub. 5. Open the [endpoint reference](https://docs-git-docs-connecting-to-postgres-technical-supabase.vercel.app/docs/guides/database/connecting-to-postgres#endpoints-and-ip-versions). The table shows `aws-[INDEX]-[REGION]`, and the prose below explains the index and the username rule. 6. Read the decision table. It has a row for a third-party BI client or database GUI, pointing at session mode. 7. Read [Transaction mode limitations](https://docs-git-docs-connecting-to-postgres-technical-supabase.vercel.app/docs/guides/database/connecting-to-postgres#transaction-mode-limitations). It covers prepared statements, cursors, and session-level state. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Documentation - Expanded the Postgres connection guide with clearer client configuration guidance, including pool sizing, SSL, stale connections, and transaction mode limitations. - Added recommendations for BI tools and database GUIs using the shared pooler. - Clarified connection strings, pooler hosts, usernames, ports, and IP version behavior. - Updated serverless driver guidance for transaction mode configuration. - Added JDBC troubleshooting instructions for disabling prepared statements with `prepareThreshold=0`. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-09 16:49:42 -07:00
Miranda Limonczenko	15484a0e75	docs: add application-side pool sizing to the connecting to Postgres guide (#49927) ... Closes DOCS-1312 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. One technical addition, isolated so the eval can attribute a score change to it. I re-ran the preview link on a scratch Eval branch and found that this PR will resolve the Eval. ## What is the current behavior? The eval baseline for `build-docs-004-postgres-connection` fails one check, 3 of 6 runs: the application-side pool cap for a serverless invocation. - Two failing runs left `max` unset, which is 10 on the Postgres.js default. - One set `max: 5`. The page says nothing about the application-side pool, so there was nothing for an agent to read. Every other check passes 6/6, including the connection string, port, username, and prepared statements. The mode choice already transmits from the page. Baseline notes are on [DOCS-1312](https://linear.app/supabase/issue/DOCS-1312). ## What is the new behavior? Add a **Configure your client** section to the procedure group. Pool sizing is its only subject. - Set the application-side pool to 1 connection per serverless invocation, and raise it only on evidence. - Name the trap concretely. Library defaults assume a persistent backend, and 10 connections is 10 per warm instance, with the instance count outside your control. - One Postgres.js sample setting `max` and `prepare`, created at module scope. - Cite the [Supavisor FAQ](https://supabase.com/docs/guides/troubleshooting/supavisor-faq-YyP5tI) and [Prisma troubleshooting](https://supabase.com/docs/guides/database/prisma/prisma-troubleshooting), which already carries the equivalent `connection_limit` guidance for one ORM. The gap is that the connection guide didn't carry it for readers not using Prisma. `prepare: false` is in the sample because a transaction mode sample is wrong without it, and the page already instructs it. It isn't new guidance. `ssl: 'require'` is, so it waits for #49928. ## Additional context PR 3 of 4. Base is #49869. This ships alone on purpose. It's the only change with baseline evidence behind it, so a score change after this PR is attributable to one edit. #49928 carries the rest of the eval feedback and is not expected to move the score. **Run the eval against this preview before #49928 lands.** ## Manual testing 1. Open [Connect to your database](https://docs-git-docs-connecting-to-postgres-pool-size-supabase.vercel.app/docs/guides/database/connecting-to-postgres) on the deploy preview. 2. Check the table of contents. "Configure your client" appears under Get your connection string. 3. Read the section. It states 1 connection per invocation and names the Postgres.js default of 10. 4. Read the sample. It sets `max: 1` and `prepare: false`, and says the client is created once at module scope. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added guidance for configuring application-side Postgres clients when connecting through Supabase poolers. - Documented recommended serverless settings, including creating the client once, limiting connections per invocation, and disabling prepared statements in transaction mode. - Added a Postgres.js configuration example and links to relevant Supavisor FAQ and Prisma troubleshooting resources. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-09 16:39:09 -07:00
Miranda Limonczenko	976e7338bc	docs: restructure the connecting to Postgres guide by information type (#49869) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. Restructure, mostly moved lines, plus inbound anchor fixes. ## What is the current behavior? The page states the same routing decision four times and never states an answer: - Intro bullets - A matrix table - A "How to choose the right connection method?" section - A Mermaid flowchart An agent asked "I'm deploying to Vercel serverless functions, set up the database connection" has to synthesize an answer from four partial, inconsistent restatements. Context, procedure, and reference material are interleaved throughout, so background reading interrupts the action path. The page is also too long at 2,883 words, and grouping alone doesn't fix that. Explainer and reference material need their own page, and the troubleshooting group belongs in troubleshooting entries. 16 of the 19 inbound anchor links to this page are already broken on `master`, before any restructure: `#direct-connections`, `#shared-pooler`, `#connection-pooler`, `#how-connection-pooling-works`, `#quick-summary`, `#connection-pool`, and `#connecting-with-drizzle`. Groundwork for [DOCS-1312](https://linear.app/supabase/issue/DOCS-1312). The issue stays open until the paired eval is re-run. ## What is the new behavior? Group the guide into a decision, a procedure, context, reference, and troubleshooting, per CONTRIBUTING § Guides on mixed information types. Review with `git diff --color-moved=zebra`. - Lead with "Which connection method do you use?", a decision table keyed on where your code runs. Section navigation sits directly below the intro. - Collect every connection string under "Get your connection string", with the shared Connect dialog steps stated once as a procedure. - Move the endpoint, port, pool size, and connection limit material into "Connection reference". These were FAQ questions. - Split the page. The guide keeps the decision, the connection strings, and the quickstarts, at 1,180 words and three paths. A new child page, Connection pooling and limits, carries how pooling works, pool size, connection limits, and monitoring. - Move the endpoint and IP version table up beside the connection strings it explains. - Replace the troubleshooting group with two new troubleshooting entries, `tenant-or-user-not-found` and `fatal-password-authentication-failed`, plus links to the existing entries. The existing connection-refused entry is stronger than what was here: it names the IP ban and gives the unban procedure. - Cut the pool size worked example. It said a pool size of 30 is a shared ceiling across session and transaction mode, while the Supavisor FAQ and the terminology entry both say pool size is per user, database, and mode combination. That text came from `master`, so the contradiction is pre-existing. Link the FAQ as the authority rather than picking a side. - Drop the duplicate `pg_stat_ssl` query, which already exists in `connection-management.mdx` and `monitor-supavisor-postgres-connections.mdx`, both with column tables this page lacked. - Add the subsection to the navigation, which also adopts `connecting-to-postgres/serverless-drivers`. That page existed on disk and was referenced nowhere in the navigation constants. - Delete the decision flowchart. It was the fourth restatement of the decision table, and its logic was broken: `Persistent Backend` had two unconditional edges into decision nodes that each had one unlabeled output, so neither node decided anything. - Fix every broken inbound anchor, and pin stable anchors on the headings they target. This now includes six files in `apps/www` that no earlier pass in this stack checked, most of which were already broken on `master`. - Repoint the Studio Connect sheet's Drizzle link at the Drizzle guide. It pointed at a heading this page hasn't had for some time. - Serverless drivers: state the guide's intent, give the three runtimes parallel structure, and link the transaction mode prepared statements constraint. That page never mentioned the constraint that most affects serverless connections. ## Additional context PR 2 of 2. Base is #49868, rebased on its review feedback commit. Three of the 13 files are in `apps/studio`, so this runs the Studio unit tests, build, and lint ratchet. They are link string changes only. The ESLint warning count is unchanged at 1 on the touched files, so the ratchet holds. ## Manual testing 1. Open [Connect to your database](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/database/connecting-to-postgres) on the deploy preview. 2. Check the table of contents. The top level reads: Which connection method do you use?, Get your connection string, Quickstarts, Related. The intro lists three paths. 3. Open [Reports](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/monitoring-and-debugging/reports) and follow "Implement connection pooling" under Disk IO. It lands on the decision table. 4. Open [Serverless drivers](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/database/connecting-to-postgres/serverless-drivers). The intro links the transaction mode prepared statements constraint. 5. Check the sidebar. Connecting to your database expands to Connection pooling and limits and Serverless drivers. 6. Open [Connection pooling and limits](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/database/connecting-to-postgres/pooling-and-limits). Pool size states the setting and links the Supavisor FAQ, with no worked example. 7. Open [Tenant or user not found](https://docs-git-docs-connecting-to-postgres-structure-supabase.vercel.app/docs/guides/troubleshooting/tenant-or-user-not-found). <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added a dedicated guide covering connection pooling, limits, configuration, and monitoring. * Added troubleshooting guides for password authentication failures and shared pooler tenant or user errors. * Expanded connection guidance with method selection, endpoints, IP versions, and serverless driver configuration. * **Documentation** * Reorganized database connection documentation and navigation. * Updated related links throughout the documentation to current connection and pooling guidance. * Improved guidance for pooler modes, connection strings, and supported deployment environments. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-09 16:21:41 -07:00
Miranda Limonczenko	7fbaeb3dcd	docs: style edit for the connecting to Postgres guide (#49868) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. Style only. ## What is the current behavior? The connecting to Postgres guide and its serverless drivers child page have drifted from `WORD_LIST.md` and `CONTRIBUTING.md`. They also carry six defects: - The connection pooling diagram's alt text describes migrations on a preview instance. - The SSL screenshot's alt text and the sentence above it both promise connection info. The image shows the SSL Configuration panel: a toggle and a Download Certificate button. - "Where can you see current connection usage?" lists three Observability reports, then says the Roles page is not real-time. The Roles page appears nowhere else in that answer. - The serverless drivers manual configuration step has no main clause. - "For example, If you set the pool size to 30". - One of the two monitoring queries uses uppercase SQL keywords. Three of the four connection strings use `postgres://` and two carry literal project refs. The Connect dialog emits `postgresql://` with placeholders. The pooler host is templated as `aws-[region]`, which reads as composable and isn't. Hosts are `aws-<index>-<region>.pooler.supabase.com`, and the index is a pooler cluster index, not part of the region. Both `aws-0-us-west-1` and `aws-1-us-west-1` appear in this repo, so a reader can't derive it. Studio doesn't compose the host either; it comes from the API. Groundwork for [DOCS-1312](https://linear.app/supabase/issue/DOCS-1312). The issue stays open until the paired eval is re-run. ## What is the new behavior? Word-level edit. No section is added, moved, or reordered, so the restructure in the next PR of this stack lands as a readable set of moved lines. Headings are untouched; PR 2 owns all heading changes. - Fix the six defects above. - Align the connection strings with what the Connect dialog emits: `postgresql://` on all four, and `[PROJECT-REF]` in place of two literal project refs. - Use `[POOLER-HOST]` in the copyable pooler strings, the convention the newer quickstarts already use. Keep the full `aws-[INDEX]-[REGION]` shape in the summary table, where showing the shape is the point. - Settle on one name per concept: shared and dedicated pooler in sentence case, persistent backend, serverless and edge functions, and paid plans. - Drop bold used for plain emphasis, parenthetical asides, and claims the page doesn't support: "ideal for", "ensures best performance and latency", "satisfactory on their own". - Format the two literal error strings as code, not quotes. - Split the pool size answer into one paragraph per subject, and turn the two pooler limits into a table. - Serverless drivers: sentence case title, an intent sentence, and a four-step procedure in place of the sentence fragment. ## Additional context PR 1 of 2. Base is `master`. Second commit applies review feedback. Third fixes the pooler host placeholder, which belongs here rather than later in the stack: the evidence is in the repo, not in the eval. ## Manual testing 1. Open [Connect to your database](https://docs-git-docs-connecting-to-postgres-style-supabase.vercel.app/docs/guides/database/connecting-to-postgres) on the deploy preview. 2. Read the four connection strings. All four use `postgresql://`, and the two pooler strings use `[POOLER-HOST]` rather than a composable region template. 3. Inspect the two images. The pooling diagram's alt text describes pooling, and the SSL screenshot's describes the SSL Configuration panel. 4. Read "Where can you see current connection usage?". The paragraph after the report list refers to the reports, not the Roles page. 5. Read "What is the difference between client connections and backend connections?". The two limits are a table. 6. Open [Serverless drivers](https://docs-git-docs-connecting-to-postgres-style-supabase.vercel.app/docs/guides/database/connecting-to-postgres/serverless-drivers). Manual configuration is four numbered steps. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Clarified the PostgreSQL connection guide with updated connection examples, pooling guidance, connection-mode tables, SSL information, FAQs, and SQL formatting. - Replaced sample connection values with generic placeholders in documentation examples. - Added clearer guidance that frontend Data API access requires appropriate RLS policies. - Updated explanations of client/backend connections and long-lived PostgreSQL sessions. - Updated serverless driver documentation with clearer setup guidance for Vercel, Cloudflare, and Supabase Edge Functions. - Reorganized manual configuration into numbered steps and standardized connection string examples. - Improved descriptions of runtime behavior and supported connection methods. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-09 15:24:02 -07:00
Miranda Limonczenko	4d2bd0eacf	docs: add the missing API key decision information (#49799) ... Closes DOCS-1311 Closes FDBKIN-2926 Closes DOCS-694 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. Corrections and new content. This is the PR that is to bring the Eval to green. ## What is the current behavior? Two statements are wrong, and the gaps behind most logged confusion about this page are unfilled. - The Availability column marks publishable and secret keys Platform-only. `supabase start` prints both. - The page says Edge Functions only verify the legacy keys and to use `--no-verify-jwt`. #49700 updated `guides/functions/auth-headers` to document that `verify_jwt` accepts the new keys on either header, but left this page and the migration guide stating the old behavior. - The page has no code samples, so it never shows how a key reaches code. An agent reading it falls back on `SUPABASE_SERVICE_ROLE_KEY`, the legacy key this same page deprecates. - Nothing maps `anon` and `service_role` to their replacements, or says the replacements aren't `eyJ`-prefixed JWTs. - The Postgres role table covers only publishable keys. ## What is the new behavior? Corrections: - Mark all four key types available on Platform and CLI, and note that the local secret key takes the place of the local `service_role` key. - Point the Edge Functions guidance at the `@supabase/server` SDK instead of `--no-verify-jwt`. Fix the same bullet in the migration guide. Additions: - "Coming from `anon` and `service_role`" gives the legacy-to-new mapping and says the replacements aren't JWTs. - Extend the Postgres role table to cover secret keys, and note that grants are evaluated before Row Level Security, so a missing grant fails even for `service_role`. - State who does what. Copying a key needs a signed-in Dashboard session, so it is a person's step, while code only refers to the variable name. Add a `.env` sample naming the variables. - Add the two `createClient` samples the page lacked, plus an "Inside an Edge Function" subsection using `withSupabase`, which reads no key from the environment. - Cross-reference from the key decision to retrieving a value, wiring it into code, or migrating an application that ships legacy keys. ## Additional context PR 4 of 4. Base is #49797. ## Manual testing 1. Open the API keys guide on the deploy preview. 2. Check the Key types table. All four rows read "Platform, CLI". 3. Check Known limitations. It no longer mentions `--no-verify-jwt`. 4. Open the migration guide and check Known limitations. The Edge Functions bullet matches. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated API key guidance with clearer instructions for finding, selecting, and using publishable and secret keys. * Added examples for environment variables, client applications, backend code, and Edge Functions. * Clarified key formats, CLI availability, local development output, Postgres role mappings, and authorization behavior. * Expanded guidance on `apikey` headers, RLS errors, and Edge Function API key authorization. * Refined migration guidance for API key authentication in Edge Functions. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-01 14:40:55 -07:00
Miranda Limonczenko	5bd0b90cf0	docs: add all ways to get an API key (not just Studio) (#49797) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. ## What is the current behavior? "Find your keys" offers only the Dashboard. Readers working from a script, a preview branch, or a local stack have no path, which accounts for several logged reports of people unable to locate a key. ## What is the new behavior? Replace the procedure with a tabbed selector so a reader picks the path that matches where they work: - Dashboard, through the Connect dialog or Settings > API Keys. - Supabase CLI, `supabase projects api-keys --project-ref`, including the note that a preview branch has its own keys and needs its own ref. - Management API, `GET /v1/projects/{ref}/api-keys?reveal=true`, for deploy scripts and provisioning tooling. - Local stack, from `supabase start` output or `supabase status`. `queryGroup="retrieval-method"` makes each tab deep-linkable, so a reader can be sent straight to one path. ## Additional context PR 3 of 4. Base is #49796. ## Manual testing 1. Open the API keys guide on the deploy preview and find "Find your keys". 2. Select each tab. One panel shows at a time, and the URL gains `?retrieval-method=<tab>`. 3. Open that URL in a new tab. It restores the same selection. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated the API key deprecation guidance to link to the “Find your keys” guide. - Expanded the guide with instructions for retrieving keys through the Dashboard, CLI, Management API, and local stack. - Added guidance to create keys in the Dashboard when none are available. - Reworded the table of contents entry for improved clarity. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-01 14:40:54 -07:00
Miranda Limonczenko	d7f1a44e53	docs: restructure the API keys guide by information type (#49796) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. Restructure, mostly moved lines, plus a tense fix in a shared partial. ## What is the current behavior? Context, procedure, and reference material are interleaved, so background reading interrupts the action path. - The page never states which key to use as an answer. You infer it from a five-column reference table. - Finding a key is a fragment inside an admonition, placed above the page's own definition of an API key. - Rotating a leaked key, the only procedure on the page, is the last H3. - The "Changes to API keys" notice narrates a past change in future tense, and "They will be deprecated" has no antecedent in its paragraph. ## What is the new behavior? Group the guide into context, procedure, and reference sections, per CONTRIBUTING § Guides on mixed information types. - Lead with "Which key do you use?", a decision table keyed on where the code runs. Section navigation sits directly below the intro. - Collect the conceptual sections under "How API keys work" and give publishable and secret keys parallel headings. - Promote both procedures into "Find and use your keys". Rotation is now an ordered procedure. - Move the enumerated secret key rules into "Security reference", grouped under bold labels by the kind of mistake each prevents, and leave a short danger admonition where secret keys are introduced. - Promote the five-sentence coexistence admonition to its own section. Admonitions are for short warnings. - Rewrite the shared deprecation partial for timeless documentation: present tense, no dangling "They", no "now". The partial renders on five pages. - Pin a stable anchor on the rotation heading and update the one inbound link, in the rotating-anon-service-and-jwt-secrets troubleshooting entry. - Align link text across docs for this guide. Twenty-one links pointed at it under fourteen labels, including two that named the wrong destination. Rule: when a link means the guide, the text is "API keys"; when it means a specific key or section, the specific text stays. Twelve now share "API keys", up from three. Review with `git diff --color-moved=zebra`. ## Additional context PR 2 of 4. Base is #49795. Includes the link-text alignment previously opened as #49866. ## Manual testing 1. Open the API keys guide on the deploy preview. 2. Check the table of contents. It shows three groups: How API keys work, Find and use your keys, Security reference. 3. Open the rotating-anon-service-and-jwt-secrets troubleshooting entry and follow "Rotate a leaked or compromised key" under Further readings. It lands on the renamed heading. 4. Open the Realtime Broadcast guide and check the "Changes to API keys" notice. It reads in present tense there too. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated API key guidance to explain the transition from legacy `anon` and `service_role` keys to publishable and secret keys by the end of 2026. - Reorganized the API keys guide with clearer key-selection guidance, security recommendations, usage examples, and rotation steps. - Updated troubleshooting references to point to the revised leaked-key rotation guidance. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-01 14:40:54 -07:00
Miranda Limonczenko	2f31010a18	docs: style edit for the API keys guide (#49795) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. Style only. ## What is the current behavior? The API keys guide has drifted from `WORD_LIST.md` and `CONTRIBUTING.md`. It also carries two defects: - The rotation steps tell you to replace the new key with the compromised one, rather than the reverse. - The secret key caution list opens with "Do not:" but several items read "Never use" and "Do not pass", which inverts them into the opposite instruction. ## What is the new behavior? Word-level edit. No section is added, moved, or reordered, so the restructure in the next PR of this stack lands as a readable set of moved lines. - Fix the reversed rotation instruction. - Rewrite the caution list so every item completes its "Don't:" stem. - Replace the Silicon Valley character names and trailing ellipses in the responsibility table. - Drop italics used for plain emphasis, parenthetical asides, `etc.`, `&`, the lint-flagged "easy", and existential sentence openers. - Replace "since" and "as" used for cause, and future tense used for current product behavior. ## Additional context PR 1 of 4. Base is `master`. ## Manual testing 1. Open [Understanding API keys](https://docs-git-docs-api-keys-style-edit-supabase.vercel.app/docs/guides/getting-started/api-keys) on the deploy preview. 2. Read the secret key caution list. Every item completes the "Don't:" stem. 3. Read "What to do if a secret key or `service_role` has been leaked or compromised". The order is: create the new key, then replace the compromised key with it. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Rewritten the API keys guide with clearer wording and improved structure. * Clarified how to access API keys through the Connect dialog and distinguished API keys from Supabase Auth. * Updated explanations of publishable and secret keys, including cautions, security best practices, and steps for responding to leaked keys. * Refined guidance on known limitations and compatibility differences. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-09-01 14:40:53 -07:00
Miranda Limonczenko	f09d35cfd5	fix(docs): make code blocks reachable and readable by keyboard and screen reader (#49562) ... Closes DOCS-1283 https://github.com/user-attachments/assets/6e55a27f-6f73-453b-b98f-e91d3c14a9e4 ## Problem Three defects in the docs code block: - The scroll container has no `tabindex`. On `/guides/database/tables`, 18 blocks, none focusable, 2 overflowing at 1280px. Tab skips the scroll region, so a keyboard-only user cannot scroll code that runs off the edge. - The container has `role="group"` with no accessible name, so it announces as bare "group". - The line-number gutter has no `aria-hidden`, so digits are read inline with the code. A block linearizes as `1import { createClient } from '@supabase/supabase-js'23const supabase = ...`, with lines 2 and 3 collapsing into "23". Four more surfaced while testing the fix: - The wrap and copy buttons were absolutely positioned inside the element that scrolls, so `right-2` measured against the scrollable content box. Scrolling dragged them out of the corner into the middle of the code. This one predates the PR. - The buttons preceded the code in the DOM, so a screen reader read two actions before naming what they act on. - `focus-within` only fired for the buttons, so focusing the block left the controls invisible. - Both buttons set an `aria-label` identical to their tooltip text, and Radix points `aria-describedby` at the tooltip on focus, producing "Copy code, button, Copy code". ## Solution Keyboard: - Split the scroll region out of the positioning container, so the controls stay pinned. - Give the scroll region a `tabIndex` and a focus ring. - Reveal the controls on `group-focus-within`. Screen reader: - Name the region `<language>, <n> lines`. Code content stays readable; the summary goes in the name so the group can be skipped or stepped into. - Map fence aliases to spoken names, so `ts` announces as TypeScript. Only the ambiguous ones; `bash`, `python`, `kotlin`, `dart`, `swift` already read fine. - `aria-hidden` the gutter. The numbers are already `select-none`, and copy takes its content from the source string rather than the DOM, so copy behavior is unchanged. - Order the controls after the code. - Announce the word wrap toggle through a live region, matching the copy button. - Opt both buttons out of Radix's generated description. Also moved the `data-wrapped` side effect out of the `setIsWrapped` updater, since React calls updaters twice under StrictMode. ## Manual testing 1. Open `/docs/guides/database/tables`. 2. Run `document.querySelectorAll('.code-scroll[tabindex="0"]').length` in the console. Expect `18`. 3. Run `[...document.querySelectorAll('.code-scroll')].map(b => b.getAttribute('aria-label'))`. Expect entries like `SQL, 11 lines` and `bash, 2 lines`, plus one bare `2 lines` for the fence with no language. 4. Tab to a code block. Expect a visible focus ring, and the wrap and copy buttons to appear. 5. Press ArrowRight on the block under "Basic data loading", which overflows. Expect it to scroll, and the buttons to stay in the top-right corner. 6. Press Enter on the wrap button. Expect the code to wrap and a screen reader to announce "Word wrap enabled". 7. With VoiceOver on, focus a code block. Expect "SQL, 11 lines, code block", then the code read without line numbers interleaved. Focus each button and expect its name once, not twice. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Accessibility** - Improved code block labels for screen readers, including programming language and line count. - Added announcements when word wrap is enabled or disabled. - Enhanced keyboard focus behavior for code block controls. - **Usability** - Kept code block controls visible while scrolling through code. - Improved wrapped-code overflow handling. - Removed redundant tooltip descriptions for copy and word-wrap controls. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-08-26 10:43:40 -07:00
Miranda LimonczenkoandClaude Opus 5	60f7903b52	fix(www): group the filter controls and announce the result count (#49410) ... Closes FE-4251 ## Problem The filter sidebars are unstructured `div` nesting. Measured on a preview: * 9 checkboxes on `/features` and 13 on `/partners/catalog`, none inside a `fieldset`, a `role="group"`, or any region. * The `/features` "Filter by tags:" `h2` has no `id`, so nothing can reference it as a group name. * The only landmarks on `/features` are two `nav` elements, so the filter panel is unreachable by landmark navigation. A screen reader user meets a checkbox announced as "authentication, checkbox" with nothing conveying that it filters features by tag. Separately, both result counts update on every filter change with no live region, so the outcome of toggling a filter is never announced. ## Solution * Wrap each checkbox set in a labelled `role="group"`. * Wrap each filter panel in an `aside` labelled "Filters". * Add `aria-live="polite"` to both result counts. The two pages name their group differently on purpose. `/features` uses `aria-labelledby` pointing at the existing `h2`, so the visible heading is the accessible name. `/partners/catalog` uses `aria-label`, because `filtersPanel` renders into both the desktop sidebar and the mobile sheet, so an `id` would appear twice in the DOM. That file already calls out the duplicate-id hazard at line 152 as its reason for using wrapping labels. Chose `role="group"` over `fieldset` and `legend` to avoid resetting UA styling in a styled sidebar. The single self-hosted checkbox keeps its own label and needs no group. ## Manual testing **/features** 1. Open [/features](https://zone-www-dot-com-git-www-filter-groups-and-live-count-supabase.vercel.app/features) with Screenreader. 2. Confirm the tag checkboxes report as a group named "Filter by tags:". 3. Confirm a "Filters" landmark appears in landmark navigation. 4. Tick a tag filter. The result count changes and is announced. **/partners/catalog** 5. Open [/partners/catalog](https://zone-www-dot-com-git-www-filter-groups-and-live-count-supabase.vercel.app/partners/catalog) at a desktop width. The filter panel is `hidden md:block`, so the landmark only exists at md and above. 6. Confirm the category checkboxes report as a group named "Categories". 7. Open the mobile filter sheet at a narrow width and confirm the group is still named, with no duplicate ids. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Accessibility Improvements** * Improved screen reader navigation for partner catalog and feature filters. * Added accessible labels and landmarks for filter sections. * Updated result counts to be announced when selections change. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-24 09:46:03 -07:00
Miranda LimonczenkoandClaude Opus 5	78d6d57faa	fix(www): stop rendering the invisible Clear all filters button (#49409) ... Closes FE-4250 <img width="661" height="294" alt="Screenshot 2026-08-21 at 10 44 38 AM" src="https://github.com/user-attachments/assets/db7e09db-845c-43a8-a6ca-5d0c67436355" /> ## Problem With no filters active, `/features` still rendered the "Clear all filters" button and hid it with `opacity-0`. Found with VoiceOver, which announced "You are currently on a button" on an apparently empty control. Measured on a preview with no filters active: | Property | Value | | -- | -- | | `opacity` | `0` | | `visibility` | `visible` | | `display` | `block` | | `tabIndex` | `-1` | | `aria-hidden`, `inert`, `disabled` | none | | `pointer-events` | `auto` | | Layout | 256 x 26px | Two assumptions were wrong. `opacity: 0` does not remove an element from the accessibility tree, and `tabIndex="-1"` only removes it from tab order, not the tree. Screen readers walk the tree. It was also a live 256 x 26 mouse target, so a sighted user could click an invisible button. ## Solution Render it conditionally, matching `IntegrationsContent.tsx` which already does this and was unaffected. No layout shift. The button is the last child of the sidebar column, so nothing above it moves when it appears. ## Manual testing 1. Open [/features](https://zone-www-dot-com-git-www-features-clear-filters-button-supabase.vercel.app/features) with no filters applied. Confirm no "Clear all filters" button exists anywhere in the DOM. 2. Tick a tag filter in the left sidebar. The button appears. 3. Click it. Every filter clears, the count returns to 79 features, and the button disappears again. For the before state, open [/features on production](https://supabase.com/features) with no filters, then run this in the console. It reveals the button that is present but invisible: ```js const b = [...document.querySelectorAll('button')].find(x => /Clear all filters/.test(x.textContent)) Object.assign(b.style, { opacity: '1', outline: '3px solid red' }) ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * The “Clear all filters” button now appears only when filters are active. * Improved keyboard navigation by removing inactive filter controls from the tab order. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-24 09:38:38 -07:00
Miranda LimonczenkoandClaude Opus 5	21265b2e59	docs(database): make writing and running the tests part of the procedure (#49276) ... Ref DOCS-1274 Follow-up to #49017, now merged. This is the go-to-green piece: everything aimed at the three failing eval checks, and nothing else. Technical corrections follow in the PR stacked on this one. ## Problem `build-docs-002-rls-guide` points an agent at this guide with a vibe-coder prompt that never says RLS, policy, role, or test. Grants, policies, access probes, indexes, and security-definer placement all pass. Three checks fail, and have failed on every recorded run: | Check | What it measures | Why it failed | | --- | --- | --- | | `pgTAP test file(s) written under supabase/tests/` | Any `.sql` file exists | The agent never wrote one. | | `supabase test db runs at least 8 assertions and all pass` | Suite runs, ≥8 assertions, none failing | Nothing to run. The only example was `plan(4)`, under the floor even if copied perfectly. | | `tests assert allow and deny per operation … for anon and authenticated` | LLM judge on coverage | Never reached the judge: "no test files to review". | The guide already had a `Test your policies` section, so this isn't a strength problem. Agents don't read the page. They fetch it through an LLM extraction guided by their own query, and that query asked for enabling RLS, policy syntax, `auth.uid()`, indexes, and security definer functions. It never mentioned tests. A section about testing never enters the extract, so more testing prose cannot reach the agent. There was also a plain documentation bug underneath it: `Secure a table with RLS` said a table isn't secured until the suite passes, but the procedure beneath it ran 1–3 and ended on `grant`. A reader following the numbered steps finished without ever being told to write a test. ## Solution Put the tests where the procedure and the examples already are. - **`Secure a table with RLS`** opens with the four steps that finish a table, ending on `supabase test db`. Until the suite passes, you don't know whether the policies do what you intended. - **`Enable RLS and set the grants` gains step 4** — `supabase test new <table>_rls.test`, then `supabase test db`. The procedure ends on a passing suite instead of a grant. - **The public-read example** gains its policy and `announcements_rls.test.sql`, so a test file rides along in the enable-RLS extract. - **The four policy examples** are followed immediately by `profiles_rls.test.sql`, so one rides along in the `create policy` extract too. - **`Run the test suite` shrinks** to creating and running the files. It no longer carries content that has to survive extraction. - Each file leads with its own path as a comment, so it survives if the fence metadata is dropped. ### How that maps to the three checks | Check | Addressed by | | --- | --- | | Test files written | A complete test file now sits inside both extracts an agent's own query pulls, and step 4 of the procedure names the command that creates one. | | ≥8 assertions, all passing | `announcements_rls.test.sql` is `plan(10)`, `profiles_rls.test.sql` is `plan(14)`. Either alone clears the floor; together, 24. | | Coverage judge | `profiles` asserts allow **and** deny for all four operations. Allowed writes use `returning` + `results_eq`, proving state changed rather than that nothing raised. `using`-filtered denials use `is_empty`, asserting the row is unchanged rather than that an error was raised — the case the rubric explicitly fails suites for getting wrong. Both files switch role with `set local role` and identity with `set local request.jwt.claim.sub`, and cover `anon` as well as `authenticated`. | ## Manual testing 1. Open the [Row Level Security guide](https://docs-git-docs-rls-tests-in-procedure-supabase.vercel.app/docs/guides/database/postgres/row-level-security) on the preview. `Secure a table with RLS` opens with a four-step definition of done ending on `supabase test db`. 2. Read `Enable RLS and set the grants`. The procedure runs 1–4 and ends on writing and running the test, not on the grant. 3. Scroll to `DELETE policies`. The four policies are followed immediately by `profiles_rls.test.sql`, not a pointer to a later section. 4. Open the [markdown version](https://docs-git-docs-rls-tests-in-procedure-supabase.vercel.app/docs/guides/database/postgres/row-level-security.md), which is what agents fetch. Both test files are present, each leading with its path. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Documentation - Updated database security guidance for enabling row-level security and configuring grants. - Added per-table pgTAP testing requirements and revised `supabase test db` examples. - Expanded examples for permitted and denied access across public and authenticated roles. - Added dedicated guidance for profile testing and security-definer member/non-member cases. - Documented recursive-policy `42P17` failures and the security-definer workaround. - Clarified indexing, denial diagnosis, returned-row verification, and table-hardening links. - Streamlined the general policy-testing guidance. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-24 09:23:33 -07:00
Miranda LimonczenkoandClaude Opus 5	0243ad7cf1	fix(www): make the view toggles a radio group and fix the filter rows (#49346) ... Closes FE-4227 > [!NOTE] > Bottom of a stack. #49409 and #49410 sit on top of this one, so merge this first. ## Problem Five defects in the view toggles on `/features` and `/partners/catalog`, plus one in the `/features` filter rows. All measured on a preview. **Toggles** | Defect | Evidence | | -- | -- | | No pointer cursor | Tailwind 4 Preflight no longer sets `cursor: pointer` on buttons. 14 of 19 buttons on `/features` computed to `default`. Anchors were unaffected, which is why it looked inconsistent rather than total. | | The selected toggle offered a pointer | It is a no-op, so the cursor promised an action that does nothing. | | The selected state was invisible in light mode | `bg-surface-300` and `bg-surface-75` both resolve to pure white. Contrast ratio exactly 1.000. The light theme base lightness is `.995` and each surface step adds `.024`, so every lighter step clamps at white. The only cue left was icon colour. | | Hover inverted the selection | Unselected hover is `bg-surface-200`, a 2.7% black overlay, while the selected state was white. Hovering the wrong button made it look selected. | | No grouping | Two unrelated buttons. Nothing conveyed one choice with two options, and the selected view was not programmatically determinable at all. | **Filter rows on /features** A pointer appeared only on the narrow gap between each checkbox and its label: | Element | Computed cursor | | -- | -- | | wrapper `div` | `pointer` | | `label` | `default` | | checkbox | `default` | `cursor-pointer!` sat on the wrapper. A declaration targeting an element always beats an inherited value, so `!important` on the parent changed nothing and both children overrode it. ## Solution **Toggles become a `ToggleGroup`** on both pages, replacing the raw button pairs. * `type="single"` renders `role="group"` with `role="radio"` and `aria-checked` per item. That describes one choice with two options rather than two independent toggles, so a screen reader announces the selection and its position in the set. * Each group gets an `aria-label`, which the existing `ToggleGroup` usage on `/pricing` lacks. * Selected item gets `cursor-default`, unselected gets `cursor-pointer`. * Selected background becomes `bg-surface-400`, a 5.4% overlay that clears the 2.7% unselected hover and removes the inversion. **Filter rows** become wrapping `label` elements with `cursor-pointer` directly on the label, matching `IntegrationsContent.tsx`. The whole row becomes a click target, and `id` values derived from raw product names go away. `toggleVariants` sets the selected background to `bg-surface-300` under both `data-[state=on]:` and `aria-checked:`, and twMerge only dedupes matching prefixes. Both are overridden here so adopting the primitive does not reintroduce the invisible state this PR fixes. The primitive defect is FE-4245. ### Behaviour change The toggle pair is now a single tab stop navigated with arrow keys, rather than two separate tab stops. That is correct for a mutually exclusive group, but it is a change from current behaviour. ### Related, deliberately not here | Work | Where | | -- | -- | | Checkbox primitive pointer cursor | #49408, so the shared-package change is reviewed separately. The checkbox itself still shows an arrow on this branch. | | Naming these toggles, which rely on `title` | FE-4229 | | Base-layer cursor fix across www, Docs and Studio | FE-4228 | | Sharing one component between the two pages | FE-4244 | ## Manual testing 1. Open [/features](https://zone-www-dot-com-git-www-view-toggle-pointer-cursor-supabase.vercel.app/features) in light mode. The selected toggle is visibly darker than the unselected one. 2. Hover the selected toggle. The cursor is an arrow. Hover the unselected one. It is a pointer, and it does not become darker than the selected one. 3. Tab to the toggle pair. It takes one tab stop. Move between options with the arrow keys. 4. Inspect either toggle. It has `role="radio"` with `aria-checked` tracking the selection, and the wrapping group has an `aria-label`. 5. Hover a tag filter row over the label text and over the gap between the checkbox and the text. Both show a pointer. The checkbox itself still shows an arrow here; that is #49408. 6. Click a filter row well away from the checkbox. The filter toggles. 7. Repeat steps 1 to 4 on [/partners/catalog](https://zone-www-dot-com-git-www-view-toggle-pointer-cursor-supabase.vercel.app/partners/catalog). --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-24 09:19:59 -07:00
Miranda LimonczenkoandClaude Opus 5	c79d7be7d9	fix(www): give the feature and partner card grids list semantics (#49411) ... Closes FE-4252 ## Problem `/features` renders 79 feature cards as bare `Link` elements in a grid `div`. Measured on a preview, `main` contains zero `ul`, `ol`, `li`, and zero `role="list"`. `/partners/catalog` is the same. A screen reader user gets a run of loose links with no "list, 79 items", no set size, and no way to navigate by list. Sighted users see an obvious grid of cards, and the structure conveying that is purely visual. Same defect class as FE-4101 and DOCS-1279, both already in this milestone. ## Solution Make each card container a `ul` with one `li` per card. Four containers: | File | Container | | -- | -- | | `apps/www/pages/features.tsx` | feature card grid | | `apps/www/app/partners/catalog/IntegrationsContent.tsx` | featured partners grid | | same | grid view | | same | list view | This change makes a Screenreader announce the number of items and track them. Most of this diff is re-indentation from the added wrapper. ## Manual testing **/features** 1. Open [/features](https://zone-www-dot-com-git-www-card-grid-list-semantics-supabase.vercel.app/features) with Screenreader. Confirm the cards report as a list of 79 items, and that the count tracks the filters. 2. Check the grid at mobile, tablet and desktop widths. Cards stay equal height within a row and the column counts are unchanged. **/partners/catalog** 3. Open [/partners/catalog](https://zone-www-dot-com-git-www-card-grid-list-semantics-supabase.vercel.app/partners/catalog) in grid view with Screenreader. Confirm both the featured section and the main grid are lists. 4. Switch to [list view](https://zone-www-dot-com-git-www-card-grid-list-semantics-supabase.vercel.app/partners/catalog?view=list). Confirm it is a list and the dividing lines between rows are unchanged. Compare any of these against [production](https://supabase.com/features). The rendering should be identical; only the markup changes. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Accessibility** * Improved semantic structure for partner catalog and feature cards using properly organized lists. * Expanded card links to make larger portions of featured and grid cards clickable. * Preserved existing layouts, content, and filtering behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-24 09:19:40 -07:00
Miranda LimonczenkoandClaude Opus 5	3178da7f4d	fix(ui): give enabled checkboxes a pointer cursor (#49408) ... Closes FE-4249 ## Problem The `Checkbox` primitive sets `disabled:cursor-not-allowed` but never sets a base cursor. It renders a Radix `button`, and a UA `button { cursor: default }` rule beats an inherited value from any parent, so an enabled checkbox shows an arrow while being clickable. The `disabled:` variant only makes sense if a base cursor exists. A parent cannot fix this. `/features` tried `cursor-pointer!` on a wrapper `div` with a sibling checkbox and label. Measured: | Element | Computed cursor | | -- | -- | | wrapper `div` | `pointer` | | `label` | `default` | | checkbox `button` | `default` | A declaration targeting an element always beats an inherited value, so `!important` on the parent changed nothing. Only the bare gap between the two children showed a pointer. ## Solution Add the base `cursor-pointer` that the existing `disabled:` variant already implied. Split out of #49346 so this shared-package change gets reviewed on its own. It affects www, Docs and Studio. ## Manual testing **www** 1. Open [/features](https://zone-www-dot-com-git-ui-checkbox-pointer-cursor-supabase.vercel.app/features). 2. Hover any filter checkbox in the left sidebar. The cursor is a pointer. **Studio**, since this is a shared primitive. Needs Vercel SSO and a logged-in account. 3. Open the [Studio preview](https://studio-staging-git-ui-checkbox-pointer-cursor-supabase.vercel.app) and pick any project. 4. Go to Table Editor and click the funnel icon in the left sidebar. 5. Hover the checkboxes in the "Filter entity types" popover. Each shows a pointer. **Disabled state**, which this PR must not change. 6. In devtools, add `disabled` to any checkbox. The cursor becomes `not-allowed`. **Docs has nothing to check.** `apps/docs` contains no `Checkbox` usage. A runtime sweep found zero checkboxes on the troubleshooting page with its Products filter open, and on `/docs`, `/docs/guides/database/overview` and `/docs/guides/auth`. Its [preview](https://docs-git-ui-checkbox-pointer-cursor-supabase.vercel.app/docs) builds only because `packages/ui` is a dependency. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Style** * Updated checkbox controls to display a pointer cursor, making them feel clickable. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-24 09:17:26 -07:00
Miranda LimonczenkoandClaude Opus 5	932180541e	fix(ui-patterns): give the shared InfoTooltip trigger an accessible name (#49345) ... Closes FE-4093 ## Problem The shared `InfoTooltip` trigger's only child is an SVG and it has no accessible name, so a screen reader announces an unnamed button and the information the tooltip carries is unreachable. `button-name`, critical. `/pricing` renders 34 of them. ## Solution * Add an optional `label` prop rendered as `sr-only` text, with a generic fallback so the 22 call sites that pass nothing still get a name. The prop is optional because 26 files import this component across www, Studio, design-system and ui-patterns. * Drop the redundant `role="button"` from a native button. * Label the four www call sites. A shared fallback alone would leave `/pricing` announcing 34 identical names, which passes axe and stays unusable. The labels come from the feature title and plan already in scope, so no pricing data changes. Docs is unaffected. It has its own `InfoTooltip` at `apps/docs/features/ui/InfoTooltip.tsx` and never imports the shared one. ## Manual testing 1. Open [/pricing](https://zone-www-dot-com-git-ui-patterns-infotooltip-ac-07e2ab-supabase.vercel.app/pricing) using a Screenreader. 2. Tab through the comparison table. Each info tooltip announces its own feature, for example "About Database size". 3. Tab to a plan-specific tooltip. It announces the feature and the plan, for example "About Automatic backups on the pro plan". 4. Confirm the icons render unchanged and the tooltips still open on hover and on focus. 5. Run axe on the page. `button-name` reports zero elements. 6. Open the [design system InfoTooltip page](https://design-system-git-ui-patterns-infotooltip-acces-66ec02-supabase.vercel.app/design-system/docs/fragments/info-tooltip) and confirm the demo still renders. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Accessibility Improvements** * Added descriptive labels to pricing information tooltips. * Improved screen reader context for compute estimates, features, and plan-specific pricing. * Added a default “More information” label for unlabeled tooltips. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-24 09:14:12 -07:00
Miranda LimonczenkoandClaude Opus 5	21fccb0ecd	fix(www): name the /features page button controls (#49343) ... Closes FE-4097 https://github.com/user-attachments/assets/bc7cad1a-763e-469f-8a3b-e4d23bed94d9 _See bottom left of screen for screen reader captions._ ## Problem Two controls in the shared `/features/[slug]` template have no accessible name. Both live in the template, so both fire on all 79 feature pages. * The feature list dropdown trigger contains only a `List` icon. `button-name`, critical. * The breadcrumb back chevron wraps only a `ChevronLeft`. `link-name`, serious. ## Solution * Name both with `sr-only` text, matching the sibling prev and next controls in the same component and the theme switcher in the site header. * Label the product pill with its destination. It announced only "vector", with no indication it filters the catalog. Not an axe finding, since the product name already supplies a name. The label keeps the visible word so it satisfies WCAG 2.5.3 Label in Name. * Fix a stray `className="` inside the `iconClassName` string literal, which dropped the icons' width class. * Add `cursor-pointer` to `buttonClassName`. Tailwind 4 no longer sets a pointer cursor on buttons, so the middle control behaved differently from its two anchor siblings. This line belongs to FE-4227 and sits here only to keep two open PRs off adjacent lines of the same file. ## Manual testing 1. Open [/features/ai-integrations](https://zone-www-dot-com-git-www-features-chrome-access-1aef01-supabase.vercel.app/features/ai-integrations) using a Screenreader. 2. Tab through the three round controls at top right. They announce "Previous feature", "Browse all features", "Next feature". **Note:** The order of the elements is strange; captured in a separate ticket. 3. Tab to the round back control at top left. It announces "Back to all features". 4. Tab to the product pill beside it. It announces "All vector features", and the visible word "vector" is unchanged. 5. Hover each of the three round controls. All show a pointer cursor. 6. Run axe on the page. `button-name` and `link-name` report zero elements. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-21 08:48:04 -07:00
Miranda LimonczenkoandClaude Opus 5	61b2a18724	fix(docs): stop rendering empty troubleshooting error-code pills (#49344) ... Closes DOCS-1281 ## Problem Two defects in the "Related error codes" list, both from the page diverging from what `Troubleshooting.utils.ts` already does. * **Empty pills.** `formatError` returns an empty string when an error has neither an HTTP status code nor a code. The page renders the pill anyway, giving a link with no text whose `href` ends in `errorCodes=` with no value. So it is both an unnamed link and a pill filtering on nothing. * **Duplicate pills.** The same formatted code renders once per underlying error object, so one entry shows seven identical "500 unexpected_failure" pills. Measured on production, across the 59 entries that render the section: | | Count | | -- | -- | | Entries with an empty pill | 23 | | Empty pills | 33 | | Entries with duplicate pills | 4 | | Redundant pills | 9 | The guard also evaluated to `0` rather than `false` for an empty array, which React renders as a literal "0". ## Solution * Derive the formatted codes once, drop the empties, and dedupe. An entry whose every code formats empty no longer renders a heading and rule with nothing under them. * Call `formatError` once per code instead of twice per pill, and key on the code now that codes are unique. * Fix the same `0`-rendering guard on the keywords section. `Troubleshooting.utils.ts` already filters on `error?.http_status_code || error?.code` at lines 69 and 150, and already dedupes by formatted code at lines 72 to 79. This brings the page in line with the sidebar and filter list rather than introducing a new pattern. `formatError` itself is unchanged. It also produces grouping and sort keys in `Troubleshooting.utils.ts` and `Troubleshooting.ui.tsx`, so changing its return contract would reach well beyond this fix. ## Manual testing Compare each page against production, which still shows both defects. 1. Open [dashboard-errors-when-managing-users on production](https://supabase.com/docs/guides/troubleshooting/dashboard-errors-when-managing-users-N1ls4A). It shows 8 pills: seven identical "500 unexpected_failure" and one empty. 2. Open [the same page on the preview](https://docs-git-docs-troubleshooting-empty-error-pills-supabase.vercel.app/docs/guides/troubleshooting/dashboard-errors-when-managing-users-N1ls4A). One "500 unexpected_failure" pill remains. 3. Open [prisma-error-management on production](https://supabase.com/docs/guides/troubleshooting/prisma-error-management-Cm5P_o). It shows 6 empty pills. 4. Open [the same page on the preview](https://docs-git-docs-troubleshooting-empty-error-pills-supabase.vercel.app/docs/guides/troubleshooting/prisma-error-management-Cm5P_o). The section is gone, because every code on that entry formats empty. 5. Run axe on either preview page. `link-name` reports zero elements. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Improved troubleshooting displays by formatting and deduplicating error values. * Removed empty or invalid error entries from the rendered results. * Related error-code links now appear only when valid error codes are available. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-21 08:44:28 -07:00
Miranda LimonczenkoandClaude Opus 5	70715790b8	chore(www): unpublish and redirect the legacy launch week pages (#49335) ... Closes [FE-4226](https://linear.app/supabase/issue/FE-4226/unpublish-and-redirect-legacy-launch-week-pages) ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Content removal. ## What is the current behavior? `/launch-week/x`, `/launch-week/12`, `/launch-week/13`, and `/launch-week/14` are still published. Each one carries its own page component and a ticket flow for a launch week that ended. The accessibility scan flags them, and they hold no SEO value. This follows #49281, which took down `/launch-week/6` on the same pattern. ## What is the new behavior? - Delete the `/launch-week/x`, `/12`, `/13`, and `/14` page routes. - Redirect each path to its recap blog post, matching the destinations agreed in `#team-marketing`. - Point the Launch Week 12, 13, and 14 blog summary components at `/launch-week` instead of their deleted pages. `LWXSummary` already does this. - Drop the `disableStickyNav` and `showLaunchWeekNavMode` checks in `Nav` that only matched the deleted routes. - Drop the Launch Week X branches in `useDarkLaunchWeeks` and `_app`. | Source | Destination | | --- | --- | | `/launch-week/x` | `/blog/launch-week-x-best-launches` | | `/launch-week/12` | `/blog/launch-week-12-top-10` | | `/launch-week/13` | `/blog/launch-week-13-top-10` | | `/launch-week/14` | `/blog/launch-week-14-top-10` | ## Additional context `/launch-week/7` and `/launch-week/8` stay published. Neither has a recap post to redirect to, so they need a destination decision before they come down. The `components/LaunchWeek/{X,12,13,14}` trees stay. `BlogPostRenderer` imports the summary component from each one, and those summaries read the same `Releases/data` modules the deleted pages used. The stage and nav components under those directories are now unreachable, so they need their own dead-code audit. Assets under `public/images/launchweek/` are untouched, same as #49281. ## Manual testing Preview: https://zone-www-dot-com-git-www-redirect-legacy-launch-weeks-supabase.vercel.app 1. Open [/launch-week/x](https://zone-www-dot-com-git-www-redirect-legacy-launch-weeks-supabase.vercel.app/launch-week/x). It returns a 308 and lands on `/blog/launch-week-x-best-launches`. 2. Open [/launch-week/12](https://zone-www-dot-com-git-www-redirect-legacy-launch-weeks-supabase.vercel.app/launch-week/12). It returns a 308 and lands on `/blog/launch-week-12-top-10`. 3. Open [/launch-week/13](https://zone-www-dot-com-git-www-redirect-legacy-launch-weeks-supabase.vercel.app/launch-week/13). It returns a 308 and lands on `/blog/launch-week-13-top-10`. 4. Open [/launch-week/14](https://zone-www-dot-com-git-www-redirect-legacy-launch-weeks-supabase.vercel.app/launch-week/14). It returns a 308 and lands on `/blog/launch-week-14-top-10`. 5. On each of those blog posts, the launch week summary card header links to `/launch-week`. 6. Open [/launch-week](https://zone-www-dot-com-git-www-redirect-legacy-launch-weeks-supabase.vercel.app/launch-week), [/launch-week/7](https://zone-www-dot-com-git-www-redirect-legacy-launch-weeks-supabase.vercel.app/launch-week/7), and [/launch-week/8](https://zone-www-dot-com-git-www-redirect-legacy-launch-weeks-supabase.vercel.app/launch-week/8). All still load. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-20 15:33:09 -07:00
Miranda LimonczenkoandClaude Opus 5	ebd399ff87	fix(www): use li instead of ol in launch week summary lists (#49279) ... Closes [FE-4096](https://linear.app/supabase/issue/FE-4096/launch-week-summary-lists-ol-inside-ul-link-where-li-belongs-6-copies) ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Accessibility bug fix. ## What is the current behavior? The launch week summary card renders at the bottom of launch week blog posts. Its two lists are invalid HTML in six copies of the component. - Each entry is an `<ol>` nested directly inside a `<ul>`. Only `<li>` is a valid child of `<ul>`. - The `<Link>` sits inside the `<ol>` rather than inside an `<li>`, so there are no list items at all. Screen readers announce a list of empty items wrapping nested lists instead of a flat list of links. ## What is the new behavior? - Swap every `<ol>` for an `<li>` in the six summary components: LW X, 11, 12, 13, 14, and 15. - Class names and keys carry over unchanged. No visual change. ## Additional context The blog posts stay published. This is a markup fix only. ## Manual testing 1. Open [the Launch Week 15 top 10 post](https://zone-www-dot-com-git-www-fix-lw-summary-lists-supabase.vercel.app/blog/launch-week-15-top-10) on the deploy preview. 2. Scroll to the Launch Week 15 summary card below the article. It shows a Main Stage list and a Build Stage list. 3. Inspect either list. Every direct child of the `<ul>` is an `<li>`, and no `<ol>` appears inside. 4. Repeat on [the Launch Week 12 Wasm FDW post](https://zone-www-dot-com-git-www-fix-lw-summary-lists-supabase.vercel.app/blog/postgres-foreign-data-wrappers-with-wasm) for the Launch Week 12 card. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-20 11:43:51 -07:00
Miranda LimonczenkoandClaude Opus 5	6edef9f067	chore(www): unpublish the Launch Week 6 page (#49281) ... Closes [FE-4100](https://linear.app/supabase/issue/FE-4100/www-remove-httpssupabasecomlaunch-week6) ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Content removal. ## What is the current behavior? `/launch-week/6` is still published. Launch Week 6 ran in December 2022. The page carries its own 1,085-line component, two CSS modules, and a Supabase client that reads the `lw6_creators` and `lw6_tickets` tables. ## What is the new behavior? - Delete the `/launch-week/6` page, its CSS modules, its day data, and its types. - Redirect `/launch-week/6` to `/blog/launch-week-6-wrap-up`, which holds the same content. - Drop the Launch Week 6 card from the archive section on `/launch-week/8`, leaving Launch Week 7. ## Additional context Scope is Launch Week 6 only. Whether the other launch week pages come down is still open with marketing. Assets under `public/images/launchweek/` are untouched. Several are shared across launch weeks, so they need their own audit. ## Manual testing 1. Open [https://zone-www-dot-com-git-www-remove-launchweek-supabase.vercel.app/launch-week/6](https://zone-www-dot-com-git-www-remove-launchweek-supabase.vercel.app/launch-week/6) on the deploy preview. It returns a 308 and lands on `/blog/launch-week-6-wrap-up`. 2. Open [the Launch Week 7 page](https://zone-www-dot-com-git-www-remove-launchweek-supabase.vercel.app/launch-week/7). It still loads. 3. Open [the Launch Week 8 page](https://zone-www-dot-com-git-www-remove-launchweek-supabase.vercel.app/launch-week/8) and scroll to "Previous Launch Weeks". Only the Launch Week 7 card shows. Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-20 11:42:30 -07:00
Miranda LimonczenkoandClaude Opus 5	6368f00ca0	docs(database): restructure the RLS guide by information type (#49017) ... ## Problem The guide alternated between context, procedure, and reference on almost every heading. A reader who wanted to write a policy passed through four context or reference sections to reach one. A reader who wanted the model had to skip three procedures. ## Solution - Group into three sections by information type: `Understand Row Level Security`, `Secure a table with RLS`, and `RLS reference`, with a navigation intro. - Merge the four policy sections. They repeated the same setup block, burying the clause that differed. One setup block now precedes four short policy examples. - Move the auto-enable recipe into `event-triggers.mdx`, whose stub section's entire body was a link back here. - Relocate the stranded `auth.uid()` caution into the `auth.uid()` reference. - Lift the revoke-and-grant procedure out of the danger admonition and merge it with the two other places that taught `enable row level security`. - Point the Grafana IO chart entry at the performance guide. Its `#rls-performance-recommendations` anchor went away when tuning split out in #49016. 765 lines to 582. 30 headings to 25. Headings are demoted rather than renamed wherever anything links to them. Every inbound anchor in the repo still resolves; the only one removed, `#auto-enable-rls-for-new-tables`, was referenced solely by the `event-triggers.mdx` stub this PR replaces. ## Note on the history Rebuilt from `master` after #49011, #49015, and #49016 merged. The branch previously carried those 10 commits plus rebase churn against them. Rebasing naively would have reverted review feedback from #49016 (`70fa812`), which removed the benchmarks table and the "This guide" opener from the performance guide. Those are deliberately not restored here. The only changes to that file are two missing `await`s and a join predicate that was a tautology while unqualified. The three PRs stacked on this one (#49268, #49269, #49270) have been rebased onto the new base. ## Manual testing 1. Open the [Row Level Security guide](https://docs-git-docs-rls-restructure-supabase.vercel.app/docs/guides/database/postgres/row-level-security) on the preview. Three top-level sections appear in the table of contents. 2. Select each link in the intro. All three jump to their section. 3. Open [Event triggers](https://docs-git-docs-rls-restructure-supabase.vercel.app/docs/guides/database/postgres/event-triggers). The auto-enable section holds the full recipe instead of a link. 4. Open the [performance guide](https://docs-git-docs-rls-restructure-supabase.vercel.app/docs/guides/database/postgres/row-level-security-performance). No benchmarks table, and the three bullets at the top link into the RLS guide. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Reworked the Row Level Security guide with clearer guidance on grants, policies, permissions, performance, testing, views, and secure functions. * Added a complete example for automatically enabling RLS on newly created public tables. * Improved SQL examples and clarified table references in RLS performance guidance. * Corrected grammar in the Grafana chart troubleshooting documentation. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-19 14:51:06 -07:00
Miranda LimonczenkoandClaude Opus 5	edf50668aa	docs(database): split RLS tuning into its own guide (#49016) ... Stacked on #49015, which is stacked on #49011. Review those first. ## Problem The Row Level Security guide spent 225 lines and 5 benchmark tables on performance, 29% of the page. The `RLS Performance and Best Practices` troubleshooting entry already covers the same six tips with the same numbers, from the same source. Neither page tells you how to check whether RLS is your bottleneck in the first place. Four of the six tips are not tuning advice. Indexes, `select`-wrapping, role scoping, and `security definer` safety change whether a policy is correct and safe, not just fast. ## Solution - Add `guides/database/postgres/row-level-security-performance`. It carries the client-filter rule, the join-rewrite rule, all 5 benchmark tables merged into one, and a new `Diagnose whether RLS is the bottleneck` section: toggle RLS off to confirm it's the cost, then read the plan under an impersonated role. That diagnostic exists in the troubleshooting entry and has never been in the guide. - Keep every rule that affects correctness on the RLS guide, grouped under `Write policies that scale`. These are also the four the `build-docs-002-rls-guide` eval grades, and an agent reads the guide top-down. - Repoint the Grafana IO troubleshooting entry at the new page. - Rewrite `More resources` as `Related content`. Every link now says what it is and when to use it. Adds `Advanced pgTAP testing`, the deepest RLS testing content in the docs, which nothing here linked. Drops discussion 14576: locked, mislabeled here as "RLS Guide and Best Practices" when it is "RLS **Performance** and Best Practices", and superseded by the troubleshooting entry and this new page. **Ownership rule** so the two pages don't drift: the RLS guide owns the rule and the correct form. The performance page owns the measurement and the optimizer explanation. If a sentence on the performance page tells you what to write, it belongs on the guide. Scoped out of this PR: `More resources` was assigned to the restructure PR in the plan, but the 14576 link is what this PR supersedes, so leaving it would ship a stale pointer. ## Manual testing 1. Open the [RLS performance guide](https://docs-git-docs-rls-performance-split-supabase.vercel.app/docs/guides/database/postgres/row-level-security-performance) on the preview. It appears in the left nav under Database, Access and security, directly below Row Level Security. 2. Select the three rule links in its intro. Each lands on the matching section of the RLS guide. 3. Open the [Row Level Security guide](https://docs-git-docs-rls-performance-split-supabase.vercel.app/docs/guides/database/postgres/row-level-security) and go to `Write policies that scale`. It holds indexes, `select`-wrapping, and role scoping, with one link out to the performance page. 4. Open the [Grafana IO troubleshooting entry](https://docs-git-docs-rls-performance-split-supabase.vercel.app/docs/guides/troubleshooting/interpreting-supabase-grafana-io-charts-MUynDR) and select the RLS performance guide link. It lands on the new page. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Added a dedicated guide for diagnosing and improving PostgreSQL Row Level Security performance. * Expanded guidance on indexing, query filters, role targeting, function usage, and avoiding costly policy joins. * Updated the Row Level Security guide with streamlined, scalable policy recommendations and links to related resources. * Added the new performance guide to the Database documentation navigation. * Updated troubleshooting guidance to reference the dedicated performance guide. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-19 10:41:08 -07:00
3 people	bb094f96c8	docs(mcp): revise authentication note to match style guide (#49219) ... <img width="769" height="212" alt="Screenshot 2026-08-18 at 12 17 18 PM" src="https://github.com/user-attachments/assets/38ce6606-84ae-4833-a7d9-7a1931fdd773" /> ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Docs update. Copy and dedupe. ## What is the current behavior? Gave this a style edit. Basically, saw this note breaking a lot of style rules at once (`login` instead of `log in`, future tense, and also breaking timelessness) and couldn't help myself for submitting a revision. 😅 ## What is the new behavior? Preview: https://docs-git-cursor-revise-mcp-auth-note-bbe8-supabase.vercel.app/docs/guides/ai-tools/mcp --------- Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: Miranda Limonczenko <czenko@users.noreply.github.com>	2026-08-19 08:56:09 -07:00
Miranda LimonczenkoandCursor	8c745017fb	chore(a11y): have CodeRabbit flag live regions, keyboard, motion, and alt text (#49216) ... Closes FE-3811 ## Problem CodeRabbit reviews UI PRs without prompting on accessibility gaps axe-core cannot judge: live regions, keyboard and hover, reduced motion, alt quality, focus visibility, color-only state, and vague link names. ## Solution - Add a path_instruction on `{apps,packages}/**/*.{tsx,jsx,css,mdx}`. - Keep comments advisory. Skip tests, generated files, Radix/shadcn from `ui`, and mechanical axe findings. - Cover live-region lifecycle, pointer-only and hover-only UI, reduced motion, alt quality including a two-sentence length heuristic, focus rings, color-only state, and generic link names. ## Manual testing 1. After merge, open a PR that touches a UI or MDX file under `apps/` or `packages/`. 2. Confirm CodeRabbit comments on at least one of: an unannounced status change, a live region created with its message, a pointer-only or hover-only control, animation without reduced motion, generic or redundant or long alt, `outline-none` without a focus-visible replacement, color-only status, or a "learn more" link that does not name its destination. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Accessibility** * Expanded accessibility review coverage for interface content and styling. * Reviews now identify missing focus indicators, color-only status or selection cues, and unclear link labels. * Continued checks cover state announcements, pointer-only interactions, reduced-motion support, and alternative text quality. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-19 07:29:37 -07:00
3 people	45bb7c30ce	docs(database): fix RLS guide copy and two SQL examples (#49015) ... Stacked on #49011. Base is `docs/rls-revision`, so review that one first. ## Problem An audit of the Row Level Security guide against `apps/docs/CONTRIBUTING.md` and `WORD_LIST.md` turned up 4 lint warnings and 3 things that are wrong rather than just untidy. - Two SQL examples contradict the guide's own advice. The own-profile `SELECT` policy has no `TO` clause. The `security definer` example has no `set search_path`. - `## Bypassing Row Level Security` says Service Keys bypass RLS, then a note says Supabase adheres to the signed-in user's policy anyway. The condition that separates the two is never stated. - `#using-functions` is linked twice from the RBAC guide and has never existed on the RLS page. ## Solution Copy and correctness only. No section moves, no heading renames. - Replace the italic emphasis on `never` with bold. CONTRIBUTING permits **bold** for a term the reader must not miss, not italics for general emphasis. The matching fix for `must` lives in #49011, which rewrites that line anyway. - Drop marketing language from the opener, the Supabase intro, and the policies and performance leads. Removes the idiom "get the hang of them" and the filler `just`. - Replace `we` with second person in two places. - Scope the own-profile `SELECT` example with `to authenticated`. - Pin `search_path = ''` on the `security definer` example, schema-qualify its body to match, and state the requirement in prose. - State when a Service Key actually bypasses RLS. - Repoint the two RBAC links to `#use-security-definer-functions` and `#helper-functions`. `supa-mdx-lint` on the RLS guide goes from 4 warnings to 0. ## Manual testing 1. Open the [Row Level Security guide](https://docs-git-docs-rls-copy-fixes-supabase.vercel.app/docs/guides/database/postgres/row-level-security) on the preview. The own-profile SELECT example shows `to authenticated`, and the security definer example shows `set search_path = ''`. 2. Open the [RBAC guide](https://docs-git-docs-rls-copy-fixes-supabase.vercel.app/docs/guides/api/custom-claims-and-role-based-access-control-rbac) and select the "RLS helper functions" link near the end. It lands on the Helper functions section instead of the top of the page. 3. From `apps/docs`, run `pnpm lint:mdx`. The RLS guide reports no warnings. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Updated access-control guidance with clearer links for security-definer functions and RLS helper functions. - Clarified that exposed tables require Row Level Security (RLS), while table grants and row policies provide separate controls. - Added least-privilege and grant-revocation examples, plus explanations for authorization errors. - Expanded testing guidance for CRUD policies, identity switching, and denied operations. - Improved recommendations for service keys, policy performance, indexing, and secure function configuration. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> Co-authored-by: Cursor <cursoragent@cursor.com>	2026-08-17 23:40:09 +00:00
Miranda LimonczenkoandClaude Opus 5	d2ccbe5d46	docs(database): close the RLS guide gaps the eval flagged (#49011) ... Closes DOCS-1274 ## Problem The `build-docs-002-rls-guide` eval points an agent at the Row Level Security guide with a vibe-coder prompt that never says RLS, policy, role, or test. It failed 6 of 35 checks. Each failure traces to something the guide doesn't say. - **Grants.** `anon` kept insert, update, and delete on all four to-do tables. Both client roles kept writes on the weather feed. 24 privileges untouched. - **Indexes.** Missing on `list_members.user_id`. The agent indexed the other three, so it missed the composite-primary-key case specifically. - **Tests.** No pgTAP files. `Result: NOTESTS`, so the coverage judge never ran. ## Solution - **Add a `Grants and policies` section.** - **Rewrite the opening danger admonition around revoke-then-grant.** It previously showed `grant` only, which reads as though privileges start from nothing. - **Drop the `(or primary keys)` carve-out from `Add indexes`.** A column counts as indexed only when it leads a `btree` index, shown with a composite-primary-key example. - **Add a `Test your policies` section.** Covers file location under `supabase/tests/`, `supabase test db`, role and identity switching, which assertion matches which denial, and an 11-assertion example spanning allow and deny for all four operations across `anon` and `authenticated`. Used the supacademy RLS course as a second reference. Its framing of grants running before RLS shaped the new section. ## Manual testing 1. Open the [Row Level Security guide](https://docs-git-docs-rls-revision-supabase.vercel.app/docs/guides/database/postgres/row-level-security) on the preview. `Grants and policies` and `Test your policies` appear in the table of contents. 2. Select the `Grants and policies` link at the end of the first admonition. It jumps to the new section. 3. Open the [markdown version](https://docs-git-docs-rls-revision-supabase.vercel.app/docs/guides/database/postgres/row-level-security.md), which is what agents fetch. Both new sections and the revised `Add indexes` text are present. 4. From `apps/docs`, run `pnpm lint:mdx`. The 4 warnings on this file match `master`, with no new ones. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Documentation * Clarified that exposed tables must enable row-level security. * Explained the distinction between database grants and row-level security policies. * Added least-privilege examples for client roles, including read-only access. * Added pgTAP testing guidance with a complete `profiles` example. * Clarified that composite indexes support policy filters only on their leading columns. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-17 15:05:39 -07:00
Miranda Limonczenko	de39dda387	docs: replace Pico references with Nano in Supabase for Platforms content (#48958)	2026-08-12 11:55:17 -06:00
Miranda LimonczenkoandClaude Opus 5	f10f00ae69	fix(e2e): install e2e-shared when CI filters to a single suite (#48960) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Bug fix. Unblocks the WWW E2E check on `master`. ## What is the current behavior? The WWW E2E job fails before running any test: ``` Error: Cannot find package '@axe-core/playwright' imported from /home/runner/_work/supabase/supabase/e2e/shared/axe.ts Error: No tests found ``` Both E2E workflows install with a filter: ``` pnpm install --frozen-lockfile --filter=e2e-www... ``` The `...` suffix pulls in a package's declared dependencies. Neither `e2e-www` nor `e2e-docs` declared `e2e-shared`; both reach it through relative imports such as `../../shared/axe.ts`, which pnpm's dependency graph cannot see. So the filter selected one project, `e2e/shared/node_modules` was never created, and Node resolving `@axe-core/playwright` from `e2e/shared/axe.ts` walked up to a root that does not carry it under pnpm's isolated layout. `e2e-docs` is broken the same way. It had not run against the shared module yet, so it has not gone red. ## What is the new behavior? `e2e-shared` is declared as a workspace dependency of both suites, so the filter installs it. | | Filter scope | Importing `e2e/shared/axe.ts` | | --- | --- | --- | | Before | 1 of 28 projects | `Cannot find package '@axe-core/playwright'` | | After | 2 of 28 projects | Imports cleanly | The lockfile gains two `link:../shared` entries and no new downloads. ## Manual Testing 1. Check out this branch and delete the shared package's modules: `rm -rf e2e/shared/node_modules` 2. Run the command CI runs: `pnpm install --frozen-lockfile --filter=e2e-www...` 3. Confirm the output reports `Scope: 2 of 28 workspace projects` and that `e2e/shared/node_modules` exists again. 4. Repeat steps 1 - 3 with `--filter=e2e-docs...`. ## Additional context Fixing only the workflow lines, by adding a second `--filter=e2e-shared`, would work as well. Declaring the dependency was chosen instead because the dependency is real and every consumer of the filter gets it, not just the two workflow files. The imports stay relative. Declaring the workspace dependency is enough to get the package installed, so no import paths change in this PR. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Chores** * Updated end-to-end test packages to use shared testing utilities at runtime. * Improved consistency between documentation and website test suites. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-11 16:17:29 -07:00
Miranda LimonczenkoandClaude Opus 5	6d3a4bcc48	feat(www) Add scaffolding for WWW E2E tests and CI check (#48861) ... Closes DOCS-1278 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Feature. Adds E2E test scaffolding and a CI check for the marketing site. ## What is the current behavior? Closes [FE-4047](https://linear.app/supabase/issue/FE-4047). The marketing site has no E2E coverage. Docs has a suite in `e2e/docs`, but its runner, git helpers and axe reporting are private to that package, so a second site cannot reuse them. ## What is the new behavior? * **A www suite scoped to changed content.** Changed `.mdx` files in `_blog`, `_events`, `_customers` and `_alternatives` map to the URLs they render. Pages with `disable_page_build: true` are skipped because they 404 by design. Capped at 20 pages. Enforces `heading-order` and `page-has-heading-one`, matching docs. * **`e2e/shared` The docs site is also static with similar needs. This folder shares the docs logic with www. * **A CI check that is safe to mark required.** Path scoping lives in a `Detect changed paths` step rather than a `paths:` trigger, so the check reports on every pull request instead of being skipped. `waitForVercelDocsPreview.js` becomes `waitForVercelPreview.js`, shared by both workflows. ## How the check behaves The job always reports a check run, so it is safe to mark required. Path scoping happens in a step rather than a `paths:` trigger, which would leave non-www pull requests waiting on a check that never reports. | Case | Behavior | | --- | --- | | Fork pull request adds new pages | Passes without testing. The Vercel wait is gated on `head.repo.full_name == github.repository`, so forks resolve no preview URL. The job emits a `::warning` and a job summary containing a ready-to-run `gh workflow run www-e2e.yml` command with the resolved page paths, so a maintainer can run it against the preview. | | Vercel preview times out or fails | Passes without testing. The wait step is `continue-on-error: true`, so a 900s timeout or a failed deployment leaves the URL unset and the suite skips. Vercel's own `Vercel – zone-www-dot-com` check already reports the failure. | | Draft pull request | Job does not run at all, gated at the job level on `pull_request.draft == false`. `ready_for_review` is in the trigger's `types`, so marking it ready runs the check. | | Another app changed, www untouched | Job runs and every step skips. The `www` filter matches only the four content directories, `e2e/www`, `e2e/shared`, the lockfile, and this workflow. | | Only the harness changed | Passes without testing. Scope resolves to zero pages, and the Vercel wait is additionally gated on `www_app`, so it does not wait for a preview Vercel skipped. | | No preview resolves, any reason | Skips rather than falling back to production. Production does not serve pages the pull request adds, so testing it would fail a valid change. | ### Not covered Changes to `apps/www` components and routes do not trigger this check — only the four content directories do. A follow-up can check global components such as the navigation and the footer. ## Manual testing 1. Start the site: `pnpm dev:www` 2. Run `pnpm e2e:www` with no www content changed. It should resolve zero pages and skip Playwright, not fail. 3. Touch a post, then run `pnpm e2e:www` again: `echo "" >> apps/www/_blog/2024-01-01-some-post.mdx`. The resolved `/blog/...` path should be listed before Playwright starts. 4. Run against production with no local server: `PLAYWRIGHT_BASE_URL=https://supabase.com WWW_E2E_PAGE_PATHS=/blog/postgres-language-server pnpm e2e:www` 5. Point step 4 at a page with a known heading problem. The failure should name the rule, the CSS selector and the markup. 6. Confirm docs still passes on the shared runner: `pnpm dev:docs`, then `pnpm e2e:docs` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added WWW end-to-end testing for affected content pages, including accessibility checks. * Added standard and full-site test commands, configurable preview testing, and failure reports. * Added shared utilities for page discovery, accessibility scanning, and test execution. * **Documentation** * Documented WWW test setup, coverage, debugging, CI behavior, and running checks against production or preview environments. * **Improvements** * Updated documentation test workflows to better identify affected changes and handle preview environments. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-11 22:06:51 +00:00
Miranda LimonczenkoandClaude Opus 5	777c02c205	test(docs): scan changed pages for WCAG 2.1 A/AA in warn mode (#48727) ... Closes DOCS-1233 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Test coverage. The docs accessibility check now covers the full WCAG 2.1 A/AA rule set instead of two rules. **Note:** This PR tests _only_ the main article of changed pages (meaning, the content itself). A follow-up Linear issue is to address scanning the pieces outside of that: header, navigation, and interactive elements. ## What is the current behavior? The `@a11y` test in `e2e/docs` runs two axe rules against each in-scope page, `heading-order` and `page-has-heading-one`. Both already pass everywhere, so the check only guards a result we have. Nothing else in WCAG A/AA is checked. ## What is the new behavior? The same test runs the full WCAG 2.1 A/AA rule set. - **Existing debt does not block PRs.** Only the two heading rules fail. Everything else reports. - **The check stays fast.** It scans the article only and skips nine rules that cannot fire there. Scan time drops from 2405ms to 981ms. - **Findings belong to us.** Legacy mode excludes cross-origin frames. YouTube embeds were counting against us, 11 of 15 violations on one page. - **A pass carries meaning.** A 404 reports as a load failure, not an a11y bug. A page scanned before it hydrates warns instead of quietly reporting clean. ## How the findings appear The test is named `has no blocking accessibility violations`, so a failure listed by CI is always something to fix. It is not named for the full rule set, because a green check would then claim more than the check verifies. | | Rules | Where you see it | | --- | --- | --- | | Blocking | `heading-order`, `page-has-heading-one` | Test failure, so the runner reports it on the PR | | Reported | Everything else in WCAG A/AA | `::warning` annotation on the run | An annotation looks like this, on a run that still passes: ``` ::warning title=Accessibility::/docs/guides/database/functions has 1 non-blocking accessibility finding(s): frame-title (4) ``` The full axe result for each page is attached to the report as `axe-results.json`. ## Matching the Studio ratchet This follows the ESLint ratchet in `apps/studio`. That pattern warns on pre-existing debt rather than blocking on it, surfaces findings as annotations rather than PR comments, and promotes a rule to an error once its violations reach zero. The mechanism here is `ENFORCED_RULES` in `utils/axe-helpers.ts`. The two heading rules are on it because the heading-hierarchy work drove them to zero site-wide. The intent is to migrate rules into that list one at a time. Pick a rule, fix its violations, then move it into `ENFORCED_RULES` so it cannot come back. An exhaustive scan of the site groups the current backlog by root cause to sequence that work, and two fixes cover 99.1% of it. Studio keeps per-file baseline counts, which this does not. A whole-rule list is coarser, and it works here because docs violations reach zero across the site rather than per file. ## Manual testing Install the browser once, then run each step from the repo root. Every command scans production, so you do not need a local docs server. ```bash pnpm -C e2e/docs exec playwright install chromium ``` 1. Confirm a reported finding does not fail the check. ```bash DOCS_E2E_PAGE_PATHS=/docs/guides/database/functions PLAYWRIGHT_BASE_URL=https://supabase.com pnpm e2e:docs:a11y ``` Expect `1 passed`, and the `::warning` annotation above in the output. 2. Confirm the scan finds that violation. Same page, now failing on every rule. ```bash A11Y_ENFORCE_ALL=1 DOCS_E2E_PAGE_PATHS=/docs/guides/database/functions PLAYWRIGHT_BASE_URL=https://supabase.com pnpm e2e:docs:a11y ``` Expect `1 failed`, reporting `frame-title (serious, 4 node(s))`. Steps 1 and 2 together are the point of this PR. 3. Confirm the skipped rules stay skipped. ```bash A11Y_ENFORCE_ALL=1 DOCS_E2E_PAGE_PATHS=/docs/guides/getting-started/quickstarts/nextjs PLAYWRIGHT_BASE_URL=https://supabase.com pnpm e2e:docs:a11y ``` Expect `button-name (critical, 2 node(s))` and `label (critical, 2 node(s))`, and no `color-contrast`. 4. Confirm a page that does not load reports a load failure. ```bash DOCS_E2E_PAGE_PATHS=/docs/guides/does-not-exist-xyz PLAYWRIGHT_BASE_URL=https://supabase.com pnpm e2e:docs:a11y ``` Expect `Expected a successful response for /docs/guides/does-not-exist-xyz, got 404`, and no axe assertion. 5. Confirm the link checker still passes alongside the a11y test. ```bash DOCS_E2E_PAGE_PATHS=/docs/guides/auth/passwords PLAYWRIGHT_BASE_URL=https://supabase.com pnpm e2e:docs ``` Expect `3 passed`. ## Known gaps - `/docs/reference/*` is not scanned. Those routes render client-side into tens of thousands of elements, where axe exceeds its timeout and results depend on whether the scan caught the page mid-render. - Shared chrome is outside the article scope, so nav, sidebar, footer, menus, and drawers are not covered. - axe catches roughly 30-40% of WCAG issues. Keyboard navigation, focus management, and screen reader behavior still need manual testing. --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-07 10:41:23 -07:00
Miranda LimonczenkoandClaude Opus 5	d45e0cd3d5	fix(docs ci): stop Docs E2E blocking pull requests it shouldn't (#48726) ... Supersedes #48725, which GitHub closed when its head branch was renamed. Same commits, same diff. Fixes [DOCS-1270](https://linear.app/supabase/issue/DOCS-1270/fail-the-e2e-pipeline-if-the-docs-preview-never-loads). `Docs E2E` is a required check on `master`, so anything that turns it red blocks a merge. It had three ways of going red that had nothing to do with whether the author's docs were correct. ## Problem **1. Every troubleshooting page could fail, with nothing actionable.** Troubleshooting entries were selected by `article.prose`. That class is not unique — `apps/docs/app/not-found.tsx` renders `<article className="prose …">` too — and nothing guaranteed it matched the entry's article at all. When it missed, the link test failed with `Page article should be present` and the a11y test failed inside axe with `No elements found for include in page Context` plus a stack trace. Neither tells the author what to do. This is what DOCS-1270 actually was. The ticket describes tests running "against a preview build that was never created", but the [failing run](https://github.com/supabase/supabase/actions/runs/30949924515/job/92132543658) for #48719 shows the preview resolved fine and `response.ok()` passed — it broke at the article assertion. **Blocked:** anyone adding or editing a troubleshooting entry. **2. Fork pull requests failed for being forks.** Fork runs get no `VERCEL_TOKEN`, so no preview URL resolves, and the base-URL step fell back to `https://supabase.com`. The page paths under test can include pages the pull request *adds*, which do not exist on production, so they 404. **Blocked:** every external contributor adding a docs page, unconditionally, with no action available to them. **3. A Vercel problem failed the docs check.** `waitForVercelDocsPreview.js` throws when Vercel reports a failed deployment, omits a `target_url`, or does not post a status within 900s. The step had no `continue-on-error`, so any of those turned `Docs E2E` red. **Blocked:** any author whose pull request coincided with a Vercel incident. This is live right now — two Vercel checks on this very pull request are failing with "unable to fetch required git information", a git-integration auth error that happens before any build runs. ## Solution **1. Select on a stable, purpose-named attribute.** Add `id="sb-docs-troubleshooting-main-article"` on the troubleshooting article, mirroring `#sb-docs-guide-main-article` on guides, and select on that instead of the class. Per review feedback, a plain id doesn't say it's a test hook, so both articles also get `data-testid` with the same value — matching the convention `apps/studio` already uses with Playwright's `getByTestId` — and the e2e selectors target that attribute instead. Guides keep their `id` — `GuidesMdx.client.tsx` and `GuidesSidebar.tsx` both query it directly for the table of contents and the "copy article" fallback — and gain `data-testid` alongside it. **2 and 3. Resolve a preview or skip — never substitute production, never fail on Vercel.** The production fallback is gone. `continue-on-error: true` on the preview wait means a Vercel failure resolves no URL instead of failing the job, which lands in the same path as a fork: `should_test=false`, so Playwright is skipped and the check passes. Both cases emit a `::warning::` and a job summary with the exact `gh workflow run` command to test the preview by hand, and manual runs against a non-production base URL now send the protection bypass so that command actually works. Skipping does not let a broken preview through: `Vercel – docs` is itself a required check on `master`, so a genuine preview failure still blocks the merge — via the check that describes the real problem. ## Manual test **1. The selector matches the markup, and it needs this pull request's preview.** `data-testid` isn't deployed anywhere yet — not on production, not on any other branch — so this is the one claim in this PR that production cannot confirm. Verified directly against this branch's own Vercel preview: ```bash curl -s https://docs-git-docs-e2e-stop-false-blocks-supabase.vercel.app/docs/guides/database/overview \ | grep -o 'data-testid="[^"]*"' curl -s https://docs-git-docs-e2e-stop-false-blocks-supabase.vercel.app/docs/guides/troubleshooting/42501--permission-denied-for-table-httprequestqueue-KnozmQ \ | grep -o 'data-testid="[^"]*"' ``` Expect `data-testid="sb-docs-guide-main-article"` and `data-testid="sb-docs-troubleshooting-main-article"` respectively. Then run the suite against that same preview — expect all page/link/a11y checks to pass: ```bash PLAYWRIGHT_BASE_URL=https://docs-git-docs-e2e-stop-false-blocks-supabase.vercel.app \ DOCS_E2E_PAGE_PATHS=/docs/guides/database/overview,/docs/guides/troubleshooting/42501--permission-denied-for-table-httprequestqueue-KnozmQ \ pnpm -C e2e/docs exec playwright test --reporter=list ``` Running the same command with `PLAYWRIGHT_BASE_URL=https://supabase.com` fails both pages right now — expected until this merges, not a regression. Once merged, exercise it through the real pipeline: ```bash gh workflow run docs-e2e.yml --ref docs-e2e/stop-false-blocks \ -f base_url=<preview-url> \ -f page_paths=/docs/guides/troubleshooting/42501--permission-denied-for-table-httprequestqueue-KnozmQ ``` **2. No preview means skip, not a run against production.** Exercise the base-URL step's three paths from the repository root: ```bash export GITHUB_OUTPUT=$(mktemp) GITHUB_STEP_SUMMARY=$(mktemp) PAGE_PATHS=/docs/guides/a script=$(python3 -c "import yaml;print([s for s in yaml.safe_load(open('.github/workflows/docs-e2e.yml'))['jobs']['e2e']['steps'] if s.get('name')=='Resolve base URL'][0]['run'])") for c in "workflow_dispatch|https://supabase.com|" "pull_request||https://docs-abc.vercel.app" "pull_request||"; do IFS='|' read -r ev url dep <<< "$c" : > "$GITHUB_OUTPUT" EVENT_NAME="$ev" BASE_URL_INPUT="${url:-https://supabase.com}" DEPLOYMENT_URL="$dep" bash -c "$script" >/dev/null 2>&1 echo "$ev deployment=[${dep:-none}] -> $(tr '\n' ' ' < "$GITHUB_OUTPUT")" done tail -4 "$GITHUB_STEP_SUMMARY" ``` Expected: ``` workflow_dispatch deployment=[none] -> url=https://supabase.com use_bypass=false should_test=true pull_request deployment=[https://docs-abc.vercel.app] -> url=https://docs-abc.vercel.app use_bypass=true should_test=true pull_request deployment=[none] -> url= use_bypass=false should_test=false ``` followed by a runnable `gh workflow run docs-e2e.yml` command in the job summary. The third line covers both the fork case and the Vercel-failure case: no base URL, no test, no block. **3. A Vercel failure no longer fails the job.** `continue-on-error: true` on the wait step is what routes a throw into that third line: ```bash python3 -c " import yaml s=[x for x in yaml.safe_load(open('.github/workflows/docs-e2e.yml'))['jobs']['e2e']['steps'] if x.get('name')=='Wait for Vercel docs preview'][0] print('continue-on-error:', s.get('continue-on-error')) for n in ('Install dependencies','Install Playwright Chromium','Run docs E2E'): print(n, '->', [x for x in yaml.safe_load(open('.github/workflows/docs-e2e.yml'))['jobs']['e2e']['steps'] if x.get('name')==n][0]['if']) " ``` Expect `continue-on-error: True` and all three run steps gated on `steps.base-url.outputs.should_test == 'true'`. **Note on this pull request's own check.** The scope resolver only maps `apps/docs/content/**` to pages, and this pull request changes none, so `Docs E2E` resolves zero pages and skips — which is correct, and why the dispatch above is the real test. 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Improved documentation preview checks so unavailable or delayed previews no longer cause unnecessary workflow failures. * Added clearer handling for manual documentation checks and missing preview deployments. * **Tests** * Improved end-to-end documentation testing reliability across preview and production environments. * Added stable targeting for the troubleshooting article to reduce test failures caused by page structure changes. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com>	2026-08-05 15:23:26 +00:00
Miranda LimonczenkoandClaude Sonnet 5	e7d9c88cbc	fix(docs): resolve remaining heading-order issues found in Pass 2 diagnostic (#48664) ... ## Problem After merging [#48456](https://github.com/supabase/supabase/pull/48456) (shared components) and [#48459](https://github.com/supabase/supabase/pull/48459) (per-page content fixes), a follow-up diagnostic pass found 22 remaining heading-order violations, logged as Pass 2 in the [triage report](https://app.notion.com/p/supabase/Playwright-E2E-Triage-Reports-3ab5004b775f81e3bc60d058fa5a02c1). None of them were caught by the earlier fixes because they came from places that scan didn't check: shared partials, raw HTML heading tags written directly in MDX, and a couple of shared/interactive components rendering hardcoded heading levels. ## Solution - `_partials/social_provider_setup.mdx`: `#### Local development` → `###`, matching the `##` that always precedes it on all 14 social-login pages. - `guides/database/functions.mdx` and `guides/integrations/vercel-marketplace.mdx`: replaced raw `<h4>`/`<h5>` tags with correctly-nested real headings (`### Planets`/`### People`; `#### Deploy a Next.js app...`) — no styling workarounds needed since they nest naturally one level below their parent section. - `auth/quickstarts/{nextjs,react-native,react,astrojs}.mdx`: these 4 pages had no heading at all before the embedded `_partials/api_settings.mdx` partial's own `### Get API details` heading, so added a `## Quickstart` heading above the walkthrough to give it a valid parent. - `packages/ui`'s `Accordion` component: Radix's `AccordionPrimitive.Header` renders as an unconditional `<h3>` regardless of where the accordion is used. That's shared across Studio, www, and design-system, not just docs, and surfaced on docs' vendor-agnostic telemetry page. Now rendered via `asChild` onto a plain `div` instead, since a generic accordion has no way to know what heading level (if any) is valid in a given page. - SQL-to-REST translator tool (`/docs/guides/api/sql-to-rest`): its `Assumptions`/`FAQs` section labels were hardcoded `<h3>` with no `h2` anywhere on the page. Converted to styled spans rather than promoting to a real `<h2>`, because real h1/h2/h3 tags in this codebase force a prose font-size that utility classes can't override — promoting the tag would have visibly changed its size. - `RealtimeLimitsEstimator` (embedded on both `postgres-changes` and `benchmarks`): its 3 section headings were hardcoded `<h4>`, but the two embedding pages need different levels (h3 vs h4) for that spot to be valid — no single correct heading level. Converted to styled spans, same pattern used throughout this project for components embedded at varying heading depths. ## Manual testing 1. Check out this branch and run `pnpm dev:docs`. 2. Visit `/docs/guides/auth/social-login/auth-github` (or any other provider page) and confirm the "Local development" callout under "Find your callback URL" still looks and reads the same. 3. Visit `/docs/guides/database/functions` → "Returning data sets" tab and confirm the "Planets" / "People" table captions still look the same. 4. Visit `/docs/guides/integrations/vercel-marketplace` → "Quickstart" → "Via template" and confirm the CTA card title still looks the same. 5. Visit `/docs/guides/auth/quickstarts/nextjs` (or react-native/react/astrojs) and confirm a "Quickstart" heading now appears above the walkthrough, and "Get API details" still renders correctly further down. 6. Run `pnpm dev:design-system` and open `/design-system/docs/components/accordion` — expand/collapse an item and confirm it still animates and looks identical; inspect the DOM and confirm the trigger's wrapper is a `div`, not an `h3`. 7. Visit `/docs/guides/api/sql-to-rest`, translate any query, and confirm the "Assumptions"/"FAQs" section labels still look the same. 8. Visit `/docs/guides/realtime/postgres-changes` and `/docs/guides/realtime/benchmarks`, scroll to the connection-limits calculator, and confirm its section labels still look the same on both pages. 9. (Optional, for a full re-check) Run `pnpm e2e:docs:a11y --all` against a deployed preview of this branch — only `/docs/guides/cli` (pre-existing 404, unrelated to headings) should fail; every other page should pass. Verified with a full Playwright run against a real preview deployment: **756 passed, 1 failed** (`/docs/guides/cli`, the pre-existing unrelated 404). Zero heading-order violations remain. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit - **Documentation** - Added clearly labeled Quickstart sections to Astro, Next.js, React Native, and React authentication guides. - Improved heading hierarchy and formatting across social provider setup, database functions, and deployment documentation. - Updated estimator and SQL-to-REST section presentation for more consistent content structure. - **Bug Fixes** - Improved accordion trigger layout while preserving existing behavior, styling, accessibility, and icon display. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>	2026-08-04 09:00:29 -07:00
Miranda LimonczenkoandClaude Sonnet 5	8dda0c3910	Add heading-hierarchy a11y check to docs E2E tests (#48422) ... Closes DOCS-1232 ## Problem We do not have any tests to verify that we are following a proper heading hierarchy. For a documentation site that deals in mostly static content, this test is important. Single h1 + logical heading hierarchy (h1→h2→h3, no skips) matters because screen reader users navigate by jumping between headings — broken structure breaks that navigation. Relevant: WCAG 1.3.1 Info and Relationships (Level A) — https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html ## Solution Add Playwright axe-core, which we plan to expand later, to test only the h1 and header-hierarchy rule. This is added to our current suite that dynamically checks only pages that are edited. ## Manual testing 1. Find a docs guide and intentionally break the header hierarchy. 2. Run `pnpm e2e:docs:a11y` and see your errors. 3. Resolve the issue and run again to see errors resolved. Ensure there is at least a line changed to see the page tested. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Tests** * Added automated accessibility checks for documentation pages. * Verified heading order and the presence of a level-one heading on each page. * Added a dedicated command to run documentation accessibility tests. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-31 12:31:39 -07:00
Miranda LimonczenkoandClaude Sonnet 5	320111b06b	fix(docs): replace hardcoded heading tags in 4 shared components (#48456) ... Closes DOCS-1261 _WAVE plugin shows headers creating jumps in hierarchy. Preview on the left:_ <img width="1022" height="417" alt="Screenshot 2026-07-29 at 2 42 07 PM" src="https://github.com/user-attachments/assets/f5e3bd09-8dbf-45e3-8a7f-70d7334fd25b" /> <img width="408" height="663" alt="Screenshot 2026-07-29 at 2 44 33 PM" src="https://github.com/user-attachments/assets/6b952a81-40e5-4a9d-b08a-190c71575cac" /> ## Problem Four shared components in `apps/docs` render a hardcoded heading tag no matter where they're used: - `NamedCodeBlock` renders a code block's filename as an `<h6>` - `ProjectConfigVariables` renders a variable label as an `<h6>` - `StepHikeCompact.Details` renders a step title as an `<h3>` - `IconPanel` renders its title as an `<h5>` Since these are fixed, they often land in the wrong spot in a page's heading order (like an h6 right after an h2), which breaks navigation for screen reader users. This showed up in the [header hierarchy triage report](https://app.notion.com/p/supabase/Playwright-E2E-Triage-Reports-3ab5004b775f81e3bc60d058fa5a02c1) — fixing these 4 components alone resolves 72 of the 159 heading-order violations found. ## Solution Swapped the heading tag in each component for a `<span>` with the same classes. None of these are really "headings" for the content that follows, so they shouldn't be in the tag tree at all. The one wrinkle: this codebase applies heading font weight/family through a global CSS rule keyed off the tag name (h1-h6), not something the tag gives you for free. So each span now sets that styling explicitly, plus a margin to match what was there before. Nothing else changed — same classes, same layout. ## Manual testing Staging preview: https://docs-git-ui-header-hierarchy-supabase.vercel.app Check that each one still looks right: - [NamedCodeBlock](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/self-hosting/docker) — filenames above the code blocks - [ProjectConfigVariables](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/auth/quickstarts/react-native) — the "Project URL" / "Publishable key" labels (this page also has a `NamedCodeBlock` inside the numbered steps) - [StepHikeCompact](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/database/beekeeper-studio) — the step titles ("Create a new connection", etc.) - [IconPanel](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/resources) — the "Auth0" / "Firebase Auth" panel titles under "Migrate to Supabase" I also ran typecheck, lint, and the docs test suite locally — all green. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Style** * Updated headings and labels across documentation and UI components for more consistent typography. * Improved spacing, font weight, and block-level layout for project variables, step details, code tabs, and icon panels. * Preserved existing text content and conditional display behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-31 18:25:23 +00:00
Miranda LimonczenkoandClaude Sonnet 5	81523d5d8c	fix(docs): fix heading-order skips in guide and troubleshooting content (#48459) ... Closes DOCS-1260 _See WAVE plugin no longer flags a jump in header hierarchy. Preview on left._ <img width="708" height="699" alt="Screenshot 2026-07-29 at 2 30 11 PM" src="https://github.com/user-attachments/assets/be5bf335-9e03-474f-8215-06fa505ab2db" /> ## Problem Beyond the 4 shared components fixed in [#48456](https://github.com/supabase/supabase/pull/48456), the [header hierarchy report](https://app.notion.com/p/supabase/Playwright-E2E-Triage-Reports-3ab5004b775f81e3bc60d058fa5a02c1) found plain content headings that skip a level. For example, you may see a `##` followed directly by an `####`. Jumps in headers breaks page navigation for screen reader users, who jump between headings expecting each level to nest one at a time. ## Solution Adjusted heading levels across the affected guide and troubleshooting pages so every section nests correctly, with no skipped levels. **Staging previews:** | Page | Preview | | --- | --- | | `/guides/api/rest/postgrest-error-codes` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/api/rest/postgrest-error-codes) | | `/guides/auth/oauth-server/getting-started` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/auth/oauth-server/getting-started) | | `/guides/database/custom-postgres-config` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/database/custom-postgres-config) | | `/guides/database/drizzle` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/database/drizzle) | | `/guides/database/extensions` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/database/extensions) | | `/guides/database/extensions/pgaudit` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/database/extensions/pgaudit) | | `/guides/database/postgres-js` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/database/postgres-js) | | `/guides/database/replication/manual-replication-monitoring` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/database/replication/manual-replication-monitoring) | | `/guides/database/replication/manual-replication-setup` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/database/replication/manual-replication-setup) | | `/guides/database/replication/pipelines-monitoring` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/database/replication/pipelines-monitoring) | | `/guides/functions/debugging-tools` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/functions/debugging-tools) | | `/guides/functions/development-tips` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/functions/development-tips) | | `/guides/functions/examples/auth-send-email-hook-react-email-resend` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/functions/examples/auth-send-email-hook-react-email-resend) | | `/guides/functions/examples/image-manipulation` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/functions/examples/image-manipulation) | | `/guides/functions/examples/semantic-search` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/functions/examples/semantic-search) | | `/guides/functions/examples/send-emails` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/functions/examples/send-emails) | | `/guides/functions/examples/sentry-monitoring` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/functions/examples/sentry-monitoring) | | `/guides/functions/wasm` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/functions/wasm) | | `/guides/getting-started` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/getting-started) | | `/guides/platform/aws-marketplace` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/platform/aws-marketplace) | | `/guides/platform/aws-marketplace/faq` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/platform/aws-marketplace/faq) | | `/guides/platform/billing-faq` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/platform/billing-faq) | | `/guides/platform/ipv4-address` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/platform/ipv4-address) | | `/guides/platform/migrating-within-supabase/backup-restore` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/platform/migrating-within-supabase/backup-restore) | | `/guides/platform/privatelink` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/platform/privatelink) | | `/guides/queues/api` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/queues/api) | | `/guides/resources` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/resources) | | `/guides/security/hipaa-compliance` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/security/hipaa-compliance) | | `/guides/security/security-testing` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/security/security-testing) | | `/guides/security/soc-2-compliance` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/security/soc-2-compliance) | | `/guides/self-hosting` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/self-hosting) | | `/guides/storage/cdn/fundamentals` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/storage/cdn/fundamentals) | | `/guides/storage/debugging/logs` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/storage/debugging/logs) | | `/guides/storage/production/scaling` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/storage/production/scaling) | | `/guides/storage/schema/helper-functions` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/storage/schema/helper-functions) | | `/guides/storage/serving/image-transformations` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/storage/serving/image-transformations) | | `/guides/storage/uploads/resumable-uploads` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/storage/uploads/resumable-uploads) | | `/guides/troubleshooting/an-invalid-response-was-received-from-the-upstream-server-error-when-querying-auth-RI4Vl-` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/an-invalid-response-was-received-from-the-upstream-server-error-when-querying-auth-RI4Vl-) | | `/guides/troubleshooting/are-all-features-available-in-self-hosted-supabase-THPcqw` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/are-all-features-available-in-self-hosted-supabase-THPcqw) | | `/guides/troubleshooting/avoiding-timeouts-in-long-running-queries-6nmbdN` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/avoiding-timeouts-in-long-running-queries-6nmbdN) | | `/guides/troubleshooting/database-api-42501-errors` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/database-api-42501-errors) | | `/guides/troubleshooting/disabling-prepared-statements-qL8lEL` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/disabling-prepared-statements-qL8lEL) | | `/guides/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/discovering-and-interpreting-api-errors-in-the-logs-7xREI9) | | `/guides/troubleshooting/edge-function-504-error-response` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/edge-function-504-error-response) | | `/guides/troubleshooting/high-cpu-and-slow-queries-with-error-must-be-a-superuser-to-terminate-superuser-process` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/high-cpu-and-slow-queries-with-error-must-be-a-superuser-to-terminate-superuser-process) | | `/guides/troubleshooting/how-postgres-chooses-which-index-to-use-_JHrf4` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/how-postgres-chooses-which-index-to-use-_JHrf4) | | `/guides/troubleshooting/how-to-change-max-database-connections-_BQ8P5` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/how-to-change-max-database-connections-_BQ8P5) | | `/guides/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/how-to-interpret-and-explore-the-postgres-logs-OuCIOj) | | `/guides/troubleshooting/how-to-migrate-from-supabase-auth-helpers-to-ssr-package-5NRunM` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/how-to-migrate-from-supabase-auth-helpers-to-ssr-package-5NRunM) | | `/guides/troubleshooting/http-api-issues` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/http-api-issues) | | `/guides/troubleshooting/increase-vector-lookup-speeds-by-applying-an-hsnw-index-ohLHUM` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/increase-vector-lookup-speeds-by-applying-an-hsnw-index-ohLHUM) | | `/guides/troubleshooting/interpreting-supabase-grafana-cpu-charts-9JSlkC` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/interpreting-supabase-grafana-cpu-charts-9JSlkC) | | `/guides/troubleshooting/interpreting-supabase-grafana-io-charts-MUynDR` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/interpreting-supabase-grafana-io-charts-MUynDR) | | `/guides/troubleshooting/new-branch-doesnt-copy-database` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/new-branch-doesnt-copy-database) | | `/guides/troubleshooting/not-receiving-auth-emails-from-the-supabase-project-OFSNzw` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/not-receiving-auth-emails-from-the-supabase-project-OFSNzw) | | `/guides/troubleshooting/resolving-500-status-authentication-errors-7bU5U8` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/resolving-500-status-authentication-errors-7bU5U8) | | `/guides/troubleshooting/resolving-cannot-execute-update-in-a-read-only-transaction-on-transaction-pooler-connections-ef582c` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/resolving-cannot-execute-update-in-a-read-only-transaction-on-transaction-pooler-connections-ef582c) | | `/guides/troubleshooting/resolving-database-hostname-and-managing-your-ip-address-pVlwE0` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/resolving-database-hostname-and-managing-your-ip-address-pVlwE0) | | `/guides/troubleshooting/rls-simplified-BJTcS8` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/rls-simplified-BJTcS8) | | `/guides/troubleshooting/security-of-anonymous-sign-ins-iOrGCL` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/security-of-anonymous-sign-ins-iOrGCL) | | `/guides/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP) | | `/guides/troubleshooting/supabase-grafana-memory-charts` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/supabase-grafana-memory-charts) | | `/guides/troubleshooting/supavisor-faq-YyP5tI` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/supavisor-faq-YyP5tI) | | `/guides/troubleshooting/tracking-postgres-role-activity-to-specific-dashboard-users-8d3715` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/tracking-postgres-role-activity-to-specific-dashboard-users-8d3715) | | `/guides/troubleshooting/transferring-from-cloud-to-self-host-in-supabase-2oWNvW` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/transferring-from-cloud-to-self-host-in-supabase-2oWNvW) | | `/guides/troubleshooting/understanding-postgresql-explain-output-Un9dqX` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/understanding-postgresql-explain-output-Un9dqX) | | `/guides/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/understanding-postgresql-logging-levels-and-how-they-impact-your-project-KXiJRm) | | `/guides/troubleshooting/vercel-integration-environment-variables-not-syncing-for-persistent-git-branches-b9191e` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/vercel-integration-environment-variables-not-syncing-for-persistent-git-branches-b9191e) | | `/guides/troubleshooting/why-are-there-gaps-in-my-postgres-id-sequence-Frifus` | [Preview](https://docs-git-docs-heading-hierarchy-supabase.vercel.app/docs/guides/troubleshooting/why-are-there-gaps-in-my-postgres-id-sequence-Frifus) | ## Manual testing 1. See affected pages. Recommend running a browser plugin like WAVE and selecting the **Structure** tab. 2. See the headings do not skip. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Release Notes * **Documentation** * Standardized heading hierarchy across many guides and troubleshooting articles to improve readability and navigation. * Updated several documentation link targets to the correct new locations. * Reformatted multiple sections (including replication monitoring, Edge Functions, Storage, authentication, security, and networking) without changing instructions. * Queue Data API docs were restructured via heading-level adjustments (no operational changes). * Billing FAQ received clearer, more detailed payment-failure and tax guidance, plus related link updates. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-31 10:47:14 -07:00
Miranda Limonczenko	abbf667084	fix(docs) Resolve local link paths caused that have redirects (#48453) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem The Docs E2E link checker found broken links throughout docs, starting with `phone-login.mdx` pointing to `/docs/guides/cli/config` (404). Old links like `/docs/guides/cli/config` still work on the live site because `supabase.com` has redirects set up for them, but these links break on the docs preview site, which is what the E2E check tests against. These issues look clean on the live site, and I didn't catch them in my first pass because I was testing production instead of the preview. The E2E check only tests the ~20 pages a given PR happens to touch, so fixing the pages it flagged kept exposing more of the same problem one page at a time as each fix pulled in a new file. To stop chasing this incrementally, I cross-referenced every `/docs/guides/*` and `/docs/reference/*` redirect source in `apps/www/lib/redirects.js` against actual usage across all of `apps/docs`, and verified each candidate against the live preview. ## Solution Rather than updating the Docs E2E link checker, this PR resolves the links. **Why:** we own these docs, so keeping the links clean without redirects is keeping the house maintained. See [Broken Window Theory](https://blog.codinghorror.com/the-broken-window-theory/). Updated every link still using an old path to point straight at the current page instead of relying on a redirect. This covers old links like: - `/docs/guides/cli/config` → `/docs/guides/local-development/cli/config` - `/docs/guides/cli/getting-started` → `/docs/guides/local-development/cli/getting-started` - `/docs/guides/cli/local-development` → `/docs/guides/local-development/database-migrations` - `/docs/guides/cli/managing-environments` → `/docs/guides/deployment/managing-environments` - `/docs/guides/cli/seeding-your-database` → `/docs/guides/local-development/seeding-your-database` - bare `/docs/guides/cli` → `/docs/guides/local-development` - `/docs/guides/platform/compute-add-ons` → `/docs/guides/platform/compute-and-disk` - `/docs/guides/platform/shared-responsibility-model` → `/docs/guides/deployment/shared-responsibility-model` - `/docs/guides/database` → `/docs/guides/database/overview` - `/docs/reference/javascript`, `/docs/reference/dart`, `/docs/reference/kotlin`, `/docs/reference/python`, `/docs/reference/csharp` → their `/introduction` pages (the redirect's own destination, `/start`, turned out to be dead even on production — a separate bug in `redirects.js` I didn't touch here) - and about 35 more of the same pattern, listed in the commit messages Also fixed a handful of dead heading anchors found along the way (links that resolve to the right page but point at a `#section` that got renamed or moved), including the original `#bigquery` anchor and a few in `connecting-to-postgres.mdx` where content moved to its own dedicated page. Left alone on purpose: - `content/guides/cli.mdx` — this page has no route in the docs app at all (no `app/guides/cli/` directory), so it 404s even in production before the `www` redirect ever fires. Fixing its internal link wouldn't change that; it needs an actual routing/content decision, not a link fix. - A few candidates that already resolve fine as-is (`pg_partman`, bare `/docs/reference/api`, bare `/docs/reference/cli`) — confirmed via curl, left untouched. ## Manual testing 1. Confirmed every new link target actually exists by checking the destination file/page and matching heading anchors. 2. Cross-referenced every `/docs/guides/*` and `/docs/reference/*` redirect source in `apps/www/lib/redirects.js` against real usage in `apps/docs`, and curl-verified each old path (404) and new path (200) against the live PR preview before fixing it. 3. Ran the Docs E2E link checker locally against changed pages. 4. Spot-checked the original broken link from CI (`/docs/guides/cli/config`) to confirm it now points to a working page.	2026-07-29 14:47:17 -07:00
Miranda Limonczenko	0d465e7b5f	chore(ui): Remove 'tip' from Admonition (#48419) ... Closes FE-3966 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem - The admonition uses both 'tip' and 'note', but the visual distinction has long-ago collapsed. - 'Note' is used far more frequently than 'tip' - The two are very similar and it is confusing to know which one to use when they are visually identical ## Solution Collapse 'tip' and 'note' into one by removing all places where there is 'tip' and updating all references to 'tip' into 'note'. **Note:** This PR also resolves new broken links flagged by the E2E docs checker. It may move to another PR since E2Es keep erroring. ### Specific changes See below for an AI-generated list of changes: - **Type system** — removed `'tip'` from `AdmonitionType`, its `TYPE_TO_VARIANT`/`TYPE_LABEL` entries, and the test case in [`packages/ui-patterns/src/Admonition/](packages/ui-patterns/src/Admonition/) - **Remark plugin** — [remarkAdmonition.ts](apps/docs/lib/mdx/plugins/remarkAdmonition.ts) now maps mkdocs `tip` → `note` - **Lint allowlist** — `tip` dropped from `supa-mdx-lint.config.toml` - **Content migration** — all 109 files with `type="tip"` (across `apps/docs`, `apps/www`, `apps/studio`) converted to `type="note"`; zero remaining hits confirmed by repo-wide grep - **Style guide** — `CONTRIBUTING.md` and `contributing/content.mdx` updated to describe 4 admonition types instead of 5 ### Usage before implementation See the usage table that points toward 'note' as being dominant across all apps: Here's the usage table: | Location | `note` | `tip` | |---|---|---| | apps/docs | ~480 | ~143 | | apps/studio | 34 | 6 | | apps/www (blog) | 19 | 3 | | packages/ui-patterns (tests) | 3 | 1 (parametrized) | | design-system / ui-library / packages/ui / packages/common | 0–1 (test fixture only) | 0 | ## Preview links | App | Page | Search text (Ctrl+F) | Verify | |---|---|---|---| | docs | [/docs/guides/ai-tools/byo-mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/byo-mcp) | official MCP TypeScript SDK | callout's aria-label="Note" | | docs | [/docs/guides/ai-tools/mcp](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai-tools/mcp) | MCP server is available at | callout's aria-label="Note" | | docs | [/docs/guides/ai/python-clients](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/ai/python-clients) | Click Connect at the top of any project page | callout's aria-label="Note" | | docs | [/docs/guides/auth/audit-logs](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/auth/audit-logs) | Disabling Postgres storage reduces your database storage costs | callout's aria-label="Note" | | docs | [/docs/guides/database/tables](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/database/tables) | access a custom schema through the Supabase Data API | callout's aria-label="Note" | | docs | [/docs/guides/troubleshooting/edge-function-404-error-response](https://docs-git-admonition-collapse-note-tip-supabase.vercel.app/docs/guides/troubleshooting/edge-function-404-error-response) | Always configure an appropriate time frame | callout's aria-label="Note" (was single-quoted type='tip') | | www | [blog: cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code) | Detecting config drift | callout's aria-label="Note" | | www | [blog: cli-v2-config-as-code](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/cli-v2-config-as-code) | Setting Edge Function secrets | callout's aria-label="Note" | | www | [blog: nosql-mongodb-compatibility-with-ferretdb-and-flydotio](https://zone-www-dot-com-git-admonition-collapse-note-tip-supabase.vercel.app/blog/nosql-mongodb-compatibility-with-ferretdb-and-flydotio) | If your network supports IPv6 connections | callout's aria-label="Note" | Note: the `www` rows use the `zone-www-dot-com` preview host, not the `docs` one you gave — since blog pages are served from the www app, not docs. ## Manual testing 1. Open preview links for affected pages. 2. Inspect. Open console. 3. Paste the following in and see there is no 'Tip' on the page: ``` document.querySelectorAll('[role="alert"]').forEach(el => console.log(el.getAttribute('aria-label'), el.textContent.slice(0,60))) ``` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Standardized informational callouts across docs and tutorials from **“Tip”** to **“Note”**, updating multiple examples and guidance blocks. * Updated a few related doc references/links and conditional “Next steps” content. * **UI Updates** * Switched various in-app banners and notices to the **“Note”** style variant. * **Bug Fixes / Improvements** * Removed support for the retired **“Tip”** callout type and aligned docs linting, component behavior, and aria labeling to the remaining admonition types. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-07-29 09:26:50 -07:00
Miranda Limonczenko	9bf513f8bf	Update humans.txt (#48407) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Cleans up a name that was missed.	2026-07-28 10:47:44 -06:00
Miranda LimonczenkoandClaude Sonnet 5	52cb1c2600	feat(docs) Dynamically E2E test all docs-owned content (#48320) ... Closes DOCS-1203 ## Problem The docs E2E workflow only ever tested one hardcoded page: the Next.js quickstart. All other docs content had no E2E coverage. ## Solution This PR expands the initial scaffolding to generalize the Next.js quickstart tests, page runs and checks local links, to all pages affecting Docs content: - Add `resolveDocsScope` (`e2e/docs/utils/resolve-docs-scope.ts`) to map changed guide and troubleshooting `.mdx` files to their `/docs/...` page paths, and to expand changed `_partials` to every page that includes them (including transitively, through partials nested inside other partials). Federated guide sections (`graphql`, `database/extensions/wrappers`, `ai/python`, `deployment/terraform`, `deployment/ci`) and reference docs stay out of scope, and resolution is capped at 20 pages to keep runtime bounded. - Replace the single `quickstarts.spec.ts` test with a generic `docs-pages.spec.ts` that loads whatever pages are resolved, asserting each renders with an `<h1>` and that its docs-owned links resolve. - Add `run-e2e-docs.ts` so `pnpm e2e:docs` resolves scope locally (from commits since `origin/master`, plus staged/unstaged changes) and skips Playwright entirely when nothing in scope changed. - Update `.github/workflows/docs-e2e.yml` to widen the trigger paths to all guides/troubleshooting/partials, resolve scope in a dedicated step, skip the rest of the job when scope is empty, and accept a `page_paths` input for manual `workflow_dispatch` runs. - Rewrite `e2e/docs/README.md` to document the new scoping behavior, the override envs (`DOCS_E2E_PAGE_PATHS`, `DOCS_E2E_BASE_REF`), and how CI uses the suite. - `pnpm e2e:docs:all` is also added to run tests on every page locally. Good for scoping issues but should not be included in CI. ## Manual testing Walk through the following steps to verify this works: - [x] `pnpm e2e:docs` from repo root resolves the expected pages for a local guide edit and can run against local dev **Note:** Challenges with testing on local in part because of the long lag for first page load. Recommendation to use a hosted URL is added to docs. - [x] Editing a shared `_partials` file resolves to every page that includes it (including through nested partials) - [x] `pnpm e2e:docs` exits cleanly with no Playwright run when no in-scope files changed - [x] `git diff --name-only ... | pnpm -C e2e/docs resolve-docs-scope` prints the expected page list for a sample diff - [x] Workflow run on a PR that only touches `e2e/docs`/workflow files skips the Playwright steps - [x] Manual `workflow_dispatch` run with `page_paths` set tests only those pages - [x] Run `pnpm e2e:docs:all` to run the suite on all docs content, which takes awhile ## Next steps After this PR merges, we have the scaffolding to add more fun tests like a11y 😁 <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added scoped Docs E2E runs that target eligible doc pages based on changes, plus manual page-targeted runs and an “all eligible pages” mode. * Introduced `DOCS_E2E_PAGE_PATHS` (and updated base ref/base URL behavior) to control which pages are tested. * **Bug Fixes** * Automatically skips Playwright setup when no relevant pages are in scope; Playwright reporting now uploads only on failure. * **Documentation** * Updated the Docs E2E README with new run/CI behavior, troubleshooting notes, and commands to inspect the resolved page list. * **Tests** * Added a Docs-owned pages E2E suite; removed the Next.js quickstart E2E spec. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-28 00:04:58 +00:00
3 people	2b27ed0ab1	fix(docs) Improve a11y for Admonitions with file refactor (#48112) ... Closes FE-3914 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem On screenreader, I found that the Admonition was not behaving as it should: - There was no way on screenreader to tell what type of note I was seeing - I could not tell when a note began or ended. - The screenreader also read aloud an 'image' icon without knowing what it was. - Notes with titles were an `h5`, breaking header hierarchy structures. ## Solution This PR does several things to resolve the issue: - Adds `aria-hidden` to all icons. Instead of duplicating code, I refactored the icons into a Base Icon and moved Admonitions into its own folder. - ~Adds a text label for each of the notes. For example, "**Note:**". This is a standard practice in other documentation. If there is a title, it is added there. Otherwise, it's added to the description.~ Change reverted from design feedback. - ~Adds `role='note'` and `aria-label` to the Admonition. While `<aside>` is recommended semantic HTML, the base UI element does not allow for that change.~ This will be done in a follow-up for docs only. - Refactors Admonition into a folder with files so that it is more readable - Removes `h5` by default with a new prop to declare a header Additionally adjusts the icon so that it aligns with text better. ## Testing 1. Open documentation preview 2. Navigate to any guide and see its admonition. Compare to live. You can also see the Design System: https://design-system-git-a11y-docs-admonition-supabase.vercel.app/design-system/docs/fragments/admonition 3. See the icon position is in line with the text. 4. See the text label. 5. Use a screenreader like Voiceover on the admonition. Hear that it is clearly defined. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Summary by CodeRabbit - **New Features** - Added the Admonition UI pattern with support for `type`, `layout`, `title`/`description`, optional actions, and configurable icons. - Expanded Admonition’s public export surface with dedicated subpath entry points and icon/type exports. - **Bug Fixes** - Standardized Admonition import path casing across related components. - **Documentation** - Updated design system examples to use `type="warning"` instead of `variant="warning"`. - **Tests** - Added/updated the Admonition test coverage and removed the legacy test file. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com> Co-authored-by: Danny White <3104761+dnywh@users.noreply.github.com>	2026-07-24 15:51:19 -07:00
Miranda Limonczenko	b5cae478bc	fix(docs) Add smoke test for local development without credentials (#48218) ... Closes DOCS-1210 Closes DOCS-1209 #48226 needs to merge first for CI failure ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Test coverage and several small bug fixes discovered during implementation. ## What is the current behavior? Nothing verified that `pnpm run dev:docs` keeps working without private credentials. We value this command working, especially for community contributors. However, this issue can go undetected by employees at Supabase since many of us have credentials in place. We do not want this to go a week before finding and fixing like in the previous instance. ## What is the new behavior? - **New Playwright test suite**: `e2e/docs/local-smoke/no-credentials.spec.ts` boots the docs dev server with zero GitHub App/Supabase secrets and checks 5 routes covering each known failure point. - **CI**: a new `local-dev-smoke` job in `docs-tests.yml` runs this suite with no credentials configured. ## Additional bugs resolved Setting up this test exposed other issues that are fixed in this PR: - **Troubleshooting.utils.ts crash** — Unguarded Supabase call pattern, crashing every troubleshooting article. Added the same guard as previous fixes. - **Missing manifest.json** — middleware.ts statically imports public/markdown/manifest.json, which is gitignored and only generated by a build step that's skipped in local dev. On a fresh checkout it doesn't exist, so middleware fails to compile and takes down every page. Fixed by committing a placeholder [] (real builds still regenerate the full file). - **Phantom @code-hike/mdx import** — apps/docs/app/layout.tsx imported @code-hike/mdx/styles.css, but only apps/www actually declares that dependency. Worked by accident whenever both apps were installed together; broke in CI's docs-only install. Turned out to be dead code (nothing in docs actually uses code-hike), so fixed by deleting the unused imports rather than adding the dependency. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Summary by CodeRabbit * **New Features** * Added a credential-free “local smoke” end-to-end test suite for key documentation routes. * **Bug Fixes** * Improved troubleshooting behavior when required external service credentials are missing. * Updated federated “wrappers” documentation pages to gracefully show a fallback message when external content can’t be fetched. * **Tests** * Added a dedicated local-smoke Playwright runner and enhanced CI path-based triggering and reporting (failure-focused artifacts). * **Chores** * Refined docs workflow path filters and adjusted docs markdown manifest/ignore rules for generated content. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-07-24 10:29:12 -07:00
Miranda LimonczenkoandClaude Sonnet 5	39276f80d0	fix(docs ci): stop docs-e2e from polling the broken GitHub Deployments API (#48226) ... ## Summary - `vercel/wait-for-deployment-action` in [docs-e2e.yml](.github/workflows/docs-e2e.yml) polls GitHub's Deployments API for a `Preview – docs` deployment, but Vercel's GitHub App has not written a GitHub Deployment object repo-wide since 2026-02-17 (broken app auth). The step times out after 900s on every PR that touches `apps/docs`, even though the preview build itself succeeds (`Vercel – docs` commit status is green). - Replace the wait step with a custom poll of the `Vercel – docs` commit status (which Vercel keeps posting correctly), then resolve the actual preview URL via Vercel's own deployments API (`GET /v13/deployments/{id}`) using the deployment ID embedded in the commit status's `target_url`, reusing the existing `VERCEL_TOKEN` / `VERCEL_TEAM_ID` secrets. - Drops the now-unused `deployments: read` permission. ## Context Reported in Slack: https://supabase.slack.com/archives/C023E4L60R3/p1784721725606599?thread_ts=1784658589.182079&cid=C023E4L60R3 (surfaced by [#48178](https://github.com/supabase/supabase/pull/48178) failing on this step — [run 29916797889](https://github.com/supabase/supabase/actions/runs/29916797889?pr=48178)). Agreed workaround from that thread: swap the wait step to poll the `Vercel – docs` commit status instead of the Deployments API. ## Test plan - [ ] Confirm this workflow run (triggered by this PR since it edits `apps/docs/**`... actually this PR only touches the workflow file, so verify via `workflow_dispatch` or a follow-up PR touching `apps/docs/**`) passes the "Wait for Vercel docs preview" step and resolves a working `deployment-url` - [ ] Confirm downstream Playwright E2E run against the resolved preview URL succeeds - [ ] Confirm the step still fails cleanly (clear error, no silent hang) if the Vercel deployment itself fails 🤖 Generated with [Claude Code](https://claude.com/claude-code) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Improved documentation preview deployment handling in end-to-end tests. * Replaced the preview wait logic with more reliable polling for the relevant commit status, including clear success/failure/error and timeout behavior. * Resolve the correct documentation preview URL before tests proceed. * **Chores** * Tightened permissions for the documentation E2E workflow to use only the required access scopes. * Streamlined job setup steps so Node/Pnpm preparation runs earlier in the workflow. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-23 11:33:38 -07:00
Miranda Limonczenko	359974d071	fix(docs) Fix local broken links (#48212) ... Closes DOCS-1202 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem We have broken local links in docs. I ran locally tests that crawl through all of our docs and flags broken local links. ## Solution This PR fixes local links where they were errored. The report I generated had false-positives, so there are fewer fixes than initially thought. ## Preview checklist Docs preview: https://docs-git-docs-fix-broken-local-links-supabase.vercel.app WWW preview (redirects): https://zone-www-dot-com-git-docs-fix-broken-local-links-supabase.vercel.app | Page | Live (broken) | Preview (fixed) | Where to look | | --- | --- | --- | --- | | Amazon Bedrock | [Live](https://supabase.com/docs/guides/ai/integrations/amazon-bedrock) | [Preview](https://docs-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/ai/integrations/amazon-bedrock) | **You'll also need** → `A Postgres database with the pgvector extension` | | Getting started | [Live](https://supabase.com/docs/guides/getting-started) | [Preview](https://docs-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/getting-started) | Tutorial cards → **Expo React Native Social Auth** | | Product security | [Live](https://supabase.com/docs/guides/security/product-security) | [Preview](https://docs-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/security/product-security) | **Database** list → `Superuser access and unsupported operations` | | OAuth flows | [Live](https://supabase.com/docs/guides/auth/oauth-server/oauth-flows) | [Preview](https://docs-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/auth/oauth-server/oauth-flows) | End of page, before **Next steps** → `OAuth methods in supabase-js` | | ElevenLabs TTS | [Live](https://supabase.com/docs/guides/functions/examples/elevenlabs-generate-speech-stream) | [Preview](https://docs-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/functions/examples/elevenlabs-generate-speech-stream) | **Dependencies** → ElevenLabs `JavaScript SDK` | | ElevenLabs STT | [Live](https://supabase.com/docs/guides/functions/examples/elevenlabs-transcribe-speech) | [Preview](https://docs-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/functions/examples/elevenlabs-transcribe-speech) | **Dependencies** → ElevenLabs `JavaScript SDK` | | Realtime error codes | [Live](https://supabase.com/docs/guides/realtime/error_codes) | [Preview](https://docs-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/realtime/error_codes) | `RealtimeDisabledForTenant` → reference link | | Expo social auth redirect (legacy) | [Live](https://supabase.com/docs/guides/with-expo-social-auth) | [Preview](https://zone-www-dot-com-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/with-expo-social-auth) | Should land on the Expo social auth quickstart | | Expo social auth redirect (old tutorials path) | [Live](https://supabase.com/docs/guides/getting-started/tutorials/with-expo-social-auth) | [Preview](https://zone-www-dot-com-git-docs-fix-broken-local-links-supabase.vercel.app/docs/guides/getting-started/tutorials/with-expo-social-auth) | Should land on the Expo social auth quickstart | ### Manual testing 1. For each row, open the **Live** link and find the linked text in **Where to look**. 2. Click the link and confirm it 404s or lands on the wrong page. 3. Open the matching **Preview** link, find the same linked text, and click it. 4. Confirm the preview link resolves to the correct destination: - Amazon Bedrock → `/docs/guides/database/extensions/pgvector` - Getting started → `/docs/guides/auth/quickstarts/with-expo-react-native-social-auth` - Product security → `/docs/guides/database/postgres/roles-superuser` - OAuth flows → `/docs/reference/javascript/auth-admin-oauth-server` - ElevenLabs TTS / STT → `https://github.com/elevenlabs/elevenlabs-js` - Realtime error codes → `/docs/guides/troubleshooting/realtime-project-suspended-for-exceeding-quotas` - Redirect rows → `/docs/guides/auth/quickstarts/with-expo-react-native-social-auth` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated links for pgvector, OAuth, ElevenLabs SDK, and database security guidance. * Corrected the Expo React Native social authentication tutorial link. * Updated Realtime troubleshooting references to the current documentation path. * **Bug Fixes** * Fixed redirects for Expo social authentication guides so legacy URLs reach the correct quickstart. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-07-22 11:49:04 -07:00
Miranda LimonczenkoandClaude Sonnet 5	ca2a390a3d	fix(docs): restore Supabase env vars to stop crash on every page load (#48213) ... https://github.com/user-attachments/assets/0b9e4bd1-e2b6-4a58-b47e-803e2b34a32e ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Bug fix. ## What is the current behavior? Every page in `apps/docs` crashes at runtime with `Error: supabaseUrl is required.` Regression from #46757, which flipped `NEXT_PUBLIC_IS_PLATFORM` to `"true"` in `apps/docs/.env.development` and, in the same diff, duplicated a `NEXT_PUBLIC_MARKETPLACE_API_URL`/`NEXT_PUBLIC_MARKETPLACE_PUBLISHABLE_KEY` block where `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY` should have been. With `IS_PLATFORM` now `true`, `Feedback.tsx` (rendered on every docs page) unconditionally calls `createClient()` with an undefined URL/key, throwing synchronously on every page load. Closes DOCS-1208 / FE-3980. ## What is the new behavior? - `apps/docs/.env.development`: renamed the mislabeled duplicate block back to `NEXT_PUBLIC_SUPABASE_URL`/`NEXT_PUBLIC_SUPABASE_ANON_KEY`. - `apps/docs/components/Feedback/Feedback.tsx`: widened the guard to `IS_PLATFORM && supabaseUrl && supabaseAnonKey`, mirroring the existing pattern in `app/api/ai/docs/route.ts`, so a future env misconfiguration degrades gracefully (feedback votes silently skipped) instead of crashing every page. Verified locally by running `pnpm dev:docs` with no GitHub credentials set: - No more `"supabaseUrl is required."` anywhere; the Feedback widget renders and fires its vote request instead of throwing. - A normal guide page renders fine. - `/guides/database/database-advisors` still shows its existing graceful fallback admonition. - `/guides/graphql` (federated content, absent on a clean checkout) returns a clean 404 rather than crashing — confirming the related goal of running docs dev locally without federated content already works (via #48205 + existing `notFound()` handling), no extra changes needed there. ## Additional context A related but separate gap was found in `apps/docs/app/guides/database/extensions/wrappers/[[...slug]]/page.tsx`. A new Linear issue is created: https://linear.app/supabase/issue/DOCS-1209/wrappers-guide-page-crashes-on-unhandled-github-fetch-failure-without ## Manual testing 1. Checkout branch locally and run `pnpm run dev:docs` with no GitHub credentials set. Confirm it starts without errors. 2. Open any guide page on docs locally and confirm no `supabaseUrl is required` error, and the Feedback widget renders and responds to clicks. 3. Open `/docs/guides/database/database-advisors`. Confirm it renders and does not crash. 4. Open `/docs/guides/graphql`. Confirm a clean 404, not a server error. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Bug Fixes** * Improved feedback functionality by safely handling missing configuration. * Feedback votes and comments are skipped when the required service configuration is unavailable, preventing errors. * **Chores** * Updated documentation-site configuration to use the appropriate content service settings. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>	2026-07-22 11:06:50 -07:00
Miranda LimonczenkoandCopilot Autofix powered by AI	9199aad57e	feat(docs) Add scaffolding and CI/CD step for Docs Playwright (#48120) ... Closes DOCS-1197 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem We do not have any E2E testing established. ## Solution This PR creates an ultra-lean starting place for Docs Playwright: - A CI/CD step that skips on draft and relies on Preview for testing - One simple broken link check for one page The goal: - Playwright is implemented where we want it, with an architecture we want, with set-up steps we can build from The anti-goal of this PR: - We have meaningful tests running ## CI/CD steps <img width="1191" height="72" alt="Screenshot 2026-07-21 at 10 17 06 AM" src="https://github.com/user-attachments/assets/eeb2454c-d864-4574-a050-ce39bb3f083f" /> 1. Checkout a thin slice of the repo (`apps/docs`, `packages`, `patches`). 2. Wait for the Vercel **docs** preview for that commit SHA. 3. Use that preview URL as `PLAYWRIGHT_BASE_URL`. 4. Install Node deps and Chromium. 5. Run `pnpm run e2e:docs` (`--grep @quickstart`). 6. If anything fails, upload the HTML report + traces. Manual runs skip the Vercel wait and default to `https://supabase.com` (or whatever URL you enter), then run the full suite (`pnpm run e2e`). ## What the test checks Because this PR is scaffolding, it is doing something very basic: 1. Opens `/docs/guides/getting-started/quickstarts/nextjs` only if a connected file was edited in CI/CD step 2. Asserts the page loaded and the H1 is visible. 3. Collects docs-owned `/docs/**` links from `#sb-docs-guide-main-article`. 4. HTTP-checks each link (no full navigation) and soft-fails so every broken link is reported. Config keeps it cheap: Chromium only, 1 worker, 2 CI retries, failure screenshots/traces. ## Docs vs Studio/Dashboard The setup of Docs Playwright differs from Studio. | | Docs E2E | Studio E2E | |---|---|---| | Location |`e2e/docs/` | `e2e/studio/` | | What it tests | One published docs page + its links | Many Studio UI flows (tables, auth, storage, …) | | Where the app runs | Already-deployed **Vercel preview** | Built and started **on the runner** | | Backend needed | None | Local Supabase via Docker | | Path filtering | Native `on.pull_request.paths` (skip whole workflow) | `dorny/paths-filter` after checkout (workflow starts, heavy steps gated) | | Parallelism | 1 worker, no shards | Matrix of frameworks × 2 shards | | Retries | 2 in CI | 5 in CI | | Reports | HTML report on failure | Blob reports per shard → merge → PR comment | | Draft handling | Explicit draft skip | No draft skip today | | Manual broader run | Yes (`workflow_dispatch`) | No | The big conceptual difference: **Studio owns the environment** (build Studio, start Supabase, hit `localhost`). **Docs borrows Vercel’s preview** and only asks “does this page and its docs links work on the deployed site?” ## Docs architecture justification The docs architecture is deliberately lightweight because docs are **static, published content served by Vercel**, not an interactive app with a backend. That single fact justifies every difference: - **Borrow the Vercel preview instead of building on the runner.** The preview is already the exact artifact users will see, and Vercel builds it for free on every PR. Rebuilding docs on the runner would duplicate that work and risk testing something different from what ships. Studio, by contrast, needs a running app plus a local Supabase, so it *has* to own its environment. - **No backend.** Docs pages don't need a database or auth to render, so there's nothing to spin up. This is what keeps the job cheap enough to run per-PR. - **Native `paths` filtering.** Since the job is cheap and self-contained, an all-or-nothing skip at the workflow level is sufficient—no need for `dorny/paths-filter` to gate expensive setup steps mid-run like Studio does. - **Low parallelism and modest retries.** One page and its links is a tiny surface, so 1 worker is plenty and there's no sharding to coordinate. Retries exist only to absorb transient network flakiness against a live URL, hence 2 rather than Studio's 5 (which also cushions a heavier, stateful environment). - **Non-blocking + draft skip + manual dispatch.** As initial scaffolding checking link health on a deployed site, it should inform rather than gate merges, avoid burning minutes on drafts, and still be runnable on demand against production. In short: **Studio owns its environment because it must; docs borrows Vercel's preview because it can.** The scope is intentionally minimal today. ## Testing 1. Break a docs-owned link in the Next.js quickstart. 1. Follow README instructions to set up and run e2e docs test. 1. Confirm the suite fails. 1. Restore the broken link and re-run. 1. Confirm the suite **passes** (`1 passed`). <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Summary - **New Features** - Added a GitHub Actions workflow to run Playwright docs end-to-end tests on PRs and via manual dispatch (with optional base URL), including docs-preview waiting and concurrency cancellation. - **Documentation** - Added `e2e/docs` README with setup, how to run the suite (including UI/debug and single-spec), and how base URL selection works. - **Tests** - Added a quickstarts E2E spec that validates the page and soft-checks docs-owned links resolve. - **Chores** - Added shared Playwright configuration/package scripts and an `e2e/docs` `.gitignore` for test outputs. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>	2026-07-21 14:59:10 -07:00
Miranda Limonczenko	c1d010a699	feat(docs) Add a SKILL to write stronger documentation and apply it to guides/api/securing-your-api (#48018) ... Closes DOCS-1176 ## Summary This PR adds documentation-writing guidance for humans and agents, then applies it to the “Securing your API” guide. ## Changes - Add a documentation word list based on Google’s style guide and existing MDX lint rules. - Add a shared `docs-guides` Agent Skill with Cursor and Claude integration. - Expand contributing guidance for information types, procedures, chunking, links, admonitions, grammar, and terminology. - Restructure “Securing your API” into contextual and procedural sections. - Add section navigation, cross-references, transitions, and procedural outcomes. - Reduce repeated admonitions and improve scannability. ## Manual testing 1. Open `/docs/guides/api/securing-your-api` in Preview and compare to Live. https://docs-git-docs-restructure-api-supabase.vercel.app/docs/guides/api/securing-your-api 2. See that the content is improved and clear with no important context removed. 3. See the Admonitions that are no longer marked as admonitions. See the content still makes sense. 4. Review the diff of `CONTRIBUTING.md` and `WORD_LIST.md`. 5. See that you agree with the new rules and that they are clear. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated documentation-writing guidelines with clearer standards for structure, formatting, components, diagrams, terminology, and navigation. * Added a comprehensive word and style reference for consistent documentation language. * Reworked the API security guide with clearer guidance on grants, RLS, dedicated schemas, pre-request checks, rate limiting, and API keys. * Added documentation authoring workflow guidance, including validation and formatting steps. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-07-17 18:48:45 +00:00
Miranda Limonczenko	a9115b694f	fix(docs) Prevent dashboard links from breaking (#47897) ... Closes DOCS-1174 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem Links from docs to studio can break. There's no way to programmatically check. ## Solution Add a unit test to check that `/dashboard` relative links from docs is absolute. ## Testing 1. Pull this branch to your local machine. 1. Break the link in `apps/docs/data/content-listings/database.data.ts` — change: `href: 'https://supabase.com/dashboard/project/_/sql',` to: `href: '/dashboard/project/_/sql',` 1. Run: cd `apps/docs && pnpm exec vitest run lib/content-listings.test.ts`. You should see dashboard content listing hrefs fail. Restore the absolute URL when you’re done. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Tests** * Added validation to ensure dashboard links in documentation content listings use complete, canonical URLs. * Added coverage for identifying dashboard links across all content listing groups. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-07-13 15:57:13 -07:00
Miranda Limonczenko	1d89af2739	fix(docs) Fix broken link on Dashboard overview (#47892) ... Closes [DOCS-1172](https://linear.app/supabase/issue/DOCS-1172/fix-broken-run-sql-commands-link-in-database-overview-docs) ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Fixes broken link. ## What is the current behavior? Link is broken on dashboard overview. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated the “Run SQL commands” link to direct users to the fully qualified SQL editor URL. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-07-13 09:09:28 -07:00
3 people	c790bd44a3	fix(docs) Use CLI instead of curl for Network Restrictions topic (#47476) ... Closes DOCS-1087 <img width="1493" height="688" alt="Screenshot 2026-06-30 at 4 50 52 PM" src="https://github.com/user-attachments/assets/39267c8a-befb-4419-8fa8-4e987f82781e" /> ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem The Network Restrictions docs contain an incorrect curl example that, when followed, restricts the entire database instead of adding only the specified IP/CIDR — causing production outages for users. ## Solution Fix the incorrect curl command in the Network Restrictions docs so that it correctly adds only the specified CIDR rather than restricting the entire database. This PR solves the problem by adding an `--append` CLI procedure. Additionally, the document is improved: - All procedures are put in procedure format for easier readability and clear action steps - Wording is simpler - Headers follow convention - A "This topic..." intro paragraph is added ## Tophatting 1. Go to the preview link at `/docs/guides/platform/network-restrictions`. 2. Verify that the new `--append` section corrects the original issue. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Reworked the network restrictions guide into clearer “dashboard” and “CLI” setup flows. * Expanded the intro with IPv4/IPv6 CIDR allowlisting guidance, including exceptions for IPv6 migration extensions and when the IPv4 add-on is installed. * Updated the CLI instructions with structured examples for checking, replacing, appending, and fully removing restrictions (including the “never applied” case when allowed lists are empty). * Clarified scope/limitations: restrictions apply to Postgres and its pooler (not HTTPS APIs or client libraries), and enabling restrictions blocks Edge Function direct database access. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Andrew Valleteau <avallete@users.noreply.github.com> Co-authored-by: Jeremias Menichelli <jmenichelli@gmail.com>	2026-07-06 18:16:30 +00:00
Miranda LimonczenkoandCursor	4f05124ce7	feat(docs): add keyboard-accessible skip to content link (#47515) ... https://github.com/user-attachments/assets/30438e3c-b9aa-411b-be38-3fdcd50f7dc6 Closes DOCS-92 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem Screenreaders have to navigate our main menu on every page. This comes from a very old request. 2024. 😱 ## Solution A 'Skip to Content' button is standard a11y practice. This PR improves keyboard navigation by letting users bypass the top nav and sidebar to jump directly to main content. ## Tophatting 1. Go to any page in our docs. Try a sample of different layouts. 2. Use TAB to navigate. See 'Skip to Content' appear. **Note:** You may need to SHIFT + TAB if your keyboard focus is past the main navigation. Mouse clicks can shift focus. 3. Press ENTER. 4. Continue to TAB and see the next links focused are in the main body. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added a “skip to content” button in the docs to improve keyboard navigation. * **Accessibility / UX** * Made the main content area programmatically focusable and adjusted scroll positioning for smoother jumps. * **Style** * Removed the prior global skip-link styles in favor of component-based skip-to-content behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Cursor <cursoragent@cursor.com>	2026-07-02 23:59:29 +00:00
4 people	3dffdefd6e	fix(docs) Resolve 196 mdx lint warnings for just, quickly, actually, PostgreSQL (#47358) ... Closes DOCS-1057 Contributes to DOCS-1052 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem We have hundreds of MDX lint warnings in our docs going against style best practices. ## Solution Remove and replace in context the following: - PostgreSQL. There was only one. There was concern about exceptions, but I found none. - Just - Quickly - Actually ### What changed Edits follow the [Google developer documentation style guide](https://developers.google.com/style): concise, direct, active voice. The flagged words were removed when the sentence still read well, or replaced when meaning needed to be preserved. ### Common patterns | Flagged word | Approach | Example | |---|---|---| | **just** (filler) | Removed | "you just installed" → "you installed" | | **just** (limiting) | **only** | "just one row" → "only one row" | | **just like** | **like** / **the same as** | "function just like regular users" → "function like regular users" | | **not just** | **not only** | "not just errors" → "not only errors" | | **quickly** (performance) | **efficiently** or removed | "find rows quickly" → "find rows efficiently" | | **quickly** (time) | **soon** / **rapidly** / removed | "expires too quickly" → "expires too soon" | | **actually** (filler) | Removed | "actually execute" → "execute"; "is actually the most common" → "is the most common" | ## Tophatting 1. See the diff. 2. See that content continues to make sense in context. 3. Locally, `cd apps/docs` and run `pnpm run lint:mdx`. 4. Search for "just," "actually," "quickly", and "PostgreSQL" and see there are 0 warnings. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated wording across quickstarts, guides, and troubleshooting articles for grammar, clarity, and consistent step-by-step phrasing. * Clarified key concepts including Row Level Security policy evaluation across Supabase products, deferred foreign key constraint behavior, and when `EXPLAIN ANALYZE` executes queries (and related side effects). * Refined several troubleshooting instructions and added guidance to cap log payload size to reduce billed Logs Ingest volume. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Nik Richers <nrichers@gmail.com> Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>	2026-06-29 09:40:25 -07:00
Miranda Limonczenko	5fc0c86007	feat(studio) Link observability pages to relevant docs (#47351) ... Closes DOCS-488 <img width="1266" height="353" alt="Screenshot 2026-06-26 at 11 02 57 AM" src="https://github.com/user-attachments/assets/67b5d47b-249e-4e53-9230-2bbcb7f037b7" /> ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem We have helpful documentation that delves into each observability metric, but it is not easily findable in the moment it is needed while viewing the dashboards. ## Solution Solution includes: - Add a docs link in Studio in every relevant place with the `DocsButton` component - Add aria-hidden on the `DocsButton` icon - An added `constants.ts` to see all of the docs links in one place - A contextual aria-label for the docs so that screenreader users know where they're going | Page | Docs link | |------|-----------| | Overview | `/guides/telemetry/reports` | | Query Performance / Query Insights | `/guides/platform/performance#examining-query-performance` | | API Gateway | `/guides/telemetry/reports#api-gateway` | | Database | `/guides/telemetry/reports#database` | | Data API | `/guides/telemetry/reports#postgrest` | | Auth | `/guides/telemetry/reports#auth` | | Edge Functions | `/guides/telemetry/reports#edge-functions` | | Storage | `/guides/telemetry/reports#storage` | | Realtime | `/guides/realtime/reports` | | Custom reports | `/guides/telemetry/reports#using-reports` | Query Performance and Query Insights already had the button in their custom headers. They now use the shared constants. ## Tophatting 1. Go to a project `/observability`. 2. Click into each of the panels and see a **Docs** link in the top right. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added direct documentation links across observability report pages, making it easier to open relevant help content from each view. * Added clearer, page-specific labels for observability headers and docs links. * **Bug Fixes** * Improved accessibility for icon buttons so icons are hidden from assistive technologies while button labels remain clear. * Adjusted report navigation layouts to keep controls aligned with the new docs buttons. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-06-26 12:11:19 -07:00
Miranda Limonczenko	ea539b4f83	fix(docs) Remove unneeded double border on docs Accordion (#47202) ... Closes DOCS-974 <img width="891" height="328" alt="Screenshot 2026-06-22 at 3 11 13 PM" src="https://github.com/user-attachments/assets/d7b49d56-cf77-4c1d-a933-7cbeab3168c2" /> ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem From Linear: Accordion usage in the docs is inconsistent and can render with double lines instead of single lines. The current docs contribution guidance appears to recommend wrapping accordions with an extra div, which seems to be the cause of the extra divider in some pages. ## Solution This PR: - Removes all wrapping `divs` to AccordionItems that adds an extra border - For a11y, adds a cursor pointer and a slight bg color change on hover to make the clickable area more obvious - For a11y, adds reduce-motion option for animation and `aria-hidden` on the chevron **Note:** It is good for a11y to have more than one hover-state indicator. For example, color-change and an underline. ## Tophatting To review changes on the preview environment: 1. Go to `/docs/guides/platform/backups` and `/docs/guides/platform/migrating-to-supabase/auth0#frequently-asked-questions-faq`. 2. Expand accordion. 3. See nothing visually odd such as strange spacing or double borders. **Note:** To be exhaustive in your review, view all affected URLs and scan the docs for `border-b` to see if there are any stragglers. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Style** * Enhanced accordion components with improved hover state styling for better visual feedback. * **Refactor** * Simplified accordion markup across documentation pages for cleaner, more consistent layout and improved component nesting structure. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-06-23 17:38:47 +00:00
Miranda LimonczenkoandNik Richers	801244463a	chore(docs) Demote h1s in the doc body to avoid multiple h1s (#47061) ... Closes DOCS-875 **Before:** <img width="1465" height="755" alt="Screenshot 2026-06-17 at 2 19 31 PM" src="https://github.com/user-attachments/assets/5768e7d5-0ef9-43a3-8223-e28b340b3c08" /> **Caption:** "Errors" at the bottom of the screen is just as large as the title. The right sidebar shows h3s. Source: https://supabase.com/docs/guides/database/prisma/prisma-troubleshooting#solution-server-has-closed-the-connection **After:** <img width="1409" height="750" alt="Screenshot 2026-06-17 at 2 20 44 PM" src="https://github.com/user-attachments/assets/e39c797c-5b1f-4fce-a1a6-b3eff9e65f18" /> **Caption:** The "Errors" at the bottom of the screen is smaller than the main h1. The right drops the "Solutions" headers. Source: https://docs-git-demote-h1s-in-body-docs-supabase.vercel.app/docs/guides/database/prisma/prisma-troubleshooting#solution-server-has-closed-the-connection ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem The `title` frontmatter generates an `h1`. However, several pages have multiple h1s. ## Fix This PR demotes pages with h1s in the markdown body to h2s and so on. See [a troubleshooting page in production](https://supabase.com/docs/guides/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP) and in [in preview](https://docs-git-demote-h1s-in-body-docs-supabase.vercel.app/docs/guides/troubleshooting/supabase--your-network-ipv4-and-ipv6-compatibility-cHe3BP). ## Future improvements Possibly, we can add a linting rule to prevent this in the future. We'd also want to check that the heading hierarchy is always consistent. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Summary by CodeRabbit * **Documentation** * Updated multiple guides and troubleshooting articles to enforce consistent heading hierarchy and improved section nesting for clearer in-page structure. * Refreshed troubleshooting pages with cleaner table of contents and navigation, including added guide links and re-leveled subsections. * Reformatted Prisma troubleshooting content (including a deprecated redirect) without changing the underlying guidance. * Added a warning about manually setting database connection limits and adjusted related warning/formatting across the max-connections guide. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Nik Richers <nrichers@gmail.com>	2026-06-18 20:42:45 -07:00
Miranda Limonczenko	0d14e05cc5	fix(docs) Format MDX note in one paragraph (#47064) ... Closes DOCS-994 <img width="784" height="171" alt="Screenshot 2026-06-17 at 3 50 27 PM" src="https://github.com/user-attachments/assets/4ff4afc4-2bc8-4a71-95d8-655171b317b6" /> ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## Problem The formatting for `!!! note` breaks out multiple nodes when using `code notation`. ## Fix This PR formats the `Annotation` MDX component so that it groups the components into one paragraph rather than multiple. It also includes a test file, using the example given in the Linear issue. ## Tophatting 1. Go to [Hubspot](https://docs-git-docs-format-note-p-supabase.vercel.app/docs/guides/database/extensions/wrappers/hubspot) in preview. 2. See that the note is formatted correctly. Compare to production. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Tests** * Added a Vitest suite to verify admonition transformation and round-trip markdown parsing, including inline wrapping and preservation of multiple indented content blocks. * **Bug Fixes** * Improved admonition rendering so inline admonition content is grouped into a single paragraph and whitespace-only text is ignored. * When admonitions include multiple sibling blocks, those blocks are kept as separate paragraph children for consistent output. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-06-18 12:00:02 +02:00
3 people	0aa7b4965f	chore(docs) Remove instances of let's to resolve mdx lint warnings (#47013) ... Contributes to DOCS-1052 Contributes to DOCS-1057 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Resolves linting warning for "let's" and adds an exception for product name. ## Tophatting 1. Read the diff and see if changes make sense in context. 2. Run `pnpm lint:mdx`, search for "let's" and see no instances. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Documentation** * Updated instructional copy across multiple AI, authentication, database, functions, realtime, storage, and troubleshooting guides to improve clarity and consistency. * Replaced conversational phrasing (for example, “Let’s…/Let’s see…”) with direct imperatives, tightened example lead-ins, and adjusted a few step explanations for readability. * Refreshed some tutorial text and code-sample presentation in guides (no behavioral changes). * Added/adjusted minor MDX lint guidance in a couple of documents. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Nik Richers <nrichers@gmail.com>	2026-06-17 11:24:59 -07:00
Miranda LimonczenkoandChris Chinchilla	58cb199db0	chore(docs) Replace utilize with use (#47010) ... ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Resolves utilize lint warnings. ## What is the current behavior? Utilize lint warnings are present. ## Tophatting To see that this issue is resolved: 1. See the diff for content clarity. 2. Run `pnpm lint:mdx` to see no more remaining utilize errors. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Documentation - Improved documentation clarity and consistency across platform guides, including AI going-to-prod, custom claims/RLS RBAC, authentication (anonymous, Web3, social login), and database connection/configuration. - Refined technical wording throughout database, realtime, storage, billing, performance, telemetry, and troubleshooting guides (for example, standardizing phrasing like “use” vs “utilize”). - Updated select guidance for clearer wording on database pre-warming and clarified the scope of the Postgres logging note. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Chris Chinchilla <chris.ward@supabase.io>	2026-06-17 09:28:09 -07:00
5 people	608040b8cb	chore(docs) Resolve 'simple' style warnings where applicable (#46966) ... Contributes to DOCS-1052 ## I have read the [CONTRIBUTING.md](https://github.com/supabase/supabase/blob/master/CONTRIBUTING.md) file. YES ## What kind of change does this PR introduce? Resolves MDX linting errors related to "simple" where it applies. There was a couple cases that did not apply. For example, a product with "Simple" in the name. These changes are made in context, either by removing or using a more descriptive synonym like "minimal" or "basic". ## Tophatting 1. Read each of the diffs. 2. See that the text still makes sense in context. For extra due diligence, you can run `pnpm lint:mdx` locally and see the 'simple' errors that remain and whether they are worth addressing. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit ## Summary by CodeRabbit * **Documentation** * Updated many guide, tutorial, and troubleshooting pages with clearer “basic”/“minimal” wording across setup steps, local testing instructions, security cautions, and RLS guidance. * Refined headings, example descriptions, and inline comments for consistency (including deployment, MCP, metrics API, and search/function phrasing). * Improved readability with small snippet formatting tweaks (whitespace plus import/comment ordering) and added a self-hosting debugging note for Envoy admin endpoints via a short-lived `curl` container. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> Co-authored-by: Chris Chinchilla <chris.ward@supabase.io> Co-authored-by: Nik Richers <nrichers@gmail.com>	2026-06-16 21:45:55 +00:00