HTTP layer Devflare

Split request-wide middleware from route leaves so HTTP stays easy to read

Use for request-wide behavior, for leaf handlers, and when you need a custom root, prefix, or route-only app.

Devflare gives you a request-wide fetch entry and a built-in file router. The safest mental model is simple: keep broad middleware in , keep URL-specific behavior in , and reach for when the route tree needs custom mounting rules.

Best for: HTTP apps that need middleware, route params, or a mounted route tree
Primary order: → same-module methods → matched route file
Route config

Two HTTP layers by design

If exports or , that module becomes the primary HTTP entry. Inside , Devflare checks same-module method handlers first and then dispatches to the matched route file when needed.

That ordering is what lets middleware stay global while route files remain the clean leaf-handler story.

Use it for request-wide behavior that should apply before or after the final leaf handler runs.

Use it for specific URL handlers so the file tree mirrors the URLs you serve.

1

Devflare enters through when that file exports or .
2

Inside , exact same-module HTTP method handlers such as or are checked first, falls back to with an empty body, and is the last module-local fallback.
3

If no same-module method handler answers the request, Devflare falls through to the matched route file.
4

Devflare computes route params before request-wide middleware continues, so is available to both outer middleware and the leaf handler.

Use middleware for broad concerns, not leaf business logic

Keep the split clean

If a piece of logic only matters for one URL, it probably belongs in a route file, not in global middleware.

Keep the middleware file and the leaf route side by side

The global file owns request-wide behavior. The route file owns one URL. When those stay separate, the whole HTTP layer stays readable.

import { sequence } from 'devflare/runtime'

import type { FetchEvent, ResolveFetch } from 'devflare/runtime'

async function cors(event: FetchEvent, resolve: ResolveFetch): Promise<Response> {

if (event.request.method === 'OPTIONS') {

return new Response(null, {

headers: {

'Access-Control-Allow-Origin': '*',

'Access-Control-Allow-Methods': 'GET, POST, OPTIONS'

}

})

}

const response = await resolve(event)

const next = new Response(response.body, response)

next.headers.set('Access-Control-Allow-Origin', '*')

return next

}

export const handle = sequence(cors)

Route-only apps are valid when you do not need global middleware

You do not need just to use the file router. If every concern is leaf-local, a route tree on its own is a clean supported shape.

That is especially useful for small APIs where a mounted route prefix matters more than request-wide middleware.

Start route-only when the app really is route-only

Skip until you genuinely need request-wide auth, logging, CORS, or response shaping. Add the global file later; the route tree stays valid.

Mount a route tree under `/api` without a `src/fetch.ts` file

Explicit `files.routes` keeps the route root and prefix obvious in code review while the app stays route-only.

import { defineConfig } from 'devflare/config'

export default defineConfig({

name: 'users-api',

files: {

routes: {

dir: 'src/routes',

prefix: '/api'

}

})

Use to remap, prefix, or disable the route tree

is app routing config. It controls how Devflare discovers and mounts route modules inside the Worker package.

It is not the same thing as top-level Cloudflare deployment , which decide which hostnames and path patterns reach the Worker in the first place.

Shape	What it does
Omit	is auto-discovered when that directory exists.
	Changes the route root without changing the rest of the routing model.
	Mounts discovered routes under a fixed prefix such as .
	Disables file-route discovery entirely.

Do not blur app routing and deployment routing

If you are choosing files inside your Worker, you want . If you are deciding which traffic reaches the Worker at all, you want top-level Cloudflare .

Specificity and guardrails matter once the tree grows

Static routes beat dynamic routes, dynamic routes beat rest routes, and optional rest routes are checked last.
and normalize to the same pattern and are rejected as conflicts.
Files or directories beginning with are ignored so route-local helpers can live beside handlers.
falls back to if you do not export a dedicated handler.
Route modules can use HTTP method exports, or a primary / export, just like the fetch module.

Filename	Meaning
	Matches .
	Matches and exposes .
	Matches one-or-more trailing segments and exposes as joined path text.
	Matches both the directory root and deeper optional rest paths.

Conflict errors are a feature, not a nuisance

If two files normalize to the same route pattern, Devflare rejects the tree instead of guessing. That makes route review boring in the best possible way.

Bridge internals

The bridge architecture document remains valuable, but it should not be on the first-hour developer path.

Config basics

Write for humans first, let Devflare merge environments and resolve names later, and treat generated Wrangler-facing files as outputs rather than authoring surfaces.