#Introduction

#What is VextJS?

VextJS is a modern Node.js web framework designed for building high-performance RESTful APIs. It provides enterprise-level features such as Adapter architecture (the underlying HTTP framework can be replaced), plug-in system, conventional routing, automatic service injection, declarative parameter verification, automatic generation of OpenAPI documents, etc., allowing you to focus on business logic.

import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.get(
    "/hello",
    {
      docs: { summary: "Greeting Interface" },
    },
    async (_req, res) => {
      res.json({ message: "Hello VextJS!" });
    },
  );
});

#Core Features

#🔌 Adapter architecture

VextJS's underlying HTTP handling layer is replaceable. Built-in 5 kinds of Adapters:

Switching the Adapter only requires modifying one line of configuration, with zero changes to the business code:

// src/config/default.ts
import { nativeAdapter } from "vextjs/adapters/native";
// import { honoAdapter } from 'vextjs/adapters/hono';
// import { fastifyAdapter } from 'vextjs/adapters/fastify';

export default {
  adapter: nativeAdapter(),
  port: 3000,
};

#⚡ Ultimate performance

Historical benchmark snapshot (JSON response scenario, median of 5 rounds):

The overhead of Vext includes: body parser, response wrapper, request/response abstraction, AsyncLocalStorage context, middleware chain executor, etc. complete functions.

⚠️ Test environment description: The above table is a historical snapshot of 2026-03-23, measured based on Node.js v24.14.0 / Windows x64 / Intel i7-9700 / autocannon (50 connections, 10 pipelining, 10s × 5 rounds median). The current version reproduces the actual test based on test/benchmark/run-benchmark.mjs in the warehouse, and distinguishes between chain and middleware-chain. For complete details, see Performance Benchmark.

#🛡️ Declarative parameter verification

Integrate schema-dsl, declare verification rules in routing options, automatically verify + automatically generate OpenAPI documents:

app.post(
  "/users",
  {
    validate: {
      body: {
        name: "string!", // required string
        email: "email!", // Required email format
        age: "number?", // optional number
        role: "admin|user", // enumeration
      },
    },
    docs: { summary: "Create user" },
  },
  async (req, res) => {
    // req.body has passed verification and is type safe
    const user = await app.services.user.create(req.body);
    res.json(user);
  },
);

#🧩 Plug-in system

Extend the framework capabilities through definePlugin() to support complete life cycle hooks:

import { definePlugin } from "vextjs";

export default definePlugin({
  name: "user-cache-plugin",

  async setup(app) {
    //Register capabilities on the app
    const cache = new Map();
    app.extend("userCache", {
      get: (key: string) => cache.get(key),
      set: (key: string, value: unknown, ttl?: number) => {
        cache.set(key, value);
        if (ttl) setTimeout(() => cache.delete(key), ttl);
      },
    });
  },

  async onReady(app) {
    app.logger.info("Cache plugin ready");
  },

  async onClose(app) {
    // Clean up resources
  },
});

#🧱 Module system and decorator strategy

VextJS uses ESM + conventional directories as the module system: src/config/, src/plugins/, src/middlewares/, src/services/, src/routes/ will be automatically scanned at startup and loaded in the order of configuration → plug-ins → middleware definition → services → routes.VextJS currently does not provide decorator APIs such as @Controller / @Get / @Inject / @Service, nor does it rely on reflect-metadata. Routes use defineRoutes(), plugins use definePlugin(), and services are injected into app through the new ServiceClass(app) constructor. If you are migrating from a decorator framework such as NestJS, please migrate controller decorators to src/routes/*.ts file routes and constructor dependency injection to app.services delayed access.

#🔥 Development experience

• vext dev — File monitoring + smart hot reload (Soft Reload Tier 1/2 + Cold Restart Tier 3)
• vext build — esbuild extremely fast build, TypeScript zero configuration
• vext create — interactive scaffolding that supports 5 Adapter choices
• OpenAPI/Scalar — Automatically generated based on routing docs + validate, visit /docs to view (built-in Try it out interactive test)

#🏢 Enterprise-level features

• Cluster multi-process — ClusterMaster + Worker heartbeat + Rolling Restart + Graceful shutdown
• Internationalization (i18n) — Language packs are loaded automatically, error messages are in multiple languages
• Built-in rate limit — based on flex-rate-limit, supports IP / user dimension
• Request Tracking — AsyncLocalStorage runs through route → service and automatically injects requestId
• MonSQLize plugin — Built-in database plugin, conditional loading with zero overhead

#Design concept

#1. Convention is better than configuration

Following fixed project structure conventions (src/routes/, src/services/, src/config/), the framework automatically scans and loads without manual registration.

#2. Layered architecture

Routing layer (routes) ← Parameter extraction + response return
   ↓
Service layer (services) ← Business logic (pure data, not aware of HTTP)
   ↓
Data layer (models) ← Data access (provided through plugins)

• The routing handler is only responsible for parameter extraction and response return
• Business logic is concentrated in the service layer, accessed through app.services.xxx
• The service is not aware of the HTTP protocol, making it easy to reuse and test

#3. The bottom layer is replaceable

Through the Adapter architecture, the core of the framework is completely decoupled from underlying HTTP processing. All business code (routing, middleware, services, plug-ins) operates on the req / res objects encapsulated by VextJS, rather than the native objects of the underlying framework.

#Compare with other frameworks

#Environmental requirements

• Node.js >= 20.19.0
• TypeScript 5.x (recommended, pure JavaScript is also supported)

#Next step

Are you ready? Go to Quick Start(/guide/quick-start) to create your first VextJS project.