Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/hashicorp/swingset
drop-in component library for next.js
https://github.com/hashicorp/swingset
Last synced: about 2 months ago
JSON representation
drop-in component library for next.js
- Host: GitHub
- URL: https://github.com/hashicorp/swingset
- Owner: hashicorp
- License: mpl-2.0
- Created: 2020-08-26T22:09:40.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-01-22T10:49:04.000Z (8 months ago)
- Last Synced: 2024-06-25T15:49:09.586Z (3 months ago)
- Language: TypeScript
- Homepage: https://swingset-example.vercel.app
- Size: 2.64 MB
- Stars: 76
- Watchers: 11
- Forks: 11
- Open Issues: 35
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Codeowners: CODEOWNERS
Awesome Lists containing this project
README
# swingset
Welcome to Swingset. Swingset is a drop-in component documentation system built for Next.js's App Router and React Server Components.
> **Note**
> Swingset is currently under active development. We're actively iterating on the core features and APIs, and some things may change.
## Installation
Install `swingset` with your package manager of choice:
```
npm install swingset
```
Import the plugin in your `next.config.mjs` file:
```js
// next.config.mjs
import withSwingset from 'swingset'
export default withSwingset({
componentRoot: './components',
theme: 'swingset-theme-custom',
})()
```
## Features
### App Router native
Swingset is built for the new App Router and React Server Components. Running the bootstrap command will generate a route group for swingset:
```
$ swingset bootstrap
Generating swingset route group...
Success! Route group created:
(swingset)
├ /layout.tsx
└ /swingset
├ /page.tsx
└ /[...path]
└ /page.tsx
```
### Component documentation
Document your components with MDX by placing a `docs.mdx` file next to your component source:
```
components/
button/
docs.mdx
index.tsx
```
#### Component prop extraction
Swingset automatically exposes prop metadata for components imported into your documentation.
```typescript
```
### Custom documentation
Swingset also supports standalone documentation pages. By default, `.mdx` files in `/app/(swingset)/swingset/docs/` are rendered.
### Custom themes
By default, Swingset only exposes the data necessary to fully render your documentation content. Swingset can be configured with a custom `theme` to control rendering.
```js
// next.config.mjs
import withSwingset from 'swingset'
export default withSwingset({
componentRoot: './components',
theme: 'swingset-theme-custom',
})()
```
### Custom remark and rehype plugins
Want to add support for GitHub Flavored Markdown? Swingset accepts `remark` and `rehype` plugins.
- [x] Add `remarkGfm`
- [x] Restart your server
- [ ] Render task lists!
```js
// next.config.mjs
import withSwingset from 'swingset'
import remarkGfm from 'remark-gfm'
export default withSwingset({
componentRoot: './components',
remarkPlugins: [remarkGfm],
})()
```
### Integrates with `@next/mdx`
Swingset integrates with `@next/mdx` by supporting the same `mdx-components.ts` file at the root of your application. Swingset will make the custom components declared there available.
### Use with Storybook
Documentation pages within Swingset are treated as modules. This means that you can import other modules into your `.mdx` files as you would any other JavaScript file. This works great if you leverage Storybook for component development, as stories are directly consumable from your documentation:
```tsx
import * as stories from './Button.stories'
# This is the Primary story
```
## Contributing
See [CONTRIBUTING.md](/CONTRIBUTING.md).