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:

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

Generated mapping:

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

ISOLATED Mode

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

Example structure:

$ 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:

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:

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:

$ 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):

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

Installation

yarn add vite-plugin-api-routes

Vite Configuration

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

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

TypeScript Configuration

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

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

/// <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:

yarn dev

Production Mode

To build your application for production, run:

yarn build

To skip building the server, use:

yarn build --server-skip

To skip building the client, use:

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

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