Configuration

Configure renoun in your project.

This guide will help you configure renoun and better understand all of the configuration options. We’ll cover:

  • Setting up the RootProvider
  • Selecting themes (bundled or custom)
  • Configuring color modes (light/dark) with optional overrides
  • Loading languages for syntax highlighting
  • Configuring git links and the canonical site URL
  • Enabling debug logs

RootProvider

Configure renoun at the root of your application using the RootProvider component. This component must wrap the html element and will provide renoun’s configuration to the entire application.

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      git="souporserious/renoun"
      siteUrl="https://renoun.dev"
      theme="theme.json"
    >
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Themes

renoun provides accurate syntax highlighting using TextMate grammars and VS Code–compatible color themes. To keep install size small, renoun does not bundle any themes by default. You can either reference a local theme JSON file or install the optional tm-themes package to load a bundled theme by name.

For more information on TextMate grammars and themes, see the VS Code syntax highlighting guide and the TextMate grammar reference.

Predefined Themes

To use a predefined theme, first install the tm-themes package:

npm install --save-dev tm-themes

Now you can define a supported theme by name through RootProvider:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider theme="nord">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Custom Themes

To use a custom theme, reference a JSON file that defines a VS Code compatible theme:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider theme="theme.json">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Multiple Themes

You can also specify multiple themes, the first theme defined in the object will be the default:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      theme={{
        light: 'vitesse-light',
        dark: 'vitesse-dark',
      }}
    >
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

To use a specific default theme, append a data-theme attribute to the html element:

<html data-theme="dark">
  ...
</html>

The useThemePicker hook can be used to build a select menu or toggle for choosing from the configured themes:

'use client'
import { useThemePicker } from 'renoun'

export function ThemePicker() {
  const [theme, setTheme] = useThemePicker()

  return (
    <select value={theme} onChange={(event) => setTheme(event.target.value)}>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
    </select>
  )
}

Integrating with Other Theme Providers

By default, a small script that manages the theme is included in the head of the document. This script sets the data-theme attribute on the html element based on local storage. If you are using another theming provider that already manages the theme, you can disable renoun’s theme script by setting the includeThemeScript prop to false to avoid conflicts:

import { RootProvider } from 'renoun'
import { ThemeProvider } from 'next-themes'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      theme={{ light: 'nord', dark: 'nord' }}
      includeThemeScript={false}
    >
      <html>
        <body>
          <ThemeProvider>{children}</ThemeProvider>
        </body>
      </html>
    </RootProvider>
  )
}

Overriding Themes

To override a theme, you can provide a tuple that specifies the theme values to override:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      theme={{
        light: 'vitesse-light',
        dark: [
          'vitesse-dark',
          {
            colors: {
              'editor.background': '#000000',
              'panel.border': '#666666',
            },
          },
        ],
      }}
    >
      {children}
    </RootProvider>
  )
}

This accepts a subset of a VS Code theme to override, specifically the colors, tokenColors, and semanticTokenColors properties.

Languages

Use the languages prop to define which grammars are available to CodeBlock and CodeInline.

Default Languages

The following languages are loaded by default:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      languages={[
        'css',
        'js',
        'jsx',
        'ts',
        'tsx',
        'md',
        'mdx',
        'shell',
        'json',
        'html',
      ]}
    >
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Additional Languages

To add support for additional languages, install the optional tm-grammars package and list the languages you want in the languages array.

npm install --save-dev tm-grammars

Now you can reference languages by name via RootProvider:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider languages={['python', 'rust', 'go']}>
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Control which IDE is used when constructing editor URIs by setting the editor prop. Any editor supported by getEditorUri can be provided, including VS Code compatible editors and JetBrains IDEs.

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider editor="cursor">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Git Information

Set git on RootProvider to enable edit/source links and canonical URLs:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider
      git={{
        source: 'https://github.com/souporserious/renoun',
        branch: 'main',
        host: 'github',
        owner: 'souporserious',
        repository: 'renoun',
        baseUrl: 'https://github.com',
      }}
    >
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Shorthand Syntax

You can also use a shorthand syntax to specify the git information:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider git="souporserious/renoun">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

This will be parsed into the following object:

{
  "source": "https://github.com/souporserious/renoun",
  "branch": "main",
  "host": "github",
  "owner": "souporserious",
  "repository": "renoun",
  "baseUrl": "https://github.com"
}

A specifier can also include a branch, host, owner, repository, and base URL:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider git="pierre:souporserious/renoun@docs">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Site URL

Provide a siteUrl so sitemaps and other absolute URLs are generated correctly:

import { RootProvider } from 'renoun'

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <RootProvider siteUrl="https://renoun.dev">
      <html>
        <body>{children}</body>
      </html>
    </RootProvider>
  )
}

Debug Logs

You can enable internal debug logging by setting the RENOUN_DEBUG environment variable. This is helpful when investigating issues related to the renoun CLI, the WebSocker server, and other internal utilities.

  • Allowed values:
    • true or 1 : enable the most verbose logging
    • error , warn , info , debug , trace : set a specific minimum level
    • false or 0 : logging disabled (default)

Examples:

# Most verbose logging
RENOUN_DEBUG=true renoun next dev

# Only info and above
RENOUN_DEBUG=info renoun next dev
Last updated