Make middleware a required discriminator in router.map()

This eliminates ambiguity when route names like `action` (from the `form`
helper) collide with the `action` property in middleware-wrapped actions.

Previously, type guards checked for `action` or `actions` properties to
determine if an object was middleware-wrapped. This caused confusion because
`{ index: fn, action: fn }` could match `{ middleware?, action: fn }`.

Now, `middleware` is the sole discriminator.

Breaking changes:
- `{ action: fn }` without `middleware` no longer works - use plain `fn`
- `{ actions: {...} }` without `middleware` no longer works - use plain object

Author: mjackson

demos/bookstore/app/routes.ts

@@ -1,4 +1,4 @@
-import { route, form, resources } from '@remix-run/fetch-router'
+import { del, get, post, put, route, form, resources } from '@remix-run/fetch-router'
 
 export let routes = route({
   assets: '/assets/*path',
@@ -7,10 +7,7 @@ export let routes = route({
   // Simple static routes
   home: '/',
   about: '/about',
-  contact: route('/contact', {
-    index: { method: 'GET', pattern: '/' },
-    action: { method: 'POST', pattern: '/' },
-  }),
+  contact: form('contact'),
   search: '/search',
 
   // Fragments
@@ -29,13 +26,13 @@ export let routes = route({
   auth: {
     login: form('login'),
     register: form('register'),
-    logout: { method: 'POST', pattern: '/logout' },
+    logout: post('logout'),
     forgotPassword: form('forgot-password'),
     resetPassword: form('reset-password/:token'),
   },
 
   // Account section (protected, nested routes)
-  account: route('/account', {
+  account: route('account', {
     index: '/',
     settings: form('settings', {
       formMethod: 'PUT',
@@ -52,27 +49,27 @@ export let routes = route({
   }),
 
   // Cart and shopping
-  cart: route('/cart', {
-    index: { method: 'GET', pattern: '/' },
+  cart: route('cart', {
+    index: get('/'),
 
     // API-style endpoints under /cart/api
     api: {
-      add: { method: 'POST', pattern: '/api/add' },
-      update: { method: 'PUT', pattern: '/api/update' },
-      remove: { method: 'DELETE', pattern: '/api/remove' },
+      add: post('/api/add'),
+      update: put('/api/update'),
+      remove: del('/api/remove'),
     },
   }),
 
   // Checkout flow
-  checkout: route('/checkout', {
-    index: { method: 'GET', pattern: '/' },
-    action: { method: 'POST', pattern: '/' },
-    confirmation: { method: 'GET', pattern: '/:orderId/confirmation' },
+  checkout: route('checkout', {
+    index: get('/'),
+    action: post('/'),
+    confirmation: get('/:orderId/confirmation'),
   }),
 
   // Admin section (protected, showcases full CRUD on multiple resources)
-  admin: route('/admin', {
-    index: { method: 'GET', pattern: '/' },
+  admin: route('admin', {
+    index: get('/'),
 
     // Full CRUD on books
     books: resources('books', { param: 'bookId' }),

packages/fetch-router/CHANGELOG.md

@@ -94,6 +94,48 @@ This is the changelog for [`fetch-router`](https://github.com/remix-run/remix/tr
   })
   ```
 
+- BREAKING CHANGE: The `middleware` property is now required (not optional) in controller and action objects that use the `{ middleware, actions }` or `{ middleware, action }` format. This eliminates ambiguity when route names like `action` collide with the `action` property name.
+
+  ```tsx
+  // Before: { action } without middleware was allowed
+  router.map(routes.home, {
+    action() {
+      return new Response('Home')
+    },
+  })
+
+  // After: just use a plain request handler function instead
+  router.map(routes.home, () => {
+    return new Response('Home')
+  })
+
+  // Before: { actions } without middleware was allowed
+  router.map(routes, {
+    actions: {
+      home() {
+        return new Response('Home')
+      },
+    },
+  })
+
+  // After: just use a plain controller object instead
+  router.map(routes, {
+    home() {
+      return new Response('Home')
+    },
+  })
+
+  // With middleware, the syntax remains the same (but middleware is now required)
+  router.map(routes, {
+    middleware: [auth()],
+    actions: {
+      home() {
+        return new Response('Home')
+      },
+    },
+  })
+  ```
+
 ## v0.12.0 (2025-11-25)
 
 - BREAKING CHANGE: Moved all response helpers to `@remix-run/response`. Update your imports:

packages/fetch-router/src/lib/controller.ts

@@ -11,21 +11,15 @@ export type Controller<routes extends RouteMap> =
   | ControllerWithoutMiddleware<routes>
 
 type ControllerWithMiddleware<routes extends RouteMap> = {
-  middleware?: Middleware[]
+  middleware: Middleware[]
   actions: ControllerWithoutMiddleware<routes>
 } & (routes extends Record<string, any>
   ? {
-      // Explicitly exclude route name keys from objects with `actions`
+      // Explicitly exclude route name keys from objects with `middleware`
       [name in keyof routes as routes extends any ? never : name]?: never
     }
   : {})
 
-export function hasActions<routes extends RouteMap>(
-  controller: any,
-): controller is ControllerWithMiddleware<routes> {
-  return typeof controller === 'object' && controller != null && 'actions' in controller
-}
-
 // prettier-ignore
 type ControllerWithoutMiddleware<routes extends RouteMap> = routes extends any ?
   ({
@@ -35,9 +29,8 @@ type ControllerWithoutMiddleware<routes extends RouteMap> = routes extends any ?
       never
     )
   } & {
-    // Explicitly exclude `middleware` and `actions` from objects with route name keys
+    // Explicitly exclude `middleware` from objects with route name keys
     middleware?: never
-    actions?: never
   }) :
   never
 
@@ -49,16 +42,10 @@ export type Action<method extends RequestMethod | 'ANY', pattern extends string>
   | RequestHandler<method, Params<pattern>>
 
 type RequestHandlerWithMiddleware<method extends RequestMethod | 'ANY', pattern extends string> = {
-  middleware?: Middleware<method, Params<pattern>>[]
+  middleware: Middleware<method, Params<pattern>>[]
   action: RequestHandler<method, Params<pattern>>
 }
 
-export function hasAction<method extends RequestMethod | 'ANY', pattern extends string>(
-  action: any,
-): action is RequestHandlerWithMiddleware<method, pattern> {
-  return typeof action === 'object' && action != null && 'action' in action
-}
-
 /**
  * Build an `Action` type from a string, `RoutePattern`, or `Route`.
  */
@@ -68,3 +55,33 @@ export type BuildAction<method extends RequestMethod | 'ANY', route extends stri
   route extends RoutePattern<infer pattern> ? Action<method, pattern> :
   route extends Route<infer _, infer pattern> ? Action<method, pattern> :
   never
+
+/**
+ * Runtime shape for a controller with middleware.
+ */
+export interface ControllerWithMiddlewareShape {
+  middleware: Middleware[]
+  actions: Record<string, unknown>
+}
+
+/**
+ * Check if an object has middleware and an `actions` property (controller with middleware).
+ */
+export function isControllerWithMiddleware(obj: unknown): obj is ControllerWithMiddlewareShape {
+  return typeof obj === 'object' && obj != null && 'middleware' in obj && 'actions' in obj
+}
+
+/**
+ * Runtime shape for an action with middleware.
+ */
+export interface ActionWithMiddlewareShape {
+  middleware: Middleware[]
+  action: RequestHandler<any, any>
+}
+
+/**
+ * Check if an object has middleware and an `action` property (action with middleware).
+ */
+export function isActionWithMiddleware(obj: unknown): obj is ActionWithMiddlewareShape {
+  return typeof obj === 'object' && obj != null && 'middleware' in obj && 'action' in obj
+}

packages/fetch-router/src/lib/router.test.ts

@@ -177,24 +177,6 @@ describe('router.map()', () => {
     assert.equal(await response.text(), 'Home')
   })
 
-  it('maps a single route to an action without middleware', async () => {
-    let routes = route({
-      home: '/',
-    })
-
-    let router = createRouter()
-
-    router.map(routes.home, {
-      action() {
-        return new Response('Home')
-      },
-    })
-
-    let response = await router.fetch('https://remix.run')
-    assert.equal(response.status, 200)
-    assert.equal(await response.text(), 'Home')
-  })
-
   it('maps a single route to an action with middleware', async () => {
     let routes = route({
       home: '/',
@@ -269,34 +251,6 @@ describe('router.map()', () => {
     assert.equal(await response.text(), 'Blog Post 1')
   })
 
-  it('maps a route map to actions without middleware', async () => {
-    let routes = route({
-      home: '/',
-      blog: '/blog',
-    })
-
-    let router = createRouter()
-
-    router.map(routes, {
-      actions: {
-        home() {
-          return new Response('Home')
-        },
-        blog() {
-          return new Response('Blog')
-        },
-      },
-    })
-
-    let response = await router.fetch('https://remix.run')
-    assert.equal(response.status, 200)
-    assert.equal(await response.text(), 'Home')
-
-    response = await router.fetch('https://remix.run/blog')
-    assert.equal(response.status, 200)
-    assert.equal(await response.text(), 'Blog')
-  })
-
   it('maps a route map to actions with middleware', async () => {
     let routes = route({
       home: '/',
@@ -333,13 +287,17 @@ describe('router.map()', () => {
 
     let router = createRouter()
 
-    router.map(routes, {
-      middleware: [],
-      // @ts-expect-error - should not allow middleware alongside actions
-      home() {
-        return new Response('OK')
-      },
-    })
+    // This is a compile-time type check only - we use a never-executed block
+    // to verify that TypeScript catches the error without running the code.
+    if (false as boolean) {
+      router.map(routes, {
+        middleware: [],
+        // @ts-expect-error - should not allow middleware alongside actions
+        home() {
+          return new Response('OK')
+        },
+      })
+    }
   })
 
   it('supports middleware in nested controllers', async () => {
@@ -494,19 +452,6 @@ describe('router.get()', () => {
     assert.equal(await response.text(), 'Home')
   })
 
-  it('maps a single route to an action object without middleware', async () => {
-    let router = createRouter()
-    router.get('/', {
-      action() {
-        return new Response('Home')
-      },
-    })
-
-    let response = await router.fetch('https://remix.run')
-    assert.equal(response.status, 200)
-    assert.equal(await response.text(), 'Home')
-  })
-
   it('maps a single route to an action with middleware', async () => {
     let requestLog: string[] = []
     let router = createRouter()