Swingset

Swingset is a drop-in component documentation system for Next.js's App Router and React Server Components that generates documentation routes from MDX files placed next to your components.

What is Swingset?

Swingset is a tool that adds a documentation route group to a Next.js application, rendering MDX documentation alongside your component code. It takes a Next.js project and a configured componentRoot directory as input and produces an auto-generated documentation site with a route group named (swingset). The project is available on GitHub as the npm package swingset, and the repository is currently archived — the banner states it is deprecated and no longer maintained, with no further updates, bug fixes, or support.

Key Features

• App Router native — Built specifically for Next.js's App Router and React Server Components; running swingset bootstrap generates a (swingset) route group containing layout.tsx, a page.tsx, and a catch-all [...path] page.
• Component documentation with MDX — Create a docs.mdx file next to your component source file, and Swingset renders it as documentation.
• Automatic prop extraction — The exported PropsTable component accepts a component prop and displays prop metadata automatically when the component is imported into MDX.
• Standalone documentation pages — Place .mdx files in /app/(swingset)/swingset/docs/ to render custom documentation pages beyond component docs.
• Custom themes — Configure a theme option in next.config.mjs (e.g. theme: 'swingset-theme-custom') to control rendering; by default Swingset only exposes data, letting you build a custom presentation.
• Remark and rehype plugin support — Pass remarkPlugins and rehypePlugins in the config; the example shows adding remarkGfm for GitHub Flavored Markdown.
• Integrates with @next/mdx — Supports the same mdx-components.ts file at the root of the application, making custom components declared there available in Swingset docs.
• Storybook-friendly — Documentation pages are treated as modules, so you can import Storybook stories directly into MDX, e.g. import * as stories from './Button.stories' and render <stories.Primary />.

Who should use Swingset?

• Next.js developers building a component library and needing docs that live next to the source files.
• Design system teams that want automatic prop tables and MDX-based documentation tied to the App Router.
• Teams already using Storybook who want to embed story examples directly into generated documentation pages.

What can you do with Swingset?

• Component library maintainers: Place a docs.mdx beside each component and get a browsable docs section with prop tables, without maintaining a separate docs site.
• Documentation authors: Add standalone .mdx pages under the generated docs directory and control them with custom themes.
• Storybook users: Import story modules into documentation MDX to render live component examples.

How does Swingset work?

1. Install with npm install swingset.
2. Import withSwingset in next.config.mjs and pass options including componentRoot and an optional theme.
3. Run swingset bootstrap to generate the (swingset) route group inside the app directory.
4. Write docs.mdx files in the components directory and configure remark/rehype plugins as needed.

Pros and cons

• Pros: Automatic prop extraction; App Router and RSC support; custom themes; remark/rehype plugin integration; works with Storybook stories.
• Cons: The repository is archived and no longer maintained — no more bug fixes, updates, or support will be provided.

FAQ

Is Swingset still maintained?

No. The GitHub repository displays an archive notice stating the project is deprecated, will not receive further updates, bug fixes, or support, and recommends looking for alternative solutions or successor projects.

How do I install Swingset?

Install the npm package with npm install swingset, then import withSwingset in next.config.mjs and run swingset bootstrap to generate the documentation route group.

Does Swingset support the Pages Router?

The documentation only describes support for the App Router and React Server Components. No Pages Router integration is mentioned.

Can I use Swingset with Storybook?

Yes. Swingset documentation pages are treated as modules, so you can import Storybook story files into your MDX and render them as live examples.

How do I customize the appearance of my docs?

Set the theme option in the withSwingset config object in next.config.mjs. By default, Swingset exposes data only, so a custom theme is needed to control how documentation renders.