#Routing

VextJS combines convention-based file routing with route declarations inside defineRoutes(). A route file maps to a URL prefix; its factory declares the methods and paths beneath that prefix.

Start with a runnable route, then learn file mapping, request validation, and business integration. For the full fields and defaults, see the Route Definition API; for binding rules, see the HTTP and Routing Specification.

The route-demo.ts below is a complete, standalone file for an existing VextJS project. Other snippets that mention app, req, res, or handler belong inside their respective factory or handler. The business example declares its service and authentication prerequisites separately.

#Run a route first

#1. Create the route file

Prerequisite: a VextJS project created according to Quick Start, with dependencies installed and npm run dev working. Create this file; it needs no database, custom service, or authentication middleware.

// src/routes/route-demo.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.get(
    "/:id",
    { validate: { param: { id: "integer:1-!" } } },
    (req, res) => {
      const { id } = req.valid("param");
      res.json({ id, valueType: typeof id });
    },
  );

  app.post(
    "/",
    { validate: { body: { name: "string:1-50!" } } },
    (req, res) => {
      const { name } = req.valid("body");
      res.json({ name }, 201);
    },
  );
});

#2. Verify paths and validation

Run npm run dev from the project root. In another terminal, use the actual port shown on startup. Save these two request files in the project root so that JSON quoting works consistently across shells:

route-valid.json:

{ "name": "Alice" }

route-invalid.json:

{}

Run these commands from the same directory. In Windows PowerShell, use curl.exe in place of curl:

curl -i http://localhost:3000/route-demo/42
curl -i http://localhost:3000/route-demo/not-a-number
curl -i -X POST http://localhost:3000/route-demo -H "Content-Type: application/json" --data-binary @route-valid.json
curl -i -X POST http://localhost:3000/route-demo -H "Content-Type: application/json" --data-binary @route-invalid.json

The file prefix is /route-demo, so write "/" or "/:id" inside the file; do not add /route-demo again. The response wrapper depends on app configuration, and exact validation messages can vary with the validator and locale.

#3. Integrate business logic

After the minimal route works, pass business operations to a service. Add validation, middleware, authentication, and response declarations as needed.

The local app.get(...) snippets below belong inside defineRoutes((app) => { ... }). Names such as handler, user, data, and app.services.* stand for application code; VextJS does not create those business capabilities automatically.

The factory must be synchronous; handlers may be async. Register routes with direct top-level statements in the factory body, not inside loops, conditionals, or async callbacks. Statically resolvable function bindings and default re-exports are supported; see the factory rules.

#Basic concepts

#File routing mapping

Route files under src/routes/ that pass the loader rules map to URL prefixes. The table shows alternative layouts: users.ts and users/index.ts cannot coexist.

#Three-stage definition

VextJS routing is defined using three-part (path, options, handler) or two-part (path, handler):

// Three-part form: path + options + handler
app.get(
  "/list",
  {
    validate: { query: { page: "number:1-", limit: "number:1-100" } },
    middlewares: ["audit-log"],
    docs: { summary: "User List" },
  },
  async (req, res) => {
    const { page, limit } = req.valid("query");
    res.json(await app.services.user.findAll({ page, limit }));
  },
);

// Two-part form: path + handler (no options)
app.get("/health", async (_req, res) => {
  res.json({ status: "ok" });
});

The second parameter, options, is a declarative configuration object. Common fields follow; for response, cache, upload, and other fields, see RouteOptions.

#How to write routing files

Each route file default-exports the result of defineRoutes(). Verify the path and validation with the standalone example above before moving business operations into a service. Do not put the database connection, authentication implementation, and an entire CRUD application into your first route.

Use the two-part form for a simple endpoint such as a health check. Use the three-part form for validation, middleware, access protection, or response declarations. A factory can declare multiple methods, but each registration must be a direct statement in its body. For loading rules, see “Route loading priority” and “Exclusion rules” below. For the exact signature, see the defineRoutes API.

To create, read, update, and delete a resource, see Business route composition. That section names the service and authentication prerequisites explicitly.

#Route loading priority

When routes might conflict, router-loader applies these rules:

1. Static paths take precedence over dynamic paths: /users/list before /users/:id.
2. Files sort alphabetically for deterministic loading.
3. Both file prefixes and final route identities are checked: the static index rejects routes/users.ts alongside routes/users/index.ts. Runtime checks also reject duplicate normalized HTTP method and full path pairs, including case and trailing-slash variants. Different final paths do not bypass the file-prefix restriction.
4. HEAD precedes GET at the same path, and specific paths precede wildcard paths. Do not rely on filename order to override an existing route.

#Exclusion rules

Supported route sources are .ts, .js, and .mjs. A .cjs route source fails loading; it is neither supported nor silently excluded. The loader skips:

• Test files: *.test.ts and *.spec.ts
• Type declarations: *.d.ts
• Files or directories starting with _ or .
• node_modules directories
• Generated temporary files containing .__vext_compiled__

