Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
createLoader
✓ import { createLoader } from 'fumadocs-typescript/loader';
✗ const createLoader = require('fumadocs-typescript/loader');
This function is primarily used within your `next.config.mjs` file to configure type generation for your Fumadocs project. As of `fumadocs-mdx` v14.3.0 (and related ecosystem changes), Next.js configuration files are expected to be ESM-only (`.mjs` extension).
Frontmatter (generated type)
✓ import type { Frontmatter } from './.fumadocs/types';
✗ import type { Frontmatter } from 'fumadocs-typescript';
The `Frontmatter` type is automatically generated by `fumadocs-typescript/loader` based on the schema you define in your Next.js configuration. You typically import it from the generated type definition file (e.g., `.fumadocs/types.d.ts`) rather than directly from the package. Ensure this generated file is included in your `tsconfig.json`.
This quickstart demonstrates how to configure `fumadocs-typescript` within your `next.config.mjs` file. It shows defining a frontmatter schema, initializing the `createLoader`, and chaining it with `@fumadocs/mdx` for content processing to enable type-safe frontmatter.
// next.config.mjs
import { createLoader } from 'fumadocs-typescript/loader';
import { createMDX } from '@fumadocs/mdx'; // A common companion package in Fumadocs projects
// Define your frontmatter schema here. This schema will be used by
// fumadocs-typescript to generate corresponding TypeScript types for your MDX content.
const myFrontmatterSchema = {
title: { type: 'string', required: true, description: 'The title of the document' },
description: { type: 'string', optional: true, description: 'A brief summary of the content' },
date: { type: 'string', optional: true, format: 'date', description: 'Publication date (YYYY-MM-DD)' },
tags: { type: 'array', items: { type: 'string' }, optional: true, description: 'Categorization tags' },
category: { type: 'enum', enum: ['guides', 'api', 'tutorials'], optional: true, description: 'Content category' }
};
// Initialize the Fumadocs TypeScript loader with your schema.
// This loader processes the schema to generate a `types.d.ts` file,
// enabling type-safe access to frontmatter in your components.
const withFumadocsTypescript = createLoader({
schema: myFrontmatterSchema,
// By default, types are generated in .fumadocs/types.d.ts. You can customize the output path:
// outputPath: './custom-types/my-fumadocs-types.d.ts',
});
// Integrate with the main Fumadocs MDX loader for content processing.
// This is a typical setup in Fumadocs projects, chaining the loaders.
const withFumadocsMDX = createMDX({
content: {
// Configure where your MDX content is located, e.g., all files under the 'content' directory
root: 'content',
},
});
/** @type {import('next').NextConfig} */
const nextConfig = {
// Your standard Next.js configuration options go here
reactStrictMode: true,
// Add any other Next.js specific configurations
};
// Chain the loaders: the TypeScript loader typically runs 'before' or in conjunction
// with the MDX loader to ensure types are available for content processing.
export default withFumadocsMDX(withFumadocsTypescript(nextConfig));
// --- Example MDX file (content/getting-started.mdx) ---
// ---
// title: Getting Started with Fumadocs
// description: Learn how to set up your first Fumadocs project with TypeScript.
// date: 2023-10-26
// tags: ["guide", "setup", "typescript"]
// category: "guides"
// ---
// # Hello Fumadocs!
// This is your first document using type-safe frontmatter.
// Access `frontmatter.title` in your React components with full TypeScript support.
Debug
Known issues
breakingFumadocs, including `fumadocs-typescript` when used in Next.js projects, increasingly expects Next.js configuration files to be ESM-only. Ensure your `next.config.js` is renamed to `next.config.mjs` to avoid module resolution errors.fixRename `next.config.js` to `next.config.mjs`. Update any `require()` calls to `import` statements if you had CJS configuration.
affects: >=14.3.0 (for fumadocs-mdx, ecosystem wide impact)
gotchaThis package has strict peer dependencies on `fumadocs-core`, `fumadocs-ui`, `react`, and `react-dom`. Mismatched versions can lead to runtime errors or unexpected behavior, especially with major version bumps.fixEnsure that `fumadocs-core` (>=16.7.0), `fumadocs-ui` (>=16.7.0), `react` (>=19.2.0), and `react-dom` (>=19.2.0) are installed and meet the specified version ranges. Use `npm install --legacy-peer-deps` or `yarn add --install-peer-deps` if facing installation issues, then manually verify versions.
affects: >=1.0.0
gotchaFor TypeScript to recognize the generated frontmatter types (e.g., from `.fumadocs/types.d.ts`), you must ensure the generated file's path is included in your `tsconfig.json`'s `include` array.fixAdd the path to your generated types, e.g., `'./.fumadocs'` or `'./.fumadocs/**/*.d.ts'`, to the `include` array in your `tsconfig.json`.
affects: >=1.0.0
gotchaWhen defining your frontmatter schema, pay close attention to the `required` property. If a field is marked as `required: true` but is missing from an MDX file's frontmatter, it will result in a build error.fixEnsure all required frontmatter fields are present in your MDX files, or mark the field as `optional: true` in your schema definition if it's not strictly necessary for every document.
affects: >=1.0.0
Errors
Common errors & fixes
Cannot use import statement outside a module
Attempting to use ES module `import` syntax in a CommonJS (`.js`) Next.js configuration file, or vice versa.
fixRename your `next.config.js` to `next.config.mjs` and ensure all module imports within it use `import` syntax. If intentionally using CommonJS, use `require()`.
Property 'someField' does not exist on type 'Frontmatter'.
The generated `Frontmatter` type does not include `someField`, likely because it's missing from your schema definition in `next.config.mjs`, or the types are outdated.
fixCheck your `myFrontmatterSchema` definition in `next.config.mjs` and add `someField` with its appropriate type. Restart your development server or trigger a build to regenerate the types. Verify `tsconfig.json` includes the generated types path.
Error: next-mdx-remote failed to parse MDX. If you're using a custom loader, ensure it returns valid MDX.
Incorrect configuration of `fumadocs-typescript` or `@fumadocs/mdx` within `next.config.mjs`, preventing proper processing of MDX files.
fixReview the `next.config.mjs` quickstart example and your setup. Ensure `createLoader` from `fumadocs-typescript/loader` is correctly applied and chained with `createMDX` from `@fumadocs/mdx`. Check for typos in schema definitions.
Audit
Dependencies
fumadocs-corerequiredCore Fumadocs functionality; essential runtime peer dependency.
fumadocs-uirequiredUI components and styling; common peer dependency for Fumadocs projects.
reactrequiredRequired by Next.js and Fumadocs UI components.
react-domrequiredRequired by Next.js for server and client rendering.
@types/estreeoptionalTypeScript types for ESTree AST specification, used internally for parsing.
@types/hastoptionalTypeScript types for HAST HTML AST specification, used for rendering.
@types/mdastoptionalTypeScript types for MDAST Markdown AST specification, used for content processing.
@types/reactoptionalTypeScript types for React, complementing the `react` peer dependency.