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:

LEGACY Mode

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

Example structure:

1$ tree src/api-legacy
2src/api-legacy
3├── index.js
4└── user
5    ├── [id]
6    │   └── index.js
7    ├── confirm.js
8    └── index.js

Generated mapping:

1USE     /api/                src/api-legacy/index.js?fn=default
2GET     /api/                src/api-legacy/index.js?fn=GET
3POST    /api/                src/api-legacy/index.js?fn=POST
4PATCH   /api/                src/api-legacy/index.js?fn=PATCH
5PUT     /api/                src/api-legacy/index.js?fn=PUT
6DELETE  /api/                src/api-legacy/index.js?fn=DELETE
7USE     /api/user/           src/api-legacy/user/index.js?fn=USE
8GET     /api/user/           src/api-legacy/user/index.js?fn=GET
9POST    /api/user/           src/api-legacy/user/index.js?fn=POST
10PATCH   /api/user/           src/api-legacy/user/index.js?fn=PATCH
11PUT     /api/user/           src/api-legacy/user/index.js?fn=PUT
12DELETE  /api/user/           src/api-legacy/user/index.js?fn=DELETE
13USE     /api/user/confirm    src/api-legacy/user/confirm.js?fn=default
14GET     /api/user/confirm    src/api-legacy/user/confirm.js?fn=GET
15# ... 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

ISOLATED Mode

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

Example structure:

1$ tree src/api-isolated
2src/api-isolated
3├── GET.js
4├── USE.js
5└── user
6    ├── [id]
7    │   ├── DELETE.js
8    │   ├── PATCH.js
9    │   ├── PUT.js
10    │   └── USE.js
11    ├── confirm
12    │   └── POST.js
13    ├── GET.js
14    └── POST.js

Generated mapping:

1USE     /api/                 src/api-isolated/USE.js
2GET     /api/                 src/api-isolated/GET.js
3GET     /api/user/            src/api-isolated/user/GET.js
4POST    /api/user/            src/api-isolated/user/POST.js
5POST    /api/user/confirm/    src/api-isolated/user/confirm/POST.js
6USE     /api/user/:id/        src/api-isolated/user/[id]/USE.js
7PATCH   /api/user/:id/        src/api-isolated/user/[id]/PATCH.js
8PUT     /api/user/:id/        src/api-isolated/user/[id]/PUT.js
9DELETE  /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:

1import { defineConfig } from "vite";
2import api from "vite-plugin-api-routes";
3
4export default defineConfig({
5  plugins: [
6    api({
7      mapper: {
8        // Default Mapping
9        default: { method: "use",    priority: 10 },
10        USE:     { method: "use",    priority: 20 },
11        GET:     { method: "get",    priority: 30 },
12        POST:    { method: "post",   priority: 40 },
13        PATCH:   { method: "patch",  priority: 50 },
14        PUT:     { method: "put",    priority: 60 },
15        DELETE:  { method: "delete", priority: 70 },
16        // Custom aliases
17        AUTH:    { method: "use", priority: 11  }, // After default and before USE
18        ERROR:   { method: "use", priority: 120 }, // After DELETE, FILES, and PARAMS
19        LOGGER:  { method: "use", priority: 31  }, // After GET and before POST
20      },
21      filePriority:  100, // Default value for files
22      paramPriority: 110, // Default value for parameters
23    }),
24  ],
25});

Example structure:

1$ tree src/api-isolated/
2src/api-isolated/
3├── AUTH.js
4├── ERROR.js
5├── GET.js
6├── USE.js
7└── user
8    ├── [id]
9    │   ├── DELETE.js
10    │   ├── PATCH.js
11    │   ├── PUT.js
12    │   └── USE.js
13    ├── confirm
14    │   └── POST.js
15    ├── ERROR.js
16    ├── GET.js
17    ├── LOGGER.js
18    └── POST.js

Generated mapping (respecting priorities):

1USE     /api/                 src/api-isolated/AUTH.js          // after default and before USE
2USE     /api/                 src/api-isolated/USE.js
3GET     /api/                 src/api-isolated/GET.js
4GET     /api/user/            src/api-isolated/user/GET.js
5USE     /api/user/            src/api-isolated/user/LOGGER.js   // after GET and before POST
6POST    /api/user/            src/api-isolated/user/POST.js
7POST    /api/user/confirm/    src/api-isolated/user/confirm/POST.js
8USE     /api/user/:id/        src/api-isolated/user/[id]/USE.js
9PATCH   /api/user/:id/        src/api-isolated/user/[id]/PATCH.js
10PUT     /api/user/:id/        src/api-isolated/user/[id]/PUT.js
11DELETE  /api/user/:id/        src/api-isolated/user/[id]/DELETE.js
12USE     /api/user/            src/api-isolated/user/ERROR.js    // after DELETE, FILES, and PARAMS
13USE     /api/                 src/api-isolated/ERROR.js         // after DELETE, FILES, and PARAMS

Installation and Basic Configuration

Installation

1yarn add vite-plugin-api-routes

Vite Configuration

1import { defineConfig } from "vite";
2import api from "vite-plugin-api-routes";
3
4export default defineConfig({
5  plugins: [
6    api(), // with default configuration
7  ],
8});

TypeScript Configuration

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

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

1/// <reference path="../.api/env.d.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

Development Mode

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

1yarn dev

Production Mode

For production, build your application normally:

1yarn build

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

Project Renaming

🙏 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