Contentlayer — Turn Content into Type-Safe Data for Next.js

Introduction

Contentlayer validates your content files (Markdown, MDX, JSON, YAML) against a schema you define, then generates typed JSON data and TypeScript definitions. It integrates deeply with Next.js so you can import content like a local module with full IntelliSense.

What Contentlayer Does

• Reads Markdown, MDX, JSON, and YAML files from a content directory and validates against your schema
• Generates .contentlayer output with typed JSON data and auto-generated TypeScript definitions
• Provides a Next.js plugin for seamless integration with hot reload on content changes
• Supports computed fields for transforming content at build time (e.g., reading time, slug generation)
• Handles MDX compilation with customizable remark and rehype plugin chains

Architecture Overview

Contentlayer runs as a build step that watches your content directory. When files change, it parses each document, validates fields against your defineDocumentType schema, compiles MDX if needed, and writes typed JSON to a .contentlayer/generated folder. A TypeScript definition file is auto-generated so imports are fully typed. The Next.js plugin hooks into the dev server for live reload.

Self-Hosting & Configuration

• Install contentlayer2 and the Next.js plugin as dev dependencies
• Create a contentlayer.config.ts with document type definitions and field schemas
• Wrap your Next.js config with withContentlayer() for automatic integration
• Store content files in the configured contentDirPath (e.g., ./posts or ./docs)
• Customize MDX processing with remark/rehype plugins in the makeSource options

Key Features

• Full TypeScript support: auto-generated types for every document type and field
• Live reload: content changes trigger immediate rebuilds during development
• Computed fields: derive values like reading time, URL slug, or table of contents at build time
• MDX support with configurable remark/rehype plugins for custom transformations
• Incremental builds: only re-processes changed content files for fast iteration

Comparison with Similar Tools

• next-mdx-remote — Renders MDX at runtime; Contentlayer pre-compiles at build time with full type safety
• Fumadocs — Documentation framework with built-in search; Contentlayer is a general-purpose content SDK
• Velite — Similar typed content layer; Contentlayer has deeper Next.js integration and a larger community
• Sanity / Contentful — Cloud CMS platforms; Contentlayer works with local files, giving you Git-based version control

FAQ

Q: Is Contentlayer still maintained? A: The original contentlayer package is no longer actively maintained. The community fork contentlayer2 continues development and is compatible with recent Next.js versions.

Q: Does it work with frameworks besides Next.js? A: Contentlayer is designed primarily for Next.js. The core content processing works standalone, but the plugin ecosystem and hot reload are Next.js-specific.

Q: How does it handle images in Markdown? A: Images referenced in Markdown are not processed by Contentlayer directly. Use next/image with a remark plugin to optimize images, or store them in the public directory.

Q: Can I use it with a headless CMS? A: Contentlayer is designed for file-based content. For CMS integration, consider using the CMS's API directly or tools like Sanity's GROQ with their own type generation.

Sources

• https://github.com/contentlayerdev/contentlayer
• https://contentlayer.dev