> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fimo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Frameworks

> Choose a supported framework for a new Fimo site or connect an existing application.

Fimo can create a new site with React Router, Vite, Astro, Next.js, or SvelteKit. It can also host other applications when you provide a build command and output directory.

For Next.js projects, keep the `withFimo` wrapper in your Next configuration. In Fimo previews it adapts framing headers from Next's `headers()` function so Studio can embed the site. Published builds retain the original policy. Middleware and custom-server headers remain application-owned; see [Preview and production](/docs/environments/preview-vs-production).

## Choose a framework

| Framework | Best fit | Fimo integration |
| - | - | - |
| React Router | A full-stack React site | Content, forms, labels, media, visual editing, and hosting |
| Vite with React | A client-rendered React app | Content, forms, labels, media, visual editing, and hosting |
| Astro | A content-led site | Content, forms, labels, media, visual editing, and hosting |
| Next.js | An App Router or Pages Router application | Content, forms, labels, media, visual editing, and hosting |
| SvelteKit | A Svelte application | Content, forms, labels, media, visual editing, and hosting |
| Other frameworks | A static build or custom application | Hosting only unless a Fimo adapter exists |

Next.js App Router is the default for new sites. Select another framework during setup:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npx fimo@latest init my-site --framework react-router --package-manager npm
    npx fimo@latest init my-site --framework vite --package-manager npm
    npx fimo@latest init my-site --framework astro --package-manager npm
    npx fimo@latest init my-site --framework sveltekit --package-manager npm
    ```
  </Tab>

  <Tab title="Bun">
    ```bash theme={null}
    bunx fimo@latest init my-site --framework react-router --package-manager bun
    bunx fimo@latest init my-site --framework vite --package-manager bun
    bunx fimo@latest init my-site --framework astro --package-manager bun
    bunx fimo@latest init my-site --framework sveltekit --package-manager bun
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm dlx fimo@latest init my-site --framework react-router --package-manager pnpm
    pnpm dlx fimo@latest init my-site --framework vite --package-manager pnpm
    pnpm dlx fimo@latest init my-site --framework astro --package-manager pnpm
    pnpm dlx fimo@latest init my-site --framework sveltekit --package-manager pnpm
    ```
  </Tab>

  <Tab title="Yarn">
    ```bash theme={null}
    yarn dlx fimo@latest init my-site --framework react-router --package-manager yarn
    yarn dlx fimo@latest init my-site --framework vite --package-manager yarn
    yarn dlx fimo@latest init my-site --framework astro --package-manager yarn
    yarn dlx fimo@latest init my-site --framework sveltekit --package-manager yarn
    ```
  </Tab>
</Tabs>

<Note>
  Current adapter ranges depend on the version of `fimo` installed in your project. Run `fimo validate` before changing
  framework versions.
</Note>

## Connect an existing application

From the application directory, run:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npx fimo@latest link
    ```
  </Tab>

  <Tab title="Bun">
    ```bash theme={null}
    bunx fimo@latest link
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm dlx fimo@latest link
    ```
  </Tab>

  <Tab title="Yarn">
    ```bash theme={null}
    yarn dlx fimo@latest link
    ```
  </Tab>
</Tabs>

Fimo keeps your framework, routes, and Git history. If the framework needs a Fimo build hook, the command tells you which configuration line to add.

Your application continues to own routing, locale URLs, links, and page-level SEO. Fimo supplies the content and editing tools that its adapter supports.

## Framework guides

