alex-fastify-inertiajs

v1.0.8

Published

2 months ago

A lightweight Fastify plugin for Inertia.js that lets you build modern single-page applications with server-side rendering.

0High
0Medium
0Low

alex-j-b

inertiajs fastify fastify-inertia fastify-plugin fastify-inertiajs-plugin

fastify-inertiajs

A lightweight Fastify plugin for Inertia.js that lets you build modern single-page applications with server-side rendering. It allows seamless integration of React, Vue, or Svelte components while preserving the simplicity of classic apps.

Features

Server-Side Rendering (SSR) support for improved SEO and performance
Vite integration for fast development and optimized builds
Framework agnostic - works with React, Vue, or Svelte
Lightweight Fastify plugin with minimal configuration
TypeScript support with full type definitions

Quick Start

The fastest way to get started is using our official templates:

# For React
npx degit mahendra7041/fastify-inertia/examples/react my-inertia-app

# For Vue
npx degit mahendra7041/fastify-inertia/examples/vue my-inertia-app

# For Svelte
npx degit mahendra7041/fastify-inertia/examples/svelte my-inertia-app

cd my-inertia-app
npm install
npm run dev

Setup Guide

Prerequisites

Node.js 18 or higher
Fastify
Vite

Step 1: Create a Vite Project

First, create a new project using Vite with your preferred framework:

# For React (used in this guide)
npm create vite@latest my-inertia-app -- --template react

# For Vue
npm create vite@latest my-inertia-app -- --template vue

# For Svelte
npm create vite@latest my-inertia-app -- --template svelte

cd my-inertia-app

Step 2: Install Required Packages

Install the necessary dependencies for Fastify and Inertia:

# For React (used in this guide)
npm install fastify-inertiajs @fastify/cookie @fastify/static @inertiajs/react

# For Vue
npm install fastify-inertiajs @fastify/cookie @fastify/static @inertiajs/vue3

# For Svelte
npm install fastify-inertiajs @fastify/cookie @fastify/static @inertiajs/svelte

# Additional dev dependencies
npm install -D nodemon

Step 3: Project Structure

Set up your project structure as follows:

my-inertia-app/
├── build/                 # Generated build artifacts
├── public/                # Static assets
├── src/
│   ├── pages/            # Inertia page components
│   ├── assets/           # Styles, images, etc.
│   ├── main.jsx          # Client entry point (or .js/.vue/.svelte)
│   └── ssr.jsx           # SSR entry point (optional)
├── index.html            # HTML template
├── vite.config.js        # Vite configuration
├── server.js             # Fastify server
└── package.json

Step 4: Update HTML Template (`index.html`)

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!-- @inertiaHead -->
  </head>
  <body
    class="bg-neutral-50 text-black selection:bg-teal-300 dark:bg-neutral-900 dark:text-white dark:selection:bg-pink-500 dark:selection:text-white"
  >
    <!-- @inertia -->
    <script type="module" src="/src/main.Jsx"></script>
  </body>
</html>

Step 5: Fastify Server Setup (`server.js`)

import fastify from "fastify";
import fastifyStatic from "@fastify/static";
import fastifyCookie from "@fastify/cookie";
import inertia from "fastify-inertiajs";
import path from "path";
import { fileURLToPath } from "url";

const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);

async function bootstrap() {
  const app = fastify();
  const PORT = process.env.PORT || 5000;

  // Serve static files in production
  if (process.env.NODE_ENV === "production") {
    await app.register(fastifyStatic, {
      root: path.join(__dirname, "build/client"),
      prefix: "/",
      decorateReply: false,
    });
  }

  await app.register(fastifyCookie);

  await app.register(inertia, {
    rootElementId: "root",
    assetsVersion: "v1",
    ssrEnabled: true,
    ssrEntrypoint: "src/ssr.jsx",
    ssrBuildEntrypoint: "build/ssr/ssr.js",
  });

  app.get("/", (req, reply) => {
    reply.inertia.render("home");
  });

  try {
    await app.listen({ port: PORT });
    console.log(`Server is running at http://localhost:${PORT}`);
  } catch (err) {
    console.error(err);
    process.exit(1);
  }
}

