{"id":15113,"library":"fumadocs-typescript","title":"Fumadocs TypeScript Integration","description":"fumadocs-typescript is a specialized integration package within the Fumadocs ecosystem, providing robust TypeScript support for documentation projects built with Next.js. It enables developers to define and enforce type-safety for MDX frontmatter, ensuring consistency and reducing errors in content authoring. The package is currently at version 5.2.6. While its specific release cadence isn't independently clear, it often updates in conjunction with major releases of `fumadocs-core` and `fumadocs-ui`, which demonstrate frequent maintenance and improvements. Its key differentiator is its seamless integration with the Fumadocs MDX processing pipeline, allowing for automatic type generation and validation of content-level metadata, crucial for large-scale documentation sites. This significantly enhances the developer experience by providing autocompletion and compile-time checks for content properties.","status":"active","version":"5.2.6","language":"javascript","source_language":"en","source_url":"https://github.com/fuma-nama/fumadocs","tags":["javascript","Docs","NextJs","fumadocs","typescript"],"install":[{"cmd":"npm install fumadocs-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add fumadocs-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add fumadocs-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Fumadocs functionality; essential runtime peer dependency.","package":"fumadocs-core","optional":false},{"reason":"UI components and styling; common peer dependency for Fumadocs projects.","package":"fumadocs-ui","optional":false},{"reason":"Required by Next.js and Fumadocs UI components.","package":"react","optional":false},{"reason":"Required by Next.js for server and client rendering.","package":"react-dom","optional":false},{"reason":"TypeScript types for ESTree AST specification, used internally for parsing.","package":"@types/estree","optional":true},{"reason":"TypeScript types for HAST HTML AST specification, used for rendering.","package":"@types/hast","optional":true},{"reason":"TypeScript types for MDAST Markdown AST specification, used for content processing.","package":"@types/mdast","optional":true},{"reason":"TypeScript types for React, complementing the `react` peer dependency.","package":"@types/react","optional":true}],"imports":[{"note":"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).","wrong":"const createLoader = require('fumadocs-typescript/loader');","symbol":"createLoader","correct":"import { createLoader } from 'fumadocs-typescript/loader';"},{"note":"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`.","wrong":"import type { Frontmatter } from 'fumadocs-typescript';","symbol":"Frontmatter (generated type)","correct":"import type { Frontmatter } from './.fumadocs/types';"}],"quickstart":{"code":"// next.config.mjs\nimport { createLoader } from 'fumadocs-typescript/loader';\nimport { createMDX } from '@fumadocs/mdx'; // A common companion package in Fumadocs projects\n\n// Define your frontmatter schema here. This schema will be used by\n// fumadocs-typescript to generate corresponding TypeScript types for your MDX content.\nconst myFrontmatterSchema = {\n  title: { type: 'string', required: true, description: 'The title of the document' },\n  description: { type: 'string', optional: true, description: 'A brief summary of the content' },\n  date: { type: 'string', optional: true, format: 'date', description: 'Publication date (YYYY-MM-DD)' },\n  tags: { type: 'array', items: { type: 'string' }, optional: true, description: 'Categorization tags' },\n  category: { type: 'enum', enum: ['guides', 'api', 'tutorials'], optional: true, description: 'Content category' }\n};\n\n// Initialize the Fumadocs TypeScript loader with your schema.\n// This loader processes the schema to generate a `types.d.ts` file,\n// enabling type-safe access to frontmatter in your components.\nconst withFumadocsTypescript = createLoader({\n  schema: myFrontmatterSchema,\n  // By default, types are generated in .fumadocs/types.d.ts. You can customize the output path:\n  // outputPath: './custom-types/my-fumadocs-types.d.ts',\n});\n\n// Integrate with the main Fumadocs MDX loader for content processing.\n// This is a typical setup in Fumadocs projects, chaining the loaders.\nconst withFumadocsMDX = createMDX({\n  content: {\n    // Configure where your MDX content is located, e.g., all files under the 'content' directory\n    root: 'content',\n  },\n});\n\n/** @type {import('next').NextConfig} */\nconst nextConfig = {\n  // Your standard Next.js configuration options go here\n  reactStrictMode: true,\n  // Add any other Next.js specific configurations\n};\n\n// Chain the loaders: the TypeScript loader typically runs 'before' or in conjunction\n// with the MDX loader to ensure types are available for content processing.\nexport default withFumadocsMDX(withFumadocsTypescript(nextConfig));\n\n// --- Example MDX file (content/getting-started.mdx) ---\n// ---\n// title: Getting Started with Fumadocs\n// description: Learn how to set up your first Fumadocs project with TypeScript.\n// date: 2023-10-26\n// tags: [\"guide\", \"setup\", \"typescript\"]\n// category: \"guides\"\n// ---\n\n// # Hello Fumadocs!\n\n// This is your first document using type-safe frontmatter.\n// Access `frontmatter.title` in your React components with full TypeScript support.","lang":"typescript","description":"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."},"warnings":[{"fix":"Rename `next.config.js` to `next.config.mjs`. Update any `require()` calls to `import` statements if you had CJS configuration.","message":"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.","severity":"breaking","affected_versions":">=14.3.0 (for fumadocs-mdx, ecosystem wide impact)"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Add the path to your generated types, e.g., `'./.fumadocs'` or `'./.fumadocs/**/*.d.ts'`, to the `include` array in your `tsconfig.json`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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()`.","cause":"Attempting to use ES module `import` syntax in a CommonJS (`.js`) Next.js configuration file, or vice versa.","error":"Cannot use import statement outside a module"},{"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.","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.","error":"Property 'someField' does not exist on type 'Frontmatter'."},{"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.","cause":"Incorrect configuration of `fumadocs-typescript` or `@fumadocs/mdx` within `next.config.mjs`, preventing proper processing of MDX files.","error":"Error: next-mdx-remote failed to parse MDX. If you're using a custom loader, ensure it returns valid MDX."}],"ecosystem":"npm"}