Files
supabase/apps/ui-library/middleware.ts
T
3e79df3ece feat(library): serve the block catalog as Markdown and harden the exporter (#50370)
## 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, bug fix.

Part 3 of 6 in a stack that splits the library redesign into reviewable
pieces.

## What is the current behavior?

An agent can already fetch any guide as Markdown, but has no way to find
out what guides exist: the entry point is a rendered React page.

The exporter also fails quietly in ways that ship wrong output rather
than failing the build:

- An unknown component silently unwraps to its children, so a component
rename drops its rendered content.
- A registry item that cannot be read produces a page with no file
listing.
- A link to a missing page produces a 404 URL.
- An unrecognized install framework produces a plausible command for the
wrong CLI.
- Only absolute `/library/docs` links are rewritten, so in-page anchors
and sibling links break in the export.

## What is the new behavior?

`/library` negotiates Markdown the same way the guides do — `Accept:
text/markdown`, or an explicit `/library/index.md` — and returns a
categorized catalog with every block, its description, its framework
variants, and a link to each guide's Markdown.

`config/library.ts` is the single catalog description the generator
reads, and a test ties it to the content directory in both directions: a
guide cannot be added without a catalog entry, or listed without a
guide.

Each quiet failure above now throws, and links resolve against the page
they appear on and are checked against the set of published documents.

```bash
curl -H 'Accept: text/markdown' https://supabase.com/library
```

## Additional context

`config/library.ts` also carries the category and preview metadata the
redesigned homepage consumes in the last PR of the stack; here it is
exercised by the Markdown index and its test.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

- **New Features**
- Added a browsable library catalog covering categories, blocks, starter
apps, and supported frameworks.
- Added Markdown versions of the library homepage and documentation for
compatible tools and workflows.
- Added framework-aware links and expanded registry information,
including dependencies and source details.
- Markdown requests now work for the homepage and documentation, while
browser requests continue receiving HTML.

- **Bug Fixes**
- Improved document link handling, metadata validation, slug
consistency, and detection of duplicate or missing documentation
entries.

- **Tests**
- Added coverage for catalog routes, Markdown generation, homepage
negotiation, document parsing, and framework-specific links.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: Ivan Vasilov <vasilov.ivan@gmail.com>
2026-09-22 14:14:04 +02:00

70 lines
2.1 KiB
TypeScript

import { negotiateMarkdown, type MarkdownDecision } from 'common/markdown-negotiation'
import { NextResponse, type NextRequest } from 'next/server'
import MARKDOWN_SLUGS from '@/public/markdown/manifest.json'
const BASE_PATH = process.env.NEXT_PUBLIC_BASE_PATH ?? '/library'
const DOCS_PATH = `${BASE_PATH}/docs`
const MARKDOWN_SLUG_SET = new Set(MARKDOWN_SLUGS)
// The homepage catalog, generated by scripts/build-markdown-index.ts.
const HOME_PATHS = new Set([BASE_PATH, `${BASE_PATH}/`, `${BASE_PATH}/index.md`])
export function middleware(request: NextRequest) {
const url = new URL(request.url)
const { pathname } = url
// Server Actions POST to the page URL with `Accept: text/x-component`, which
// matches none of the types these routes negotiate and would 406. Let Next.js
// handle them.
if (request.headers.get('next-action')) {
return NextResponse.next()
}
const acceptHeader = request.headers.get('accept') ?? ''
if (HOME_PATHS.has(pathname)) {
return respond(
negotiateMarkdown(
{ acceptHeader },
{ hasMarkdownVariant: true, isMarkdownSuffix: pathname.endsWith('.md') }
),
url,
`${BASE_PATH}/api/index-md`
)
}
if (!pathname.startsWith(`${DOCS_PATH}/`)) {
return NextResponse.next()
}
const isMdSuffix = pathname.endsWith('.md')
const slug = pathname.replace(`${DOCS_PATH}/`, '').replace(/\.md$/, '')
const decision = negotiateMarkdown(
{ acceptHeader },
{ hasMarkdownVariant: MARKDOWN_SLUG_SET.has(slug), isMarkdownSuffix: isMdSuffix }
)
return respond(decision, url, `${BASE_PATH}/api/docs-md/${slug}`)
}
function respond(decision: MarkdownDecision, url: URL, markdownPathname: string) {
if (decision === 'not-acceptable') {
return new NextResponse('Not Acceptable', {
status: 406,
headers: { 'Cache-Control': 'no-store', Vary: 'Accept' },
})
}
if (decision === 'markdown') {
const rewriteUrl = new URL(url)
rewriteUrl.pathname = markdownPathname
return NextResponse.rewrite(rewriteUrl)
}
return NextResponse.next()
}
export const config = {
matcher: ['/', '/index.md', '/docs/:path*'],
}