DOCSEARCHbyAlgolia
Submit Docs

@fastify/vite Documentation

repository·main·Indexed 22 days ago

https://github.com/fastify/fastify-vite

A Fastify plugin that integrates Vite into a Fastify server. It provides a development mode using Vite middleware, application exposure for router integration, and automatic production bundle serving. The ecosystem includes official renderers for React (@fastify/react), Vue (@fastify/vue), and HTMX (@fastify/htmx), as well as support for SPA and SSR patterns.

Tokens
37.7K
Snippets
115
Records
181
Agent score
75%

What's inside @fastify/vite

  1. Overview of @fastify/vite

    main

    @fastify/vite is a Fastify plugin designed to integrate Vite into your Fastify server. It provides three core capabilities:

    1. Development Mode: Runs the Vite development server as middleware within your Fastify server (only during development).
    2. Application Exposure: Exposes your Vite application to Fastify, providing configuration hooks to simplify router integration and other customizations.
    3. Production Mode: Automatically serves your Vite production bundle, which is inferred from your Vite configuration file.

    For higher-level DX (Developer Experience) that mimics Nuxt or Next.js, you should use the companion packages @fastify/vue or @fastify/react.

  2. Use @fastify/react for React rendering in @fastify/vite

    main
    The @fastify/react package is the official renderer for React when using the @fastify/vite framework. It allows you to integrate React components into your Fastify application via the @fastify/vite plugin system. For detailed setup guides and advanced configuration, refer to the official documentation suite.

  4. Identify @fastify/vite framework examples

    main

    The e2e/ directory provides usage examples for integrating Vite with Fastify across several common scenarios. Use these as reference implementations for your own projects:

    • React: Various configurations including Vanilla, SPA, Streaming, and Hydration.
    • Vue: Standard Vue integration.
    • SSR/SPA: Examples demonstrating Server-Side Rendering and Single Page Application patterns.
    • TypeScript: Examples using TypeScript source files.

    Specific edge-case reproductions are also available:

    • prefix-support: Ensures static routes respect registration prefixes.
    • relative-outdir: Handles nested roots with relative outDir settings.

  8. What is Route Context in @fastify/react?

    main

    In @fastify/react applications, the route context is an object available in every route module and layout module. It provides access to shared application state, data fetched for the current route, and metadata.

    It is populated via a route context initialization module (context.js) and is designed to be simple and extensible. The implementation is tightly coupled to the server to facilitate hydration (transferring server-side state to the client).

    import { useRouteContext } from '@fastify/react/client'

export default function Index (props) {
  const { ... } = useRouteContext()
  // ...
}

  9. How Route Layouts work in @fastify/react

    main

    In @fastify/react, layouts are automatically loaded from the layouts/ directory. They are used to wrap route components with shared UI or logic (like authentication checks).

    Default Layout

    If no layout is specified for a route, @fastify/react uses a default layout. If your project does not provide a /layouts/default.jsx file, a virtual module provides a fallback layout that wraps children in a <Suspense> component:

    import { Suspense } from 'react'

export default function Layout({ children }) {
  return <Suspense>{children}</Suspense>
}

    Assigning a Layout to a Route

    To assign a specific layout to a route, export a layout constant from your route module. The value of the constant should match the filename of the component in your layouts/ folder (excluding the extension).

    For example, exporting export const layout = 'auth' will wrap the route in the component defined in layouts/auth.jsx or layouts/auth.tsx.

    export const layout = 'auth'

  10. Understand the route context execution order

    main

    When a route is loaded, @fastify/vue executes lifecycle functions in a specific order to prepare the context. Understanding this order is crucial for managing data flow between the server and client.

    Execution Flow:

    1. context.js (default export): Runs first to populate the global state.
    2. getData(): Runs next to fetch route-specific data, which populates the data property in the route context.
    3. getMeta(): Runs to resolve page metadata, populating the head property.
    4. onEnter(): Runs after metadata is resolved.
    5. Component Render: The Vue component finally renders using the prepared context.

  11. Use smart imports with the $app/ prefix

    main

    The @fastify/react package uses a $app/ prefix to implement smart imports. When you import a module using this prefix, the system first checks if the file exists in your local Vite project root. If it does not exist, it provides the default version stored inside the @fastify/react package.

    This allows you to keep your project directory clean by only including files you wish to customize, while relying on the package for standard boilerplate logic like mounting, routing, and context initialization.

  12. Define React Route Modules

    main

    Route modules are React components located in your route search path (defaulting to <project-root>/pages or client/pages). A route module is a file that can export several special functions to control data fetching, metadata, lifecycle events, and rendering modes.

    Supported exports:

    • default: The React component for the route.
    • getData(): Universal data fetching function.
    • getMeta(): Universal page metadata function.
    • onEnter(): Universal route enter event.
    • clientOnly: Boolean to disable server-side rendering (SSR).
    • serverOnly: Boolean to disable client-side rendering (ships static markup).
    • streaming: Boolean to enable streaming SSR.
    export default function MyPage() {
  return <div>My Route</div>
}