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:

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
• OpenAPI docs: in this version you can add GET.yml as documentation of a service, from summary and description content

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

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
  • README 1.1

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