renoun

The examples/ directory contains several implementations showcasing different use cases for the renoun SDK:

• Blog: A minimal project using @renoun/blog that overrides the posts/ directory. It demonstrates the CLI application flow and requires only package.json and local content.
• Docs: A complete documentation site featuring MDX support, custom UI components, Tailwind CSS styling, and Next.js configuration.
• Package: An example of a package documentation site, demonstrating component library structures, custom hooks, MDX documentation, and component examples.
• Blog (Advanced): An example focused on content management, showing MDX support, custom collections, and post organization.

Renoun provides several capabilities for turning codebases into structured data:

• File Querying: Query files (MDX, MD, TS) as if they were structured data.
• Navigation Generation: Automatically generate navigations and indexes based on your file system structure.
• Module Loading: Load and render module exports from your files.
• Schema Validation: Validate frontmatter and module exports using schemas to ensure data integrity.

Renoun uses a security model to ensure that file discovery and path resolution remain within the bounds of your project. The CLI uses an internal environment variable RENOUN_RUNTIME_DIRECTORY to locate the runtime directory, but it validates this variable using three specific checks to prevent path traversal and unauthorized access:

If any check fails, renoun ignores the environment variable and falls back to normal path resolution.

For advanced use cases where you want to render an element once and then extract multiple formats (e.g., a canvas, a PNG blob, and a WebP URL), use the screenshot() function to create a ScreenshotTask. This avoids redundant rendering work.

import { screenshot } from '@renoun/screenshot'

const shot = screenshot(element, {
  includeFixed: 'intersecting',
  scale: window.devicePixelRatio,
})

// Reuse the same render for multiple encodings
const canvas = await shot.canvas()
const pngBlob = await shot.blob({ format: 'png' })
const webpUrl = await shot.url({ format: 'webp', quality: 0.9 })

When running the Workbench via renoun dev, the CLI copies the workbench template into a temporary runtime and applies specific local files as overrides. You can customize the application by providing your own implementations in the following directories:

• components/: Component source files, examples, and documentation.
• hooks/: Hook implementations and exports.
• ui/: UI overrides for entry layouts and navigation.

The File class implements standard Web Blob/File methods, allowing you to stream content without buffering the entire file into memory.

Available methods:

• slice(start, end): Returns a slice of the file.
• stream(): Returns a ReadableStream.
• arrayBuffer(): Returns the content as an ArrayBuffer.
• text(): Returns the content as text.

These can be used directly with fetch for uploads or in server responses for efficient partial content (Range) serving.

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

const directory = new Directory({ path: 'workspace:public' })
const file = await directory.getFile('video.mp4')

// Stream directly to a fetch request
await fetch('https://example.com/upload', {
  method: 'PUT',
  body: file.slice(),
  headers: { 'content-type': file.type },
})

When defining a Directory collection for MDX files, use zod to define the shape of the frontmatter. This provides type safety and runtime validation for your content metadata.

In the schema object of a Directory instance, nest your Zod schema under mdx.frontmatter.

schema: {
  mdx: {
    frontmatter: z.object({
      title: z.string(),
      date: z.coerce.date(),
      summary: z.string().optional(),
      tags: z.array(z.string()).optional(),
    }),
  },
}