File Conventions

Taser.js 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().

Source of Truth Comparison

Route Path String Mismatch Error

If the path string in a route builder does not match any valid route path in the emitted ambient union, TypeScript flags the mismatch during tsc:

Type '"/usr/profile"' is not assignable to type 'RoutePath'.

HTTP Method Suffixes

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

Flat Routes, Directory Routes, and Mixed Notation

Taser.js 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:

Index Routes vs. Dynamic Parameter Routes ($param)

Collision & Duplicate Route Rules

Both posts.$id.get.ts and posts.$id.index.get.ts (as well as posts/$id/index.get.ts) evaluate to the exact same route: GET /posts/:id.

If both files exist simultaneously within the same routes directory, Taser.js halts the build immediately during the route scan phase with a ScanErrorCollection:

ScanError: Duplicate route for GET /posts/:id (posts.$id.get.ts and posts.$id.index.get.ts)

Route collisions are never silently overwritten and do not result in last-write-wins or undefined behavior. You must remove one of the duplicate route files to resolve the build error.

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:

Breakout Route vs. Base Route Alternatives

The base route tasks/$id.complete.patch.ts and the breakout route tasks/$id_.complete.patch.ts resolve to the identical endpoint URL (PATCH /tasks/:id/complete). They are mutually exclusive architectural alternatives for the same URL:

ScanError: Duplicate route for PATCH /tasks/:id/complete (tasks/$id.complete.patch.ts and tasks/$id_.complete.patch.ts)

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