Next.js

Renoun enhances Next.js with features like collections, MDX support, syntax highlighting, and type documentation, making it easier to create accurate and engaging content for blogs, documentation, and design systems.

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

This command is necessary to enable Renoun features in your Next.js project. The renoun CLI starts a WebSocket server that communicates with components and utilities in your project to provide performant syntax highlighting and code analysis.

MDX (Optional)

To enable writing MDX content in your Next.js application, we will use the @next/mdx and @renoun/mdx packages. These packages allow you to author MDX content in your Next.js project and ship with pre-configured plugins that include reasonable defaults.

This step is optional and only necessary if you plan to use MDX in your project. Additionaly, you can skip adding the @renoun/mdx package if you want to configure your own MDX plugins.

First, install the Next.js MDX plugin and the Renoun MDX plugins:

npm install @next/mdx @renoun/mdx

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

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

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

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

Webpack Configuration

Finally, we need to configure Webpack and alias js files since renoun is an ESM package and will otherwise error. We also need to silence critical dependency warnings for @ts-morph/common as these come from the ts-morph package renoun depends on. This is necessary to prevent warnings from appearing in the console:

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

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

export default withMDX({
  output: 'export',
  pageExtensions: ['js', 'jsx', 'ts', 'tsx', 'md', 'mdx'],
  webpack(config) {
    /* Resolve .js files to .ts and .tsx */
    config.resolve.extensionAlias = {
      '.js': ['.ts', '.tsx', '.js'],
    }

    /* Silence critical dependency warnings for @ts-morph/common */
    config.plugins.push(
      new webpack.ContextReplacementPlugin(
        /\/(@ts-morph\/common)\//,
        (data) => {
          for (const dependency of data.dependencies) {
            delete dependency.critical
          }
          return data
        }
      )
    )
    return config
  },
})

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