Registry / web-framework / vite-plugin-api-routes

vite-plugin-api-routes

library1.3.0-beta1jsnpmunverified

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.

web-framework http-networking devops

npm install vite-plugin-api-routes

github ↗package ↗

INSTALL

IMPORT

SIG · VITE-PLUGIN-API-RO

vite-plugin-api-routes

web-frameworkjavascriptv1.3.0-beta1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

api

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

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

The plugin is exported as a default ESM module. Direct CommonJS `require()` is not supported for configuration.

Request, Response (types)

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

✗ import { 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.

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.

Debug

Known issues

breakingThe 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.

affects: >=1.x.x-beta

gotchaThe 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`.

affects: >=1.0.0-beta1

gotchaWhile 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.

affects: >=1.0.0-beta1

Errors

Common errors & fixes

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

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.

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.

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.

Upgrade

Version history

1.3.0-beta1latest on npm

Audit

Dependencies

viterequiredPeer dependency as a Vite plugin.

expressoptionalRequired for API route handlers and their types, although not a direct dependency, handlers are Express-compatible.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/yracnet/vite-plugin-api-routes ↗

packagehttps://www.npmjs.com/package/vite-plugin-api-routes ↗