vite-plugin-api-routes


Vision

vite-plugin-api-routes enhances API routing in ViteJS based on directory structure for improved visibility and project organization in Node.js and Express applications.

Motivation

- Simplify project configuration
- Convert the directory tree into automatic routing rules

Routing Modes

The plugin offers two approaches to define API routes:

$3

In this approach, a single file can handle multiple HTTP methods through named exports.

Example structure:

``bash
$ tree src/api-legacy
src/api-legacy
├── index.js
└── user
├── [id]
│ └── index.js
├── confirm.js
└── index.js
`

Generated mapping:

`bash
USE /api/ src/api-legacy/index.js?fn=default
GET /api/ src/api-legacy/index.js?fn=GET
POST /api/ src/api-legacy/index.js?fn=POST
PATCH /api/ src/api-legacy/index.js?fn=PATCH
PUT /api/ src/api-legacy/index.js?fn=PUT
DELETE /api/ src/api-legacy/index.js?fn=DELETE
USE /api/user/ src/api-legacy/user/index.js?fn=USE
GET /api/user/ src/api-legacy/user/index.js?fn=GET
POST /api/user/ src/api-legacy/user/index.js?fn=POST
PATCH /api/user/ src/api-legacy/user/index.js?fn=PATCH
PUT /api/user/ src/api-legacy/user/index.js?fn=PUT
DELETE /api/user/ src/api-legacy/user/index.js?fn=DELETE
USE /api/user/confirm src/api-legacy/user/confirm.js?fn=default
GET /api/user/confirm src/api-legacy/user/confirm.js?fn=GET


... and many more routes


`

LEGACY mode features:

- Simple at the file system level
- One file handles multiple HTTP methods
- Hides the actual route structure
- Ideal for APIs with few endpoints or small projects

$3

In this approach, each HTTP method is defined in a separate file, which improves the visibility of available routes.

Example structure:

`bash
$ tree src/api-isolated
src/api-isolated
├── GET.js
├── USE.js
└── user
├── [id]
│ ├── DELETE.js
│ ├── PATCH.js
│ ├── PUT.js
│ └── USE.js
├── confirm
│ └── POST.js
├── GET.js
└── POST.js
`

Generated mapping:

`log
USE /api/ src/api-isolated/USE.js
GET /api/ src/api-isolated/GET.js
GET /api/user/ src/api-isolated/user/GET.js
POST /api/user/ src/api-isolated/user/POST.js
POST /api/user/confirm/ src/api-isolated/user/confirm/POST.js
USE /api/user/:id/ src/api-isolated/user/[id]/USE.js
PATCH /api/user/:id/ src/api-isolated/user/[id]/PATCH.js
PUT /api/user/:id/ src/api-isolated/user/[id]/PUT.js
DELETE /api/user/:id/ src/api-isolated/user/[id]/DELETE.js
`

ISOLATED mode features:

- More explicit and understandable mapping
- One file per HTTP method
- Clear visibility of available endpoints
- Better organization for complex APIs
- Easier long-term maintenance

Priority Mapping System

All methods are mapped to routes with priorities defined by the mapper attribute, allowing precise control over middleware execution order.

Example configuration:

`java
import { defineConfig } from "vite";
import api from "vite-plugin-api-routes";

export default defineConfig({
plugins: [
api({
mapper: {
// Default Mapping
// default: { method: "use", priority: 10 },
// USE: { method: "use", priority: 20 },
// GET: { method: "get", priority: 30 },
// POST: { method: "post", priority: 40 },
// PATCH: { method: "patch", priority: 50 },
// PUT: { method: "put", priority: 60 },
// DELETE: { method: "delete", priority: 70 },
// New Default Mapping from 1.2.6
// AUTH: { method: "use", priority: 11 },
// CRUD: { method: "use", priority: 12 },
// PING: { method: "get", priority: 21 },
// ACTION: { method: "post", priority: 41 },
// ERROR: { method: "use", priority: 120 },
// Custom aliases
AUTH: { method: "use", priority: 11 }, // After default and before USE
ERROR: { method: "use", priority: 120 }, // After DELETE, FILES, and PARAMS
LOGGER: { method: "use", priority: 31 }, // After GET and before POST
},
filePriority: 100, // Default priority for files
paramPriority: 110, // Default priority for PATH with parameters
}),
],
});
`

Example structure:

`bash
$ tree src/api-isolated/
src/api-isolated/
├── AUTH.js
├── ERROR.js
├── GET.js
├── USE.js
└── user
├── [id]
│ ├── DELETE.js
│ ├── PATCH.js
│ ├── PUT.js
│ └── USE.js
├── confirm
│ └── POST.js
├── ERROR.js
├── GET.js
├── LOGGER.js
└── POST.js
`

Generated mapping (respecting priorities):

`js
USE /api/ src/api-isolated/AUTH.js // after default and before USE
USE /api/ src/api-isolated/USE.js
GET /api/ src/api-isolated/GET.js
GET /api/user/ src/api-isolated/user/GET.js
USE /api/user/ src/api-isolated/user/LOGGER.js // after GET and before POST
POST /api/user/ src/api-isolated/user/POST.js
POST /api/user/confirm/ src/api-isolated/user/confirm/POST.js
USE /api/user/:id/ src/api-isolated/user/[id]/USE.js
PATCH /api/user/:id/ src/api-isolated/user/[id]/PATCH.js
PUT /api/user/:id/ src/api-isolated/user/[id]/PUT.js
DELETE /api/user/:id/ src/api-isolated/user/[id]/DELETE.js
USE /api/user/ src/api-isolated/user/ERROR.js // after DELETE, FILES, and PARAMS
USE /api/ src/api-isolated/ERROR.js // after DELETE, FILES, and PARAMS
`

Installation and Basic Configuration

$3

`bash
yarn add vite-plugin-api-routes
`

$3

`js
import { defineConfig } from "vite";
import api from "vite-plugin-api-routes";

export default defineConfig({
plugins: [
api(), // with default configuration
],
});
`

$3

To access type definitions, include the generated file in your project:

In src/vite-env.d.ts, add:

`ts
///
`

Customization

The plugin allows customizing three main components:

- Handler File: /src/handler.js - Customize the route handler
- Server File: /src/server.ts - Customize the Express server
- Configure File: /src/configure.ts - Customize server configuration

Execution Environments

$3

In development, the plugin serves API routes through the Vite server with HMR support:

`bash
yarn dev
`

$3

To build your application for production, run:

`bash
yarn build
`

To skip building the server, use:

`bash
yarn build --server-skip
`

To skip building the client, use:

`bash
yarn build --client-skip
``

Additional Resources

- npm Package: vite-plugin-api-routes
- GitHub Repository: yracnet/vite-plugin-api-routes
- Articles:
- Enhancing API Routing in Vite.js with vite-plugin-api
- CRUD User API + GUI in ViteJS
- Tutorials:
- Tutorial Legacy
- Tutorial Isolated
- Tutorial CRUD
- Previous Documentation:
- README 1.0

License

This project is licensed under the MIT License.

Version Notes

$3

🙏 Dear Community,

We sincerely apologize for the recent project name changes. After careful consideration and feedback, we've settled on the name vite-plugin-api-routes. We understand that these changes might have caused confusion, and we appreciate your understanding.

Thank you for your continued support and flexibility.

Best regards,

Willyams Yujra