Next.js Guide

The renoun toolkit enhances the Next.js framework with powerful content and documentation features.

The renoun toolkit provides collections, syntax highlighting, and api references, making it easier to create accurate and engaging content for blogs, documentation, and design systems powered by Next.js.

Install

To use renoun with Next.js, start with an existing or new Next.js project. If you don’t have a project yet, you can create one using the Next.js create command:

npx create-next-app@latest

Setup

Modify the next scripts located in the project’s package.json file to use the renoun CLI. This will ensure that the renoun process starts before your Next.js server:

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

MDX (Optional)

To enable writing MDX content in your Next.js application, we will use the @next/mdx package. This package allows you to author MDX content in your Next.js project. Additionally, you can use the pre-configured remarkPlugins and rehypePlugins from renoun/mdx.

First, install the Next.js MDX plugin:

npm install @next/mdx
pnpm add @next/mdx
bun add @next/mdx
yarn add @next/mdx

Now, add the plugin to your next.config file while optionally including the pre-configured remarkPlugins and rehypePlugins from renoun/mdx:

import createMDXPlugin from '@next/mdx'
import { remarkPlugins, rehypePlugins } from 'renoun/mdx'

const withMDX = createMDXPlugin({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins,
    rehypePlugins,
  },
})

export default withMDX({
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
})

MDX Code Blocks

Use the MDXComponents export to override the pre and code components in your project’s mdx-components.tsx file:

mdx-components.tsx
import { MDXComponents } from 'renoun/components'

export function useMDXComponents() {
  return MDXComponents
}

This forwards the meta information added from the @renoun/mdx rehype plugin to the CodeBlock component.

Creating Collections

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',
})

Finally, 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.

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>
    </>
  )
}

Collections are not limited to MDX files and can be used with any file type.

Start

Now you can start your Next.js server with renoun enabled:

npm run dev

Congratulations, you’ve successfully set up renoun with Next.js! You can now create collections or use one of the many components available to enhance your content and documentation.

Last updated