Getting Started

Learn how to set up renoun in your project.

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

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 following examples.

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. For example, to create a list of blog posts or documentation pages we can query all the MDX files in a directory:

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

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

We can then add a loader to the directory that resolves the module of each MDX file using a dynamic import:

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

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

Now we can use the configured directory to render the contents of our MDX files by querying them from the file system:

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

const posts = new Directory({
  path: 'posts',
  include: '*.mdx',
  loaders: {
    mdx: (path) => import(`@/posts/${path}.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 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 file system entry’s getPath method is used to generate a route path for each entry in the directory. For example, to generate a link to each post, you can 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>
    </>
  )
}

Authoring 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, 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 (
    <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.

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

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 the front matter of each file in the posts directory. This ensures that each file adheres to the schema and provides type safety when accessing the frontmatter export.

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.