File Conventions

Taser adopts modern TanStack Router-style file routing conventions tailored specifically for REST APIs. Your filesystem serves as the single source of truth for URL endpoints, HTTP methods, and cascading middleware pipelines.

Route Files vs Layout Files

Under your src/routes/ directory, files are classified into two distinct types:

1. Route Files: Filenames containing an HTTP verb before .ts (such as users.get.ts, posts.post.ts, items.$id.delete.ts, tasks/$id.complete.patch.ts). Route files export a default route definition created with t.get(), t.post(), etc.
2. Layout Files: Filenames ending in .ts without an HTTP verb (such as $.ts, admin.ts, _auth.ts, tasks/$id.ts). Layout files export a default middleware pipeline created with t.layout().

HTTP Method Suffixes

Taser determines the HTTP verb from the final extension segment before .ts:

Flat Routes, Directory Routes, and Mixed Notation

Taser supports nested directory structures, flat dot notation, and mixed folder + dot notation. You can use whichever structure keeps your codebase cleanest:

Index Routes (index.<method>.ts)

An index segment targets the root of its parent route without appending /index to the public URL:

Dynamic Path Parameters ($param)

Prefixing a segment with $ denotes a named URL path parameter:

Inside your route handler, parameters are automatically typed and validated on ctx.params:

import { json } from "@taserjs/router/reply";
import { z } from "zod";
import { t } from "@taserjs/router";

export default t
  .patch("/tasks/:id/complete")
  .params(z.object({ id: z.string().uuid() }))
  .handler((ctx) => {
    // ctx.params.id is strictly typed as a UUID string
    return json({ taskId: ctx.params.id, completed: true });
  });

Wildcard Catch-All Splats ($)

A standalone $ segment captures wildcard rest segments (splats):

In your handler, the wildcard path matches all trailing sub-paths.

Root Layout Middleware ($.ts)

A top-level file named src/routes/$.ts serves as the Root Layout Middleware. It runs before every route in your application:

import { bodyLimit } from "@taserjs/router/body-limit";
import { secureHeaders } from "@taserjs/router/secure-headers";
import { t } from "@taserjs/router";

export default t
  .layout("/*")
  .use(secureHeaders())
  .use(bodyLimit({ maxSize: 1_000_000 }));

Pathless Layouts (Leading Underscore _layout)

A segment starting with an underscore _ (like _auth.ts, _auth/, or _auth.login.post.ts) is pathless. It applies scoped middleware to child routes without adding any segment to the public URL:

In flat dot notation:

Notice that _auth, _app, and _dashboard are omitted from the public URL.

Layout Breakout Routes (Trailing Underscore segment_)

A segment ending with an underscore _ is a breakout route (un-nested route). It targets the expected URL path, but breaks out of the parent layout hierarchy so it skips that segment's layout middleware.

The Problem Breakout Routes Solve

Suppose you have an authenticated /posts layout in src/routes/posts.ts (or a /tasks/:id layout in src/routes/tasks/$id.ts) that enforces user login or permission checks. You want a specific child endpoint (like /posts/:id/preview or /tasks/:id/complete) to skip that layout's checks.

By adding a trailing underscore to posts_ or $id_, the route keeps the URL segment but skips the layout:

Escaping Special Characters ([...])

When you need a literal character that would otherwise trigger a router convention (such as a literal dot ., literal leading underscore _, or literal index), wrap the character in brackets [...]:

Ignored & Private Files (- Prefix)

To co-locate utility files, helper functions, schemas, or test fixtures directly alongside route files without generating routes, prefix the file or folder with a dash -:

Complete Conventions Reference

Next Steps