These skipped files are not startup errors. Runtime loading, route diagnostics, and manifest generation use the same exclusion policy. The _ prefix can hold shared route utilities:

src/routes/
├── _utils.ts          # not loaded as a route
├── _types.ts          # shared types
├── users.ts
└── orders.ts

#HTTP method

The app object in the defineRoutes() callback supports these HTTP methods:

#Dynamic routing parameters

#File-level dynamic parameters

Use [paramName] as the file name or directory name to automatically convert it to a routing dynamic parameter:

src/routes/users/[id].ts → /users/:id
src/routes/posts/[slug].ts → /posts/:slug
src/routes/[category]/[id].ts → /:category/:id

// src/routes/users/[id].ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  // GET /users/:id — file-level parameter :id is included in the prefix
  app.get(
    "/",
    {
      validate: { param: { id: "string!" } },
    },
    async (req, res) => {
      const { id } = req.valid("param");
      const user = await app.services.user.findById(id);
      res.json(user);
    },
  );

  // GET /users/:id/orders — file-level parameters + subpath
  app.get(
    "/orders",
    {
      validate: { param: { id: "string!" } },
    },
    async (req, res) => {
      const { id } = req.valid("param");
      const orders = await app.services.order.findByUserId(id);
      res.json(orders);
    },
  );
});

#Dynamic parameters within the route

The :paramName syntax can also be used in routing paths inside files:

// src/routes/users.ts
export default defineRoutes((app) => {
  // GET /users/:id/posts/:postId
  app.get(
    "/:id/posts/:postId",
    {
      validate: {
        param: { id: "string!", postId: "string!" },
      },
    },
    async (req, res) => {
      const { id, postId } = req.valid("param");
      // ...
      res.json({ userId: id, postId });
    },
  );
});

#Request object (req)

Handlers read HTTP input through req. For business input, prefer req.valid() for locations declared in the validation schema: it contains validated, converted values. Raw req.params/query/body/headers/cookies remain available.

Only declared locations produce validation results; an undeclared location returns undefined. Field optionality comes from the schema; a TypeScript generic cannot substitute for runtime validation. The id example above converts a string into a number. A handler can apply business defaults to optional fields:

// Inside a handler with validate.query declared
const { page = 1, limit = 20 } = req.valid("query");

For method, URL, raw input, request ID, IP, protocol, cookies, session, and app instance, see request members. See req.valid() for signatures and inferred types. Enable Session before accessing it. See Uploads for file reads and regular field limits.

Use req.onClose() to clean up timers and other resources for long connections or streams. It runs on normal response completion or early connection closure, at most once per callback. Registering after completion runs the callback immediately. A callback does not imply an abnormal disconnect, and normal completion does not abort req.signal. Check signal separately when cancelling downstream work.

#Response object (res)

Call res.json(data) in a handler to send ordinary JSON business data. Pass 201 for creation and use 204 for a successful deletion with no body. Merely returning data does not send a response.

res.json({ name: "Alice" }); // Default 200
res.status(201).setHeader("X-Custom-Header", "value").json(data);
// After successful deletion: res.status(204).json(null);

Each line is an alternative for a different request; do not send them in sequence for one request. By default, config.response.wrap: true wraps JSON as { code: 0, data, requestId }; a 204 response has no body. See JSON response for fields, defaults, and behavior with wrapping disabled.

Choose other response methods according to the task; the request and response API has exact parameters and examples:

To constrain JSON output fields, see top-level responses under “OpenAPI documentation configuration.” Use app.throw() for errors; do not pass error responses as successful data to res.json().

#Parameter validation

VextJS integrates schema-dsl, declares validation rules in the route options.validate, and the framework automatically performs validation and generates OpenAPI documents.

#DSL syntax at a glance

The introduction uses integer:1-! and string:1-50!: ! makes a field required, and the range constrains its value or length. Use ? (or omit the required marker) for an optional field. Declare the rule in route options and read the converted result in the handler.

For strings, numbers, email, URL, booleans, dates, and enums, see the DSL syntax guide and route validation reference. A schema does not decide whether an email is already registered or whether a user owns a resource; implement those business and authorization checks separately.

#Validation locations

app.post(
  "/users/:id/settings",
  {
    validate: {
      param: {
        id: "string!",
      },
      query: {
        format: "json|xml",
      },
      header: {
        "x-api-key": "string!",
      },
      body: {
        nickname: "string:1-30!",
        avatar: "url?",
        notifications: "boolean!",
      },
    },
  },
  handler,
);

Validation runs in this order: param → query → header → cookie → body. An invalid path param returns HTTP 400 immediately; failure at another location returns HTTP 422 immediately.

#Validation error response

When validation fails, the framework returns a structured error response:

{
  "code": 422,
  "message": "Validation failed",
  "errors": [
    { "field": "email", "message": "must be a valid email address" },
    { "field": "name", "message": "length must be between 1 and 50" }
  ],
  "requestId": "xxx"
}

#Routing level middleware

Use options.middlewares to attach middleware to a route. This is a composition snippet: first create the audit-log and response-label files described in Define middleware, then allowlist them in configuration. handler represents your own business handler.

