Vite Plugin for File-System API Routes

Common errors

• Error: [vite-plugin-api-routes] No API routes found in configured directory: /path/to/your/project/src/api

  cause The `dir` option in the plugin configuration points to a non-existent or empty directory, or the path is incorrect relative to `process.cwd()`.
  fix Verify the `dir` path in `vite.config.ts` is correct and contains valid API route files (e.g., `GET.ts`, `index.ts`). It's recommended to use `path.resolve(process.cwd(), 'your/path')` for robust absolute path resolution.

• 404 Not Found response for an API endpoint that should exist.

  cause The `base` option in the plugin configuration doesn't match the URL prefix being accessed, or the route file name/structure doesn't match the expected path based on the chosen `mode`.
  fix Check that the `base` option (e.g., `/api`) matches the URL prefix used in your client-side requests (e.g., `fetch('/api/my-route')`). Also, ensure your route files (e.g., `src/api/my-route/GET.ts`) correctly map to the desired endpoint according to the `ISOLATED` or `LEGACY` routing mode.

• TypeError: Cannot read properties of undefined (reading 'json') or similar Express-related errors within route handlers.

  cause The API route handler is not correctly exporting a default function, or the function signature does not match Express's `(req, res, next)` expectation, leading to `res` (or other Express objects) being undefined or not having expected methods.
  fix Ensure your API route files `export default` an Express-compatible handler function, e.g., `export default (req, res) => { res.status(200).json(...) }`. Also, ensure `express` is installed if you are using its types or features directly.

Warnings

• breaking The package is currently in beta (`1.3.0-beta1`). The API, features, and internal implementation may change significantly before a stable `1.0` release, potentially introducing breaking changes for users relying on pre-release versions.
  Fix: Review release notes diligently for each update and consider locking dependency versions to specific beta releases for stability in production environments, though this is generally not recommended for beta software.
• gotcha The plugin offers two distinct routing modes: `ISOLATED` (one file per HTTP method, e.g., `GET.ts`) and `LEGACY` (multiple methods via named exports in a single `index.ts` file). Mixing paradigms or misunderstanding the implications can lead to unexpected route resolution or missed endpoints.
  Fix: Clearly define and consistently apply one routing mode (via the `mode` option in the plugin configuration) across your entire API directory structure. The default mode is `ISOLATED`.
• gotcha While the `mapper` attribute allows for fine-grained control over middleware execution priority, incorrect or overlapping priority definitions, especially with `USE` methods, can lead to unexpected middleware bypasses or incorrect request handling order.
  Fix: Carefully define priorities, especially for `USE` methods, and test middleware chains thoroughly. Ensure unique and logical priority values to prevent conflicts and ensure middleware executes as intended.

Install

• npm install vite-plugin-api-routes npm
• yarn add vite-plugin-api-routes yarn
• pnpm add vite-plugin-api-routes pnpm

Imports

• api
  wrong:

  const api = require('vite-plugin-api-routes');

  correct:

  import api from 'vite-plugin-api-routes';

  The plugin is exported as a default ESM module. Direct CommonJS `require()` is not supported for configuration.
• Request, Response (types)
  wrong:

  import { Request, Response } from 'express';

  correct:

  import type { Request, Response } from 'express';

  These types from `express` are crucial for TypeScript development of API route handlers. Ensure `express` is installed as a dependency (`npm install express @types/express`) for correct type inference and runtime behavior.

Quickstart

This quickstart demonstrates how to configure `vite-plugin-api-routes` in `vite.config.ts` to enable file-system based API routing. It sets up the plugin to serve routes from `src/api` under the `/api` URL prefix using `ISOLATED` mode, and includes a simple `GET` route handler for `/api/hello`.

// vite.config.ts
import { defineConfig } from 'vite';
import apiRoutes from 'vite-plugin-api-routes';
import path from 'node:path';

export default defineConfig({
  plugins: [
    apiRoutes({
      // Specifies the root directory where your API route files are located.
      // This example uses 'src/api' relative to the project root.
      dir: path.resolve(process.cwd(), 'src/api'),
      // Defines the base URL path under which these API routes will be served.
      // e.g., files in 'src/api/hello/GET.ts' will be accessible under '/api/hello'
      base: '/api',
      // Choose a routing mode: 'ISOLATED' (default) or 'LEGACY'.
      // 'ISOLATED' means one file per HTTP method (e.g., GET.ts, POST.ts).
      // 'LEGACY' means a single index.ts can export multiple method handlers.
      mode: 'ISOLATED'
    })
  ]
});

// src/api/hello/GET.ts (create this file)
// This file will handle GET requests to /api/hello
import type { Request, Response } from 'express';

export default (req: Request, res: Response) => {
  res.status(200).json({ message: 'Hello from Vite API Routes!', method: req.method });
};

// To run:
// 1. Create vite.config.ts and src/api/hello/GET.ts in your project root.
// 2. npm install vite vite-plugin-api-routes express @types/express
// 3. Add "dev": "vite" to your package.json scripts.
// 4. Run `npm run dev` and visit http://localhost:5173/api/hello in your browser.