Getting Started

Learn how to configure and start using renoun.

This guide will help you get started using renoun in your project. Designed as a powerful toolkit for building documentation and authoring content with MDX, renoun offers a suite of utilities and components to create beautiful, interactive documentation tailored exactly to your needs.

In this getting started guide, Next.js will be used as an example. However, renoun works with any framework or bundler that supports React Server Components. For additional examples, please see the guides section.

Installation

First, install renoun using your preferred package manager and additionally next or a compatible framework if you haven’t already:

npm install renoun

pnpm add renoun

bun add renoun

yarn add renoun

Configuration

CLI

A CLI is included with renoun to help isolate the processing required for syntax highlighting and resolving type information. This greatly improves performance of these operations by keeping them separate from your application’s development and build processes.

To use the CLI, prepend renoun 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 WebSocket server that will watch for changes to the file system and communicates with renoun components and utilities.

Path Aliases

To simplify imports, you can optionally set up path aliases in your project’s tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["*"]
    }
  }
}

With this configuration, you can now import files using the @/ alias which we will use in the upcoming examples.

MDX Content

The renoun toolkit 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 to use, but provides a set of useful plugins.

To start, create a new directory in your project called posts and add a new file called build-a-button-component-in-react.mdx:

---
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 (
    <button className={className} onClick={onClick}>
      {label}
    </button>
  )
}
```

We are using YAML front matter to define metadata for the post, such as the title, date, summary, and tags. This metadata can be used to show a list of posts, filter by tags, or display the post’s title and date.

Querying the File System

The Directory class is a core utility in renoun. This allows you to easily query and render files and directories within a file system. To create a list of blog posts, query all of the MDX files in the posts directory we created earlier:

import { Directory } from 'renoun/file-system'

const posts = new Directory({
  path: 'posts',
  include: '*.mdx',
})

Now we can use the configured directory to render the contents of our MDX files by querying them from the file system. Create a new file in the app/posts directory called [slug].tsx and add the following:

import { Directory } from 'renoun/file-system'

const posts = new Directory({
  path: 'posts',
  include: '*.mdx',
})

export default async function Page({
  params,
}: {
  params: Promise<{ slug: string }>
}) {
  const slug = (await params).slug
  const post = await posts.getFile(slug, 'mdx')
  const Content = await post.getExportValue('default')

  return <Content />
}

This will create a collection of every MDX file in the posts directory and render the page based on the provided slug.

Loaders

By default, the Directory class will load files using the MDX compiler. However, if you are using a bundler like Webpack, Turbopack, or Vite, it is recommended to define a loader that resolves the module. This is especially useful for MDX files, which are often processed by the bundler’s loader.

Use the loaders option in the Directory constructor to assign a specific loader for each file type. In the posts directory, for instance, you can use a dynamic import as the loader to ensure that the MDX files are processed by the bundler:

import { Directory } from 'renoun/file-system'

const posts = new Directory({
  path: 'posts',
  include: '*.mdx',
  loaders: {
    mdx: (path) => import(`@/posts/${path}.mdx`),
  },
})

Generating Links

A File System entry’s getPath method is used to generate a route path for each entry in the directory. To generate a link to each post, map over the directory’s entries using getEntries and then use the entry’s getPath method to generate a list of links:

import { Directory } from 'renoun/file-system'
import Link from 'next/link'

const posts = new Directory({
  path: 'posts',
  include: '*.mdx',
  loaders: {
    mdx: (path) => import(`@/posts/${path}.mdx`),
  },
})

export default async function Page() {
  const allPosts = await posts.getEntries()

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

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

Validating Exports

Alongside file loading, renoun can validate module exports to ensure that source code is documented and exported according to a consistent schema. This is especially beneficial in larger projects where multiple developers collaborate on the same codebase.

Below is an example demonstrating how to validate a frontmatter object exported from a module using Zod:

import { Directory, withSchema } from 'renoun/file-system'
import { z } from 'zod'

export const posts = new Directory({
  path: 'posts',
  include: '*.mdx',
  loaders: {
    mdx: withSchema(
      {
        frontmatter: {
          title: z.string(),
          date: z.coerce.date(),
          summary: z.string().optional(),
          tags: z.array(z.string()).optional(),
        },
      },
      (path) => import(`@/posts/${path}.mdx`)
    ),
  },
})

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

import { posts } from './posts.ts'

const post = await posts.getFile('build-a-button-component-in-react.mdx')
const frontmatter = await post.getExportValue('frontmatter')
const { title, date, summary, tags } = frontmatter

Enhancing with Components

The renoun toolkit provides several built-in components to enhance your documentation like APIReference and CodeBlock. For example, you can use the APIReference component to document all exports from a module:

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.