{"id":16266,"library":"vite-plugin-api-routes","title":"Vite Plugin for File-System API Routes","description":"vite-plugin-api-routes is a Vite.js plugin designed to streamline backend API development by implementing a file-system based routing approach, reminiscent of Next.js API Routes. It automatically converts a designated directory structure into API endpoints, enhancing project organization and visibility for Node.js and Express applications integrated with Vite. The package is currently in a beta phase, with version `1.3.0-beta1`, indicating active development. Key differentiators include two distinct routing modes: \"ISOLATED\" where each HTTP method resides in its own file for explicit endpoint declaration, and \"LEGACY\" allowing multiple methods within a single file for simpler APIs. It also provides a priority mapping system to precisely control middleware execution order, supporting advanced API configurations. While in beta, its robust features aim to simplify full-stack Vite projects.","status":"active","version":"1.3.0-beta1","language":"javascript","source_language":"en","source_url":"https://github.com/yracnet/vite-plugin-api-routes","tags":["javascript","vite","api","api-router","api-routers","vite-plugin-api","vite-plugin-rest-api","express","express-router"],"install":[{"cmd":"npm install vite-plugin-api-routes","lang":"bash","label":"npm"},{"cmd":"yarn add vite-plugin-api-routes","lang":"bash","label":"yarn"},{"cmd":"pnpm add vite-plugin-api-routes","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency as a Vite plugin.","package":"vite","optional":false},{"reason":"Required for API route handlers and their types, although not a direct dependency, handlers are Express-compatible.","package":"express","optional":true}],"imports":[{"note":"The plugin is exported as a default ESM module. Direct CommonJS `require()` is not supported for configuration.","wrong":"const api = require('vite-plugin-api-routes');","symbol":"api","correct":"import api from 'vite-plugin-api-routes';"},{"note":"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.","wrong":"import { Request, Response } from 'express';","symbol":"Request, Response (types)","correct":"import type { Request, Response } from 'express';"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport apiRoutes from 'vite-plugin-api-routes';\nimport path from 'node:path';\n\nexport default defineConfig({\n  plugins: [\n    apiRoutes({\n      // Specifies the root directory where your API route files are located.\n      // This example uses 'src/api' relative to the project root.\n      dir: path.resolve(process.cwd(), 'src/api'),\n      // Defines the base URL path under which these API routes will be served.\n      // e.g., files in 'src/api/hello/GET.ts' will be accessible under '/api/hello'\n      base: '/api',\n      // Choose a routing mode: 'ISOLATED' (default) or 'LEGACY'.\n      // 'ISOLATED' means one file per HTTP method (e.g., GET.ts, POST.ts).\n      // 'LEGACY' means a single index.ts can export multiple method handlers.\n      mode: 'ISOLATED'\n    })\n  ]\n});\n\n// src/api/hello/GET.ts (create this file)\n// This file will handle GET requests to /api/hello\nimport type { Request, Response } from 'express';\n\nexport default (req: Request, res: Response) => {\n  res.status(200).json({ message: 'Hello from Vite API Routes!', method: req.method });\n};\n\n// To run:\n// 1. Create vite.config.ts and src/api/hello/GET.ts in your project root.\n// 2. npm install vite vite-plugin-api-routes express @types/express\n// 3. Add \"dev\": \"vite\" to your package.json scripts.\n// 4. Run `npm run dev` and visit http://localhost:5173/api/hello in your browser.","lang":"typescript","description":"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`."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.x.x-beta"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0-beta1"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0-beta1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","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()`.","error":"Error: [vite-plugin-api-routes] No API routes found in configured directory: /path/to/your/project/src/api"},{"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.","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`.","error":"404 Not Found response for an API endpoint that should exist."},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'json') or similar Express-related errors within route handlers."}],"ecosystem":"npm"}