Getting Started

Designed for building content and documentation sites, renoun is a versatile toolkit. This guide will help you set up renoun and start using it in your project.

Installation

First, install renoun using your preferred package manager:

npm install renoun

pnpm add renoun

bun add renoun

yarn add renoun

Configuration

The renoun CLI can be used alongside your framework. For example, when using Next.js, prepend the CLI to your Next.js dev and build commands in your project’s package.json:

{
  "scripts": {
    "dev": "renoun next dev",
    "build": "renoun next build"
  }
}

Then start the development server:

npm run dev

Prepending the renoun CLI ensures that the renoun process starts before your framework’s server. The CLI starts a web socket server that will watch for changes to the file system and communicates with renoun components.

Creating a Collection

The Collection utility is a core concept in renoun. This allows you to query a collection of files from the file system. For example, to create a list of blog posts or documentation pages we can query all the MDX files in a directory:

import { Collection } from 'renoun/collections'

const posts = new Collection({
  filePattern: 'posts/*.mdx',
})

We can then constrain the collection by providing types for the exports we’re interested in querying:

import { Collection } from 'renoun/collections'
import type { MDXContent } from 'renoun/mdx'

const posts = new Collection<{
  default: MDXContent
}>({
  filePattern: 'posts/*.mdx',
})

Now we can use this collection to render the contents of our MDX files:

import { Collection } from 'renoun/collections'
import type { MDXContent } from 'renoun/mdx'

const posts = new Collection<{
  default: MDXContent
}>({
  filePattern: 'posts/*.mdx',
})

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const post = await posts.getSource((await params).slug)

  if (!post) {
    return <div>Post not found</div>
  }

  const Content = await post.getExport('default').getValue()

  return <Content />
}

This will create a collection of all MDX files in the posts directory and render them based on the provided slug. Collections are not limited to MDX files and can be used with any file type.

Generating Links

A source’s getPath method is used to generate a URL path for each source in the collection. For example, to generate a link to each post, you can map over the collection using getSources and use the getPath method on a source to generate a list of links:

import { Collection } from 'renoun/collections'
import type { MDXContent } from 'renoun/mdx'
import Link from 'next/link'

const posts = new Collection<{
  default: MDXContent
}>({
  filePattern: 'posts/*.mdx',
})

export default async function Page() {
  const allPosts = await posts.getSources({ depth: 1 })

  return (
    <>
      <h1>Blog</h1>
      <ul>
        {allPosts.map(async (post) => {
          const path = post.getPath()

          return (
            <li key={path}>
              <Link href={path}>{post.getTitle()}</Link>
            </li>
          )
        })}
      </ul>
    </>
  )
}

Authoring Content

renoun helps with authoring MDX using the @renoun/mdx package, allowing you to write content with a mix of Markdown and React components. It is not required, but provides a set of useful defaults.

Here’s an example of how you might structure a blog post:

---
title: Build a Button Component in React
date: 2024-03-01
summary: Learn how to build a reusable Button component in React that can be used across your application.
tags:
  - react
  - design systems
---

In modern web development, creating reusable UI components is a must for efficiency and scalability. React, with its component-based architecture, allows developers to build encapsulated components that manage their own state and can be reused throughout applications.

## Building the Button Component

Let's start by creating our Button component:

```tsx
import React from 'react'

export function Button({ label, onClick, className }) {
  return (1
    <button className={className} onClick={onClick}>
      {label}
    </button>
  )
}
```

Validating Exports

By using schemas, you can validate module exports and ensure they remain consistent and properly documented. The following is an example of how to validate a module export with renoun using Zod.

In our Button component example, we can validate the front matter of the MDX file at the call site of our collection using a schema:

import { Collection } from 'renoun/collections'
import type { MDXContent } from 'renoun/mdx'
import { z } from 'zod'

const frontmatterSchema = z.object({
  title: z.string(),
  date: z.coerce.date(),
  summary: z.string().optional(),
  tags: z.array(z.string()).optional(),
})

export const PostsCollection = new Collection<{
  default: MDXContent
  frontmatter: z.infer<typeof frontmatterSchema>
}>({
  filePattern: '*.mdx',
  baseDirectory: 'posts',
  schema: {
    frontmatter: frontmatterSchema.parse,
  },
})

Here we define a schema for the front matter of our MDX files and use it to validate the front matter of each file in our collection. This ensures that each file adheres to the schema and provides type safety when accessing the front matter.

Enhancing with Components

The renoun toolkit provides several built-in components to enhance your documentation. For example, you can use the APIReference component to easily document your APIs:

import { APIReference } from 'renoun/components'

<APIReference source="components/Card.tsx" />

Explore more components to enhance your documentation.

Conclusion

By following this guide, you should now have a basic setup running renoun in your Next.js project. You can now start writing content and documentation with renoun’s powerful toolkit. If you have any questions or need further assistance, feel free to reach out on Discord or GitHub.