bootstrap().catch(console.error);

Step 6: Update Package.json Scripts

{
  "scripts": {
    "dev": "nodemon server.js",
    "start": "cross-env NODE_ENV=production node server.js",
    "build": "npm run build:ssr && npm run build:client",
    "build:client": "vite build --outDir build/client",
    "build:ssr": "vite build --outDir build/ssr --ssr src/ssr.jsx"
  }
}

Step 7: Client Entry Point (src/main.jsx)

Update your framework's main entry point accordingly. For more details, visit Inertia.js Client-Side Setup:

import { createInertiaApp } from "@inertiajs/react";
import { createRoot } from "react-dom/client";

createInertiaApp({
  id: "root",
  resolve: (name) => {
    const pages = import.meta.glob("./pages/**/*.jsx", { eager: true });

    return pages[`./pages/${name}.jsx`];
  },
  setup({ el, App, props }) {
    createRoot(el).render(<App {...props} />);
  },
});

Step 8: SSR Entry Point (src/ssr.jsx) - Optional

Add Server-Side Rendering support for improved SEO and performance.

import ReactDOMServer from "react-dom/server";
import { createInertiaApp } from "@inertiajs/react";

export default function render(page) {
  return createInertiaApp({
    id: "root",
    page,
    render: ReactDOMServer.renderToString,
    resolve: (name) => {
      const pages = import.meta.glob("./pages/**/*.jsx", { eager: true });

      return pages[`./pages/${name}.jsx`];
    },
    setup: ({ App, props }) => <App {...props} />,
  });
}

Configuration

Middleware Options

| Option | Type | Default | Description | | ---------------------- | -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- | | rootElementId | string? | "app" | DOM element ID where the Inertia app mounts | | assetsVersion | string? | "v1" | Version string used for inertia | | encryptHistory | boolean? | true | Encrypts the Inertia history state for security | | indexEntrypoint | string? | "index.html" | Path to your base HTML template (used in dev mode) | | indexBuildEntrypoint | string? | "build/client/index.html" | Path to the built client HTML entrypoint (used in production) | | ssrEnabled | boolean? | false | Enables/disables server-side rendering (SSR) | | ssrEntrypoint | string? | Required if ssrEnabled: true | Path to your SSR entry file (used in development) | | ssrBuildEntrypoint | string? | Required if ssrEnabled: true | Path to the built SSR bundle (used in production) | | vite | ViteResolveConfig? | { server: { middlewareMode: true }, appType: "custom" } | Passes custom options to the Vite dev server |

API Reference

`inertia(config?, vite?)`

Initializes and returns the Fastify middleware.

await fastify.register(inertia, inertiaConfig);

`reply.inertia.render(component, props?)`

Renders an Inertia page component.

fastify.get('/users', (request, reply) => {
  const users = await User.findAll();

  reply.inertia.render('user/index', {
    users: users,
    page: req.query.page || 1
  });
});

`reply.inertia.share(data)`

Shares data with the current and subsequent requests.

reply.inertia.share({
  auth: {
    user: req.user,
    permissions: req.user?.permissions,
  },
});

`reply.inertia.redirect(urlOrStatus, url?)`

Redirects the user to a different location while preserving Inertia’s client-side navigation.

fastify.get("/home", (req, reply) => {
  // Redirect with default status (302 Found)
  reply.inertia.redirect("/dashboard");

  // Redirect with explicit status
  reply.inertia.redirect(301, "/new-home");
});

Contributing

We welcome contributions! Please feel free to submit issues, feature requests, or pull requests.

Guidelines

Fork the repository
Create your feature branch:
```
git checkout -b feat/amazing-feature
```
Commit your changes with a descriptive message:
```
git commit -m "feat: add amazing feature"
```
Push to your branch:
```
git push origin feat/amazing-feature
```
Open a Pull Request

Breaking Changes

If your contribution introduces a breaking change (e.g. changes to configuration options, API methods, or default behavior), please open an issue or discussion first before submitting a PR. This ensures we can:

Discuss the impact on existing users
Decide if a major version bump is required
Provide a clear migration path in the documentation

License

This project is licensed under the MIT License - see the LICENSE file for details.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme