Fumadocs TypeScript Integration

Common errors

• Cannot use import statement outside a module

  cause Attempting to use ES module `import` syntax in a CommonJS (`.js`) Next.js configuration file, or vice versa.
  fix Rename 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'.

  cause 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.
  fix Check 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.

  cause Incorrect configuration of `fumadocs-typescript` or `@fumadocs/mdx` within `next.config.mjs`, preventing proper processing of MDX files.
  fix Review 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.

Warnings

• breaking Fumadocs, 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.
  Fix: Rename `next.config.js` to `next.config.mjs`. Update any `require()` calls to `import` statements if you had CJS configuration.
• gotcha This 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.
  Fix: Ensure 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.
• gotcha For 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.
  Fix: Add the path to your generated types, e.g., `'./.fumadocs'` or `'./.fumadocs/**/*.d.ts'`, to the `include` array in your `tsconfig.json`.
• gotcha When 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.
  Fix: Ensure 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.

Install

• npm install fumadocs-typescript npm
• yarn add fumadocs-typescript yarn
• pnpm add fumadocs-typescript pnpm

Imports

• createLoader
  wrong:

  const createLoader = require('fumadocs-typescript/loader');

  correct:

  import { createLoader } from '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)
  wrong:

  import type { Frontmatter } from 'fumadocs-typescript';

  correct:

  import type { Frontmatter } from './.fumadocs/types';

  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`.

Quickstart

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.