vite-plugin-fastify-routes

File-based routing for Fastify applications using Vite.

Installation

Install vite-plugin-fastify-routes with your favorite package manager:

$ npm i vite-plugin-fastify-routes -D
# or
$ yarn add vite-plugin-fastify-routes -D
# or
$ pnpm i vite-plugin-fastify-routes -D
# or
$ bun add vite-plugin-fastify-routes -D

Usage

Add Scripts

Add the following scripts to your package.json file:

{
  // ...
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview",
  },
  // ...
}

Configure Vite

Configure Vite by creating a vite.config.ts file in the root directory of your project, as shown below:

// vite.config.ts
import { resolve } from 'path';
import { defineConfig } from 'vite';
import fastify from 'vite-plugin-fastify';
import fastifyRoutes from 'vite-plugin-fastify-routes';

export default defineConfig({
  server: {
    host: '127.0.0.1',
    port: 3000,
  },
  plugins: [
    fastify(),
    fastifyRoutes(), // Default: { routesDir: './src/routes' }
  ],
  resolve: {
    alias: {
      '~': resolve(__dirname, 'src'),
    },
  },
});

Create the Fastify Application

Create a Fastify application by defining src/app.ts:

// src/app.ts
import type { FastifyServerOptions } from 'fastify';
import fastify from 'fastify';

import router from '~/plugins/router';

const app = async (options: FastifyServerOptions = {}) => {
  const app = fastify(options);

  app.register(router);

  return app;
};

export default app;

Start the Server

Start the server by defining src/server.ts:

// src/server.ts
import app from './app';

const start = async () => {
  const server = await app({
    logger: {
      transport: {
        target: '@fastify/one-line-logger',
      },
    },
  });

  try {
    server.listen({ host: '127.0.0.1', port: 3000 });
  } catch (err) {
    server.log.error(err);
    process.exit(1);
  }
};

start();

Create the Router Plugin

Create the router plugin by defining src/plugins/router.ts:

// src/plugins/router.ts
import plugin from 'fastify-plugin';

import routes from 'virtual:fastify-routes';

export default plugin(
  async (app) => {
    routes(app, { prefix: '/api' });
  },
  { name: 'router' },
);

Type

// vite-env.d.ts
/// <reference types="vite-plugin-fastify-routes/client" />

Define Routes (Route Handlers)

Define routes by creating a +handler.ts (or .js) file in the src/routes directory:

src/routes/path/to/+handler.ts
# or
src/routes/path/to/+handler.js

// src/routes/hello-world/+handler.ts
import type { FastifyInstance } from 'fastify';

export default async (app: FastifyInstance) => {
  // curl http://127.0.0.1:3000/api/hello-world
  app.get('', async (request, reply) => {
    return reply.send({ message: 'hello-world' });
  });
};

Route File Naming Convention

The file naming convention for the routes is as follows:

src/routes/hello-world/+handler.ts -> /hello-world

src/routes/products/+handler.ts -> /products
src/routes/products/[id]/+handler.ts -> /products/:id

src/routes/posts/[[title]]/+handler.ts -> /posts/:title?

src/routes/blog/[...info]/+handler.ts -> /blog/*

src/routes/(group)/foo/+handler.ts -> /foo
src/routes/(group)/bar/+handler.ts -> /bar

src/routes/(freeze)/+handler.ts -> /

// src/routes/path/to/+handler.ts
import type { FastifyInstance } from 'fastify';

export default async (app: FastifyInstance) => {
  // The path parameter can be initialized with an empty string.
  app.get('', async (request, reply) => {
    // Focus on your handler here
  });
};

Define Hooks (Middleware)

Define hooks by creating a +hook.ts (or .js) file in the src/routes directory:

src/routes/path/to/+hook.ts
# or
src/routes/path/to/+hook.js

// src/routes/path/to/+hook.ts
import plugin from 'fastify-plugin';

export default plugin(async (app) => {
  app.addHook('preHandler', async (request, reply) => {
    await new Promise((resolve, reject) => {
      console.log('preHandler');
      resolve('');
    });
  });
});

Hook File Naming Convention

The file naming convention for the routes is as follows:

routes
├── hooked
│   ├── +handler.ts
│   ├── +hook.ts # request.hookOne = 'yes'
│   └── children
│       ├── +handler.ts
│       └── grandchildren
│           ├── +handler.ts
│           └── +hook.ts # request.hookTwo = 'yes'
└── standard
    └── +handler.ts

// src/routes/hooked/+hook.ts
import plugin from 'fastify-plugin';

export default plugin(async (app) => {
  app.addHook('preHandler', async (request, reply) => {
    request.hookOne = 'yes';
  });
});

// src/routes/hooked/children/grandchildren/+hook.ts
import plugin from 'fastify-plugin';

export default plugin(async (app) => {
  app.addHook('preHandler', async (request, reply) => {
    request.hookTwo = 'yes';
  });
});

$ curl http://127.0.0.1:3000/api/hooked
# { hookOne: 'yes', hookTwo: undefined }

$ curl http://127.0.0.1:3000/api/hooked/children
# { hookOne: 'yes', hookTwo: undefined }

$ curl http://127.0.0.1:3000/api/hooked/children/grandchildren
# { hookOne: 'yes', hookTwo: 'yes' }

$ curl http://127.0.0.1:3000/api/standard
# { hookOne: undefined, hookTwo: undefined }

If the hook only needs to be in the current route, it can be placed within +handler.ts:

routes
├── hooked
│   ├── +handler.ts # request.hook = 'yes'
│   ├── +hook.ts # request.hookOne = 'yes'
│   └── children
│       ├── +handler.ts # request.hookChildren = 'yes'
│       └── grandchildren
│           ├── +handler.ts # request.hookGrandchildren = 'yes'
│           └── +hook.ts # request.hookTwo = 'yes'
└── standard
    └── +handler.ts

// src/routes/hooked/+handler.ts
import type { FastifyInstance } from 'fastify';

export default async (app: FastifyInstance) => {
  app.addHook('preHandler', async (request, reply) => {
    request.hook = 'yes';
  });

  app.get('', async (request, reply) => {
    // ...
  });
};

// src/routes/hooked/children/+handler.ts
import type { FastifyInstance } from 'fastify';

export default async (app: FastifyInstance) => {
  app.addHook('preHandler', async (request, reply) => {
    request.hookChildren = 'yes';
  });

  app.get('', async (request, reply) => {
    // ...
  });
};

// src/routes/hooked/children/grandchildren/+handler.ts
import type { FastifyInstance } from 'fastify';

export default async (app: FastifyInstance) => {
  app.addHook('preHandler', async (request, reply) => {
    request.hookGrandchildren = 'yes';
  });

  app.get('', async (request, reply) => {
    // ...
  });
};

$ curl http://127.0.0.1:3000/api/hooked
# { hookOne: 'yes', hookTwo: undefined }
# { hook: 'yes', hookChildren: undefined, hookGrandchildren: undefined }

$ curl http://127.0.0.1:3000/api/hooked/children
# { hookOne: 'yes', hookTwo: undefined }
# { hook: undefined, hookChildren: 'yes', hookGrandchildren: undefined }

$ curl http://127.0.0.1:3000/api/hooked/children/grandchildren
# { hookOne: 'yes', hookTwo: 'yes' }
# { hook: undefined, hookChildren: undefined, hookGrandchildren: 'yes' }

$ curl http://127.0.0.1:3000/api/standard
# { hookOne: undefined, hookTwo: undefined }
# { hook: undefined, hookChildren: undefined, hookGrandchildren: undefined }