## Summary
- `contentlayer2@0.4.6` is unmaintained and drags in a heavy, stale
dependency graph (esbuild pinned to 0.17–0.20, mdx-bundler, old
`@opentelemetry/core`) that was the recurring source of vuln bumps.
- Migrates all three apps that used it — `design-system`, `ui-library`,
`learn` — to [Velite](https://velite.js.org), preserving the generated
typed `allDocs`/`Doc` collection and the `body.code` + `useMDXComponent`
runtime via a small shared local hook.
- Same MDX pipeline (remark-gfm, remark-code-import, rehype-slug,
rehype-pretty-code w/ Shiki compat + local theme,
rehype-autolink-headings, custom
`__rawString__`/`__src__`/`__event__`/`__style__` visitors) ported 1:1
into each app's `velite.config.js`.
- `learn`'s extra frontmatter fields (`chapterNumber`, `explore`,
`courseHero`) are now backed by real Velite/Zod schema types, so the
`(doc as any)` casts in `get-next-page.ts` / `get-current-chapter.ts` /
the doc page could be dropped.
- `next.config.mjs` no longer wraps with `withContentlayer`; since
Velite has no Next.js webpack-plugin equivalent, each app's `dev` script
now runs `velite dev` and `next dev` in parallel via `npm-run-all`.
Ref:
[FE-3861](https://linear.app/supabase/issue/FE-3861/migrate-off-contentlayer2-learn-ui-library-design-system-to-shed)
## Test plan
- [x] `pnpm build:content` (Velite build) succeeds for all three apps
- [x] `pnpm typecheck` passes for all three apps
- [ ] Manual smoke test of `pnpm dev` for each app in a browser (docs
pages render, TOC, copy-button, code highlighting)
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
* **Improvements**
* Improved content generation across documentation, learning materials,
and the UI library for more consistent pages.
* Preserved MDX rendering, navigation, table of contents, course
metadata, source previews, and component examples.
* Improved consistency when displaying documentation and interactive
examples.
* Improved application loading by optimizing how interface components
are delivered.
* **Chores**
* Streamlined content compilation and development workflows across the
design system, learning area, and UI library.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
## 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?
The apps/learn and apps/ui-library applications fail to start in
development mode (pnpm dev) and during production builds. This is caused
by a conflict between Next.js 16, which enables Turbopack by default,
and the Contentlayer plugin, which injects a custom Webpack
configuration.
Error: ⨯ ERROR: This build is using Turbopack, with a webpack config and
no turbopack config.
## What is the new behavior?
This PR adds the required turbopack configuration block to the
next.config.mjs files for both apps/learn and apps/ui-library.
It explicitly enables Turbopack while providing the raw-loader rules for
*.md files. This ensures that Contentlayer can correctly process
Markdown content under Turbopack.
Reference: This fix follows the established pattern used in the Design
System
[#39890](https://github.com/supabase/supabase/pull/39890/changes#diff-07283a8ef455ee1c6769cb991039300209d540dd727e3434b070d03075ced551)
and Studio to handle the Contentlayer/Turbopack conflict.
<img width="1429" height="856" alt="image"
src="https://github.com/user-attachments/assets/253ad0da-6420-441b-874c-3394b21b9ae5"
/>
---
## Additional context
Verified that `pnpm dev` starts successfully for both apps after the
change.
Verified that `pnpm build` completes successfully using the Turbopack
engine.
<img width="1429" height="856" alt="image"
src="https://github.com/user-attachments/assets/11efbd5c-57c5-425a-baca-f0198d0e7d91"
/>
<img width="1429" height="856" alt="image"
src="https://github.com/user-attachments/assets/17ec4f25-c19e-4f6b-bcc6-d898b7b20815"
/>
System: macOS | Node: v24.13.1 | Next.js: 16.2.3
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
## Release Notes
* **Chores**
* Updated build configuration to optimize Markdown file processing in
the application build system across multiple packages.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
wip
<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit
# Release Notes
* **New Features**
* Added a new Learn application offering foundational Supabase courses
with interactive documentation
* Courses include Architecture, Authentication, Data Fundamentals,
Security, Storage, Realtime, and Edge Functions
* Chapter tracking and progress indicators for course completions
* Responsive sidebar navigation with search/command menu
* Theme switching support (light, dark, classic dark modes)
* Mobile-friendly course interface
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
---------
Co-authored-by: Alan Daniel <stylesshjs@gmail.com>
Co-authored-by: Claude Sonnet 4.5 <noreply@anthropic.com>
Ivan Vasilov