<CardGroup cols={2}>
  <Card title="React Router" href="/https/fimo.ai/docs/cli/frameworks/react-router" icon="https://mintcdn.com/strapi/BgnXuwToZAXuRnSp/public/framework-logos/react-router-on-dark.svg?fit=max&auto=format&n=BgnXuwToZAXuRnSp&q=85&s=0cf04a3247c68ecdf45416759b218162" width="602" height="360" data-path="public/framework-logos/react-router-on-dark.svg" />

  <Card title="Vite with React" href="/https/fimo.ai/docs/cli/frameworks/vite-react" icon="https://mintcdn.com/strapi/BgnXuwToZAXuRnSp/public/framework-logos/vite-on-dark.svg?fit=max&auto=format&n=BgnXuwToZAXuRnSp&q=85&s=a6c58c2973a07ab147e4b9e7223bef9f" width="23" height="14" data-path="public/framework-logos/vite-on-dark.svg" />

  <Card title="Astro" href="/https/fimo.ai/docs/cli/frameworks/astro" icon="https://mintcdn.com/strapi/BgnXuwToZAXuRnSp/public/framework-logos/astro-on-dark.svg?fit=max&auto=format&n=BgnXuwToZAXuRnSp&q=85&s=c879aace1e70765a625f95fa80cf9c3c" width="85" height="107" data-path="public/framework-logos/astro-on-dark.svg" />

  <Card title="Next.js" href="/https/fimo.ai/docs/cli/frameworks/nextjs" icon="https://mintcdn.com/strapi/BgnXuwToZAXuRnSp/public/framework-logos/nextjs-on-dark.svg?fit=max&auto=format&n=BgnXuwToZAXuRnSp&q=85&s=829922f364048dd8f01b4fe90550fa57" width="100" height="100" data-path="public/framework-logos/nextjs-on-dark.svg" />

  <Card title="SvelteKit" href="/https/fimo.ai/docs/cli/frameworks/sveltekit" icon="https://mintcdn.com/strapi/BgnXuwToZAXuRnSp/public/framework-logos/svelte.svg?fit=max&auto=format&n=BgnXuwToZAXuRnSp&q=85&s=c463965bc5338646bc276088b4a64019" width="93" height="112" data-path="public/framework-logos/svelte.svg" />
</CardGroup>

## Agent best practices

The bundled `fimo-code` skill includes focused performance guidance for public
Astro, SvelteKit, and Next.js sites. Coding agents should load the integration
reference first, then the matching best-practices reference:

```bash theme={null}
fimo skills get fimo-code --ref best-practices/astro
fimo skills get fimo-code --ref best-practices/sveltekit
fimo skills get fimo-code --ref best-practices/next
```

These references cover server-rendered content, request waterfalls, client
JavaScript, dynamic-route 404s, canonical URLs, and framework-specific build or
navigation optimizations. They do not replace the framework integration
contract.

## Shared project contract

Set the application's production profile in `.fimo/config.json`:

```json theme={null}
{
  "runtime": { "framework": "nextjs" }
}
```

Supported values are `astro`, `nextjs`, `nuxtjs`, `react-router`, `remix`,
`sveltekit`, `vite`, and `vue`. Conventional projects use their package
scripts and framework defaults. Override commands only when the existing
application needs them:

<Tabs>
  <Tab title="npm">
    ```json theme={null}
    {
      "runtime": {
        "framework": "nextjs",
        "commands": {
          "dev": "npm run dev:studio",
          "build": "npm run build:production",
          "install": "npm ci"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Bun">
    ```json theme={null}
    {
      "runtime": {
        "framework": "nextjs",
        "commands": {
          "dev": "bun run dev:studio",
          "build": "bun run build:production",
          "install": "bun install --frozen-lockfile"
        }
      }
    }
    ```
  </Tab>

  <Tab title="pnpm">
    ```json theme={null}
    {
      "runtime": {
        "framework": "nextjs",
        "commands": {
          "dev": "pnpm dev:studio",
          "build": "pnpm build:production",
          "install": "pnpm install --frozen-lockfile"
        }
      }
    }
    ```
  </Tab>

  <Tab title="Yarn">
    ```json theme={null}
    {
      "runtime": {
        "framework": "nextjs",
        "commands": {
          "dev": "yarn dev:studio",
          "build": "yarn build:production",
          "install": "yarn install --immutable"
        }
      }
    }
    ```
  </Tab>
</Tabs>

New framework shells are locale-ready by default. React Router framework mode
and native Vite use `:locale?`; Astro, Next.js, and SvelteKit use their native
route-boundary patterns. The default locale stays unprefixed, and existing
applications keep their current URL strategy.

In a linked checkout, Astro, SvelteKit, React Router, and Vite derive the
current Branch's runtime aliases during development and production builds.
Next.js resolves the linked site and active Git branch in its root
`FimoProvider`, then passes only the public connection to the browser. Explicit
server overrides still take precedence.

## Package surfaces

| Application code | Content and components |
| - | - |
| React Router or Vite + React | `fimo-react` and the matching router/Vite entrypoint |
| Next.js server | `fimo-next` |
| Next.js client | `fimo-next/client` |
| Astro server pages | `fimo/astro` and `fimo/astro/components`; hosting via `fimo-astro` |
| SvelteKit | `fimo-sveltekit`, `fimo-sveltekit/components`, and `fimo-sveltekit/vite`; hosting via `fimo-sveltekit/config` |

The component vocabulary stays value-first across frameworks: `<Text value={article.title} as="h1" />`, `<Image value={article.cover} />`, and `<RichText value={article.body} />`.

`<Date>` and `<DateTime>` both render a `<time>` element and are available in
all four surfaces. Use `<Date>` for a `date` field, where the `datetime`
attribute is the calendar day, and `<DateTime>` for a `datetime` field, where it
is the full ISO instant.

## Update Fimo packages

Keep `fimo` and its framework packages on the same exact version. Do not edit their versions directly in `package.json`. Run the latest CLI with the exact target version:

<Tabs>
  <Tab title="npm">
    ```bash theme={null}
    npx fimo@latest update 1.0.0
    ```
  </Tab>

  <Tab title="Bun">
    ```bash theme={null}
    bunx fimo@latest update 1.0.0
    ```
  </Tab>

  <Tab title="pnpm">
    ```bash theme={null}
    pnpm dlx fimo@latest update 1.0.0
    ```
  </Tab>

  <Tab title="Yarn">
    ```bash theme={null}
    yarn dlx fimo@latest update 1.0.0
    ```
  </Tab>
</Tabs>

It shows the plan first — the package pins, the companion packages your framework needs, any import rewrites, and that release's breaking changes — and only writes after you confirm. Add `--dry-run` to inspect without changing anything, or `--apply` to run non-interactively. The command needs a clean git working tree, installs with your project's package manager, runs `fimo validate` afterwards, and never commits, deploys, or publishes on its own.

The update adds missing framework packages before it rewrites imports. For
example, a Next.js project missing `fimo-next` receives `fimo-next` and
`fimo-react` at the target version before `fimo/next` imports move to
`fimo-next`.

React and Next.js projects pinned to a release from before framework packages
were split remain supported. The current CLI generates content clients against
their existing `fimo/ui` or `fimo/next` runtime, without installing
`fimo-react` or `fimo-next` or changing the project's Fimo version. The
companion becomes required only after you update to a release that uses the
split packages.

## Compatibility

The framework profile selects the integration; it does not promise every
historical framework version. Current package ranges and tested baselines are:

| Profile | Application versions |
| - | - |
| Next.js | Next 16 acceptance baseline; React 18.2+ or 19 |
| React Router | React Router 7 or 8; React 18.2+ or 19; Vite 7 or 8 |
| Vite + React | React 18.2+ or 19; Vite 7 or 8 |
| Astro | Astro 5, 6, or 7 |
| SvelteKit | SvelteKit 2; Svelte 5; Vite 7 or 8 |

Nuxt, Remix, and Vue currently have hosting detection only; they do not yet
have a Fimo content/runtime adapter.

## What's next

<Columns cols={3}>
  <Card title="Content & CMS" icon="database" href="/https/fimo.ai/docs/cli/content">
    Declare schemas and use generated content clients.
  </Card>

  <Card title="Locales" icon="globe" href="/https/fimo.ai/docs/cli/locales">
    Connect Fimo to the application's locale policy.
  </Card>

  <Card title="Deploy & publish" icon="cloud-arrow-up" href="/https/fimo.ai/docs/deploy/overview">
    Preview the application and publish it.
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.