---
title: "Quick Start"
description: "The \"Quick Start\" subsystem facilitates the rapid scaffolding and initialization of Fumadocs-powered applications. Its primary goal is to abstract the complexity of configuring build tools, file-sy..."
last_updated: "2026-07-02T09:46:38.948969+00:00"
canonical_url: "https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/orientation/quick-start"
---

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [packages/mdx/src/vite/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/vite/index.ts)
- [packages/mdx/src/next/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts)
- [packages/preview/src/pages/[...slugs].tsx](https://github.com/blade47/fumadocs/blob/main/packages/preview/src/pages/%5B...slugs%5D.tsx)
- [packages/mdx/src/runtime/dynamic.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/runtime/dynamic.ts)
- [packages/create-app/src/bin.ts](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/bin.ts)
- [packages/create-app/src/plugins/ai.ts](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/plugins/ai.ts)
- [packages/create-app/src/plugins/next-use-takumi.ts](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/plugins/next-use-takumi.ts)
- [packages/content/src/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/content/src/index.ts)
- [packages/mdx/src/runtime/server.ts](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/runtime/server.ts)
- [packages/preview/src/lib/source/index.ts](https://github.com/blade47/fumadocs/blob/main/packages/preview/src/lib/source/index.ts)
- [packages/preview/package.json](https://github.com/blade47/fumadocs/blob/main/packages/preview/package.json)
- [packages/preview/src/layouts/config.tsx](https://github.com/blade47/fumadocs/blob/main/packages/preview/src/layouts/config.tsx)
- [packages/create-app/scripts/sync.ts](https://github.com/blade47/fumadocs/blob/main/packages/create-app/scripts/sync.ts)
- [packages/vite/tsdown.config.ts](https://github.com/blade47/fumadocs/blob/main/packages/vite/tsdown.config.ts)
- [packages/vite/package.json](https://github.com/blade47/fumadocs/blob/main/packages/vite/package.json)
- [packages/preview/fumadocs.config.ts](https://github.com/blade47/fumadocs/blob/main/packages/preview/fumadocs.config.ts)
- [packages/preview/waku.config.ts](https://github.com/blade47/fumadocs/blob/main/packages/preview/waku.config.ts)
- [packages/vite-data/package.json](https://github.com/blade47/fumadocs/blob/main/packages/vite-data/package.json)
- [packages/content/src/runtime.ts](https://github.com/blade47/fumadocs/blob/main/packages/content/src/runtime.ts)
- [packages/story/package.json](https://github.com/blade47/fumadocs/blob/main/packages/story/package.json)
- [packages/sanity/package.json](https://github.com/blade47/fumadocs/blob/main/packages/sanity/package.json)
- [packages/preview/src/components/provider.tsx](https://github.com/blade47/fumadocs/blob/main/packages/preview/src/components/provider.tsx)
- [packages/base-ui/src/provider/next.tsx](https://github.com/blade47/fumadocs/blob/main/packages/base-ui/src/provider/next.tsx)
- [packages/create-app/src/constants.ts](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/constants.ts)
- [packages/core/package.json](https://github.com/blade47/fumadocs/blob/main/packages/core/package.json)
- [packages/typescript/package.json](https://github.com/blade47/fumadocs/blob/main/packages/typescript/package.json)
- [packages/twoslash/package.json](https://github.com/blade47/fumadocs/blob/main/packages/twoslash/package.json)
- [packages/obsidian/package.json](https://github.com/blade47/fumadocs/blob/main/packages/obsidian/package.json)
- [packages/asyncapi/package.json](https://github.com/blade47/fumadocs/blob/main/packages/asyncapi/package.json)
- [packages/basehub/package.json](https://github.com/blade47/fumadocs/blob/main/packages/basehub/package.json)
</details>

The "Quick Start" subsystem facilitates the rapid scaffolding and initialization of Fumadocs-powered applications. Its primary goal is to abstract the complexity of configuring build tools, file-system watching, and dependency management across various framework environments (Next.js, Waku, Vite). By providing unified CLI-driven project generation and framework-specific adapter configurations, it ensures a consistent development experience regardless of the underlying stack.

The subsystem operates through a "generator-plugin" architecture. The entry point, `create-app`, interacts with the user via `clack` prompts to define project requirements, such as linting preferences, search engine solutions, and AI chat integration. Once initialized, it executes a series of plugin-based transformations—such as adding dependencies to `package.json` or injecting AI search components into layout files—ensuring the scaffolded environment adheres to project best practices.

Integration with existing projects occurs through specific framework adapters located in `mdx/src/vite/index.ts` and `mdx/src/next/index.ts`. These modules define core emitters that watch for configuration changes, handle MDX/Meta file compilation, and ensure the development server remains reactive to content updates. This design decouples the user-facing CLI experience from the complex build-time requirements of the Fumadocs framework.

## CLI Project Scaffolding

The project generation mechanism starts with the `bin.ts` entry point in the `create-app` package. It uses a structured prompt group to gather user configuration, which is then passed to the `create()` function. The CLI handles complex decisions, such as whether to enable the `/src` directory for Next.js projects or which search solution (Orama/Orama Cloud) to utilize, based on the selected template.

```typescript
// Example: CLI generation workflow in packages/create-app/src/bin.ts
await create({
  packageManager: config.pm,
  template: options.template,
  outputDir: projectName,
  installDeps: options.installDeps,
  initializeGit: config.git,
  plugins,
  log: (message) => { info.message(message); },
});
```
Sources: [packages/create-app/src/bin.ts:272-282](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/bin.ts#L272-L282)

The system also enforces a strict pre-flight check for target directories. If a directory already exists, it prompts for deletion and handles recursive removal of files via `fs.rm` to ensure a clean slate, preventing stale configuration leaks.

Sources: [packages/create-app/src/bin.ts:319-326](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/bin.ts#L319-L326)

## Framework-Specific Adapters (MDX)

The core functionality for integrating Fumadocs into a project is split between Vite and Next.js adapters. These adapters normalize configuration and provide lifecycle hooks for the development server.

- **Next.js Adapter (`createMDX`)**: Injects custom webpack loaders for `.mdx`, `.md`, and `.json` files. It manages the `pageExtensions` configuration and initializes a `FSWatcher` to restart the development process when `configPath` changes.
- **Vite Adapter (`mdx`)**: Implements Vite-specific plugins to handle file transformations. It filters out files from internal paths like `virtual:vite-rsc` to ensure compatibility with RSC-heavy environments.

> [!NOTE]
> The dev server watcher explicitly ignores the `outDir` during initialization to prevent infinite reload loops caused by the generator emitting files into the target folder.

Sources: [packages/mdx/src/next/index.ts:138](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts#L138)

## Plugin Architecture

The `create-app` generator supports a pluggable architecture using `TemplatePlugin`. These plugins (such as AI chat or Image generation) provide `afterWrite` hooks that execute after the initial scaffolding is complete.

For instance, the AI Chat plugin leverages the `FumadocsComponentInstaller` to fetch components from the remote registry, then uses `ts-morph` to inspect the existing `DocsLayout` in the user's project and programmatically inject the `<AISearch>` trigger.

```typescript
// Example: Injecting AI Search logic in packages/create-app/src/plugins/ai.ts
const code = `<AISearch>
  <AISearchPanel />
  <AISearchTrigger ... />
</AISearch>`;
// ... logic to find DocsLayout and prepend AI components
```
Sources: [packages/create-app/src/plugins/ai.ts:61-86](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/plugins/ai.ts#L61-L86)

## Hot-Reloading Mechanism

The development server for MDX content relies on a `FSWatcher` initialized inside `initServer`. This watcher triggers an `initOrReload` cycle when the `source.config.ts` file is modified.

1. `watcher.on('all')` detects file changes.
2. Checks if `path.resolve(file)` matches the known configuration path.
3. If matched, it calls `watcher.removeAllListeners()` and `watcher.close()` to prevent race conditions during the reload.
4. Executes `core.init()` with the updated configuration.
5. Recursively calls `devServer()` to restart the watch process with updated state.

Sources: [packages/mdx/src/next/index.ts:156-165](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/next/index.ts#L156-L165)

## Configuration Design Trade-offs

| Choice | Benefit | Cost |
| :--- | :--- | :--- |
| **Pluggable Scaffolding** | Highly customizable project templates | Requires complex file parsing and transformation logic |
| **Watcher-based Config** | Real-time updates without full dev-server restarts | Overhead of maintaining file system listeners |
| **Internalized Plugins** | Cohesive dependency and version management | Coupling between CLI tools and core framework |

Sources: [packages/create-app/src/bin.ts:231-270](https://github.com/blade47/fumadocs/blob/main/packages/create-app/src/bin.ts#L231-L270)

## Dynamic Runtime Initialization

The `packages/mdx/src/runtime/dynamic.ts` module provides a bridge between static content and runtime behavior. It uses an `AsyncFunction` constructor to execute compiled MDX code within a controlled, safe sandbox environment.

> [!IMPORTANT]
> The dynamic execution assumes the compiled code is safe. When passing `fullScope`, it merges user-defined `scope` with the default `jsxRuntime`, providing essential context for document hydration.

Sources: [packages/mdx/src/runtime/dynamic.ts:31-41](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/runtime/dynamic.ts#L31-L41)

This runtime dynamic loading is primarily used to serve content lazily, ensuring that large documentation sets do not overwhelm the initial memory footprint of the application. It creates internal `head` and `body` dictionaries that resolve content only upon request, effectively caching results after the first compilation of a file entry.

Sources: [packages/mdx/src/runtime/dynamic.ts:90-91](https://github.com/blade47/fumadocs/blob/main/packages/mdx/src/runtime/dynamic.ts#L90-L91)

## Related

- [Overview](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/orientation/overview)
- [Project Structure](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/technical/orientation/project-structure)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/e8872a72-1909-479c-b585-dc74c6e26726/llms.txt) for all pages in this wiki.