// src/config/default.ts
export default {
  middlewares: [
    "audit-log",
    { name: "response-label", options: { value: "configured" } },
  ],
};

// src/routes/admin.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  // String reference
  app.get(
    "/dashboard",
    {
      middlewares: ["audit-log"],
    },
    handler,
  );

  // Object reference overrides configured default options
  app.delete(
    "/users/:id",
    {
      middlewares: [
        "audit-log",
        { name: "response-label", options: { value: "admin" } },
      ],
    },
    handler,
  );
});

Custom route middleware runs in declaration order, before automatic route validation. Before next(), do not assume req.valid() has validation results. An authentication middleware must establish req.auth before a route's auth guard can enforce protection.

The factory argument here comes from the response-label definition. Route options replace that middleware's configured default options as a whole. Configure built-in rate limiting with global rateLimit.enabled and route override.rateLimit; window is measured in seconds. See override.

#OpenAPI document configuration

OpenAPI documentation information for configuring routing via options.docs:

app.post(
  "/users",
  {
    validate: {
      body: { name: "string:1-50!", email: "email!" },
    },
    responses: {
      201: {
        schema: { id: "string", name: "string", email: "email" },
      },
    },
    docs: {
      summary: "Create user",
      description: "Create a new user, the email address must be unique.",
      operationId: "createUser",
      deprecated: false,
      responses: {
        201: {
          description: "Created successfully",
        },
        409: {
          description: "Email already exists",
        },
      },
    },
  },
  handler,
);

Top-level responses is the runtime contract used for compiled JSON serialization, OpenAPI, and generated client types. Keep descriptions and examples in docs.responses; do not repeat the schema there for the same status selector.

#Hidden route

To omit a route from generated OpenAPI documentation, set docs.hidden: true. This does not block HTTP access; use authentication and authorization for access control:

app.get(
  "/internal/metrics",
  {
    docs: { hidden: true },
  },
  handler,
);

#Access the app object

The app argument to defineRoutes() gives access to services, logging, errors, and configuration:

export default defineRoutes((app) => {
  app.get("/example", async (req, res) => {
    // Access a service
    const data = await app.services.user.findAll();

    // use logger
    app.logger.info("Fetching users");

    // throw HTTP error
    if (!data) app.throw(404, "not_found");

    // Read configuration
    const port = app.config.port;

    res.json(data);
  });
});

#Error handling

#app.throw() — throw HTTP error

When using app.throw() in a route or service to throw an error, the framework will handle it uniformly and return a structured response:

// Basic usage
app.throw(404, "User does not exist");
// → { "code": 404, "message": "User does not exist", "requestId": "..." }

// Use i18n key (with locales/ language pack)
app.throw(404, "user.not_found");
// → Automatically translate the message into the current request language

// With a business error code
app.throw(400, "Email has been registered", 10001);
// → { "code": 10001, "message": "Email has been registered", "requestId": "..." }

// With interpolation parameters
app.throw(400, "balance.insufficient", { balance: 50 });
// → code comes from the locale's business code if present; otherwise 400.
//   The message comes from translation and interpolation.

// With interpolation parameters + business error code
app.throw(400, "balance.insufficient", { balance: 50 }, 20001);

app.throw() will terminate the current request processing flow (function signature returns never), no need to add return after it.

If an unexpected exception is thrown here, you can also directly:

throw new Error("Database connection lost");

The framework will catch it as well, but this path represents an "unknown runtime error" and will ultimately return a 500 Internal Server Error. In the development environment, when response.hideInternalErrors = false, the JSON 500 response will be accompanied by stack; if your goal is to actively return a clear 4xx/5xx HTTP result, you should still use app.throw(...) first.

#Business route composition

This article-creation example connects HTTP input to business operations and an HTTP response. Before running it, implement a post service and provide an allowlisted auth middleware that sets req.auth.userId. It is a business wiring snippet; without those prerequisites, start with route-demo.ts above.

// src/routes/posts.ts
import { defineRoutes } from "vextjs";

export default defineRoutes((app) => {
  app.post(
    "/",
    {
      validate: {
        body: {
          title: "string:1-200!",
          content: "string:1-50000!",
          tags: "string?",
        },
      },
      middlewares: ["auth"],
      auth: { required: true, security: "bearerAuth" },
      docs: { summary: "Create a post" },
    },
    async (req, res) => {
      const post = await app.services.post.create({
        ...req.valid("body"),
        authorId: req.auth.userId,
      });
      res.json(post, 201);
    },
  );
});

For a full CRUD resource, keep the same responsibilities:

A status enum can use draft|published|archived. Validation constrains declared input. auth.required does not automatically check ownership, status, or database uniqueness. See Services and Security for implementation, and CRUD API for an example with its application dependencies.

#Next step

• Understand how the service layer organizes business logic
• Learn the onion model of middleware
• Explore the advanced usage of Parameter Validation
• View OpenAPI Documentation automatically generated
• Check stable Rule IDs in the HTTP and Routing Specification