Next.js Guide

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

The renoun toolkit provides file system querying, 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

Next, we need to install the renoun package dependencies:

npm install renoun shiki@1.26.0 ts-morph@25.0.0
pnpm add renoun shiki@1.26.0 ts-morph@25.0.0
bun add renoun shiki@1.26.0 ts-morph@25.0.0
yarn add renoun shiki@1.26.0 ts-morph@25.0.0

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"
  }
}

Custom Server

Alternatively, if you don’t want to use the CLI, the renoun WebSocket server can be started manually using the createServer function:

renoun-server.mjs
import { createServer } from 'renoun/server'

const server = await createServer()

Webpack Configuration

If you are using Webpack to bundle your Next.js project, you will need to configure the resolve.alias option to support ESM files. This will allow you to import renoun components and utilities without errors:

next.config.mjs
export default {
  webpack(config) {
    config.resolve.extensionAlias = {
      '.js': ['.ts', '.tsx', '.js'],
    }
    return config
  },
}

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:

next.config.mjs
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.

Querying the File System

The Directory utility in renoun lets you query and load files from your project’s file system. For example, to create a list of blog posts or documentation pages we can query all MDX files in a directory:

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

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

Next, we can use the Directory instance to render the contents of our MDX files:

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.

A directory entry’s getPath method can generate a route path for each entry. For example, to generate a link to each post, you can iterate over the entries and use the entry’s getPath method:

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(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 query other file system entries or use one of the many components available to enhance your content and documentation.

Last updated