# Fumadocs (Framework Mode, TanStack Start): 手動安裝
URL: /zh-TW/docs/tanstack-start/manual-installation
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/manual-installation.zh-TW.mdx

將 Fumadocs 加入現有的 TanStack Start 專案。

您也可以使用 [Fumadocs CLI](/docs/cli#init) 自動完成設定：

```npm
npx @fumadocs/cli init
```

## 先決條件 [#prerequisites]

繼續之前，請確認您已設定好：

* Tailwind CSS 4。
* Fumadocs MDX：請依照 [Vite 設定指南](/docs/mdx/vite)操作，並建立 `lib/source.ts` 等必要檔案。

<Callout title="小提示">
Fumadocs 也支援其他內容來源，包括 [Content Collections](/docs/headless/content-collections) 與無頭式 CMS。
</Callout>

## 開始使用 [#getting-started]

安裝套件：

```npm
npm i fumadocs-core fumadocs-ui@npm:@fumadocs/base-ui
```

與範本相同，此指令會將 `fumadocs-ui` 安裝為 `@fumadocs/base-ui` 的別名，也就是 Fumadocs UI 的 [Base UI](/docs/ui/component-library) 版本。若要使用 Radix UI 版本，請直接安裝 `fumadocs-ui`，不要使用別名。

### 樣式 [#styles]

請將以下內容加入您的 Tailwind CSS 檔案：

```css
@import 'tailwindcss';
/* [!code ++:2] */
@import 'fumadocs-ui/css/neutral.css';
@import 'fumadocs-ui/css/preset.css';
```

### Root Provider [#root-provider]

請用 [Root Provider](/docs/ui/layouts/root-provider) 包住整個應用程式，並為 `body` 加上必要的樣式。

```tsx title="src/routes/__root.tsx"
import { createRootRoute, HeadContent, Outlet, Scripts } from '@tanstack/react-router';
import * as React from 'react';
import { RootProvider } from 'fumadocs-ui/provider/tanstack';

export const Route = createRootRoute({
  component: RootComponent,
});

function RootComponent() {
  return (
    <RootDocument>
      <Outlet />
    </RootDocument>
  );
}

function RootDocument({ children }: { children: React.ReactNode }) {
  return (
    <html suppressHydrationWarning>
      <head>
        <HeadContent />
      </head>
      <body className="flex flex-col min-h-screen">
        {/* [!code ++] */}
        <RootProvider>{children}</RootProvider>
        <Scripts />
      </body>
    </html>
  );
}
```

### 路由 [#routes]

請建立下列檔案：

```tsx tab="src/components/mdx.tsx"
import defaultMdxComponents from 'fumadocs-ui/mdx';
import type { MDXComponents } from 'mdx/types';

export function getMDXComponents(components?: MDXComponents) {
  return {
    ...defaultMdxComponents,
    ...components,
  } satisfies MDXComponents;
}

export const useMDXComponents = getMDXComponents;

declare global {
  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
}
```

```tsx tab="src/lib/layout.shared.tsx"
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';

export function baseOptions(): BaseLayoutProps {
  return {
    nav: {
      title: 'Tanstack Start',
    },
  };
}
```

```tsx tab="src/routes/docs/$.tsx"
import { createFileRoute, notFound } from '@tanstack/react-router';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { createServerFn } from '@tanstack/react-start';
import { docs, source } from '@/lib/source';
import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
import { baseOptions } from '@/lib/layout.shared';
import { useFumadocsLoader } from 'fumadocs-core/source/client';
import { Suspense, use } from 'react';
import { useMDXComponents } from '@/components/mdx';

export const Route = createFileRoute('/docs/$')({
  component: Page,
  loader: async ({ params }) => {
    const slugs = params._splat?.split('/') ?? [];
    const data = await serverLoader({ data: slugs });
    await docs.getPage(data.path)?.preload();
    return data;
  },
});

const serverLoader = createServerFn({
  method: 'GET',
})
  .validator((slugs: string[]) => slugs)
  .handler(async ({ data: slugs }) => {
    const page = source.getPage(slugs);
    if (!page) throw notFound();

    return {
      path: page.path,
      pageTree: await source.serializePageTree(source.getPageTree()),
    };
  });

function Content({ path }: { path: string }) {
  const page = docs.getPage(path);
  if (!page) throw new Error(`unknown page: ${path}`);

  const { toc } = use(page.load());
  const MDX = page.body;

  return (
    <DocsPage toc={toc}>
      <DocsTitle>{page.title}</DocsTitle>
      <DocsDescription>{page.description}</DocsDescription>
      <DocsBody>
        <MDX components={useMDXComponents()} />
      </DocsBody>
    </DocsPage>
  );
}

function Page() {
  const data = useFumadocsLoader(Route.useLoaderData());

  return (
    <DocsLayout {...baseOptions()} tree={data.pageTree}>
      <Suspense>
        <Content path={data.path} />
      </Suspense>
    </DocsLayout>
  );
}
```

```ts tab="src/routes/api/search.ts"
import { createFileRoute } from '@tanstack/react-router';
import { source } from '@/lib/source';
import { createFromSource } from 'fumadocs-core/search/server';

const server = createFromSource(source);

export const Route = createFileRoute('/api/search')({
  server: {
    handlers: {
      GET: async ({ request }) => server.GET(request),
    },
  },
});
```

搜尋路由採用 ZBSearch，設定方式請參閱[文件搜尋](/docs/headless/search)。

### 完成 [#finish]

啟動開發伺服器，即可在 `content/docs` 中撰寫您的文件：

```mdx title="content/docs/index.mdx"
---
title: Hello World
---

## Introduction

I love Fumadocs.
```