feathersjs · marshallswain · Jan 28, 2026 · Jan 28, 2026 · Jan 29, 2026
diff --git a/docs/v6-custom-methods-plan.md b/docs/v6-custom-methods-plan.md
diff --git a/package-lock.json b/package-lock.json
diff --git a/packages/feathers/fixtures/index.ts b/packages/feathers/fixtures/index.ts
@@ -1,7 +1,7 @@
 import { createServer } from 'node:http'
 import { TestService } from './fixture.js'
 
-import { feathers, Application, Params } from '../src/index.js'
+import { feathers, Application, Params, method } from '../src/index.js'
 import { createHandler, SseService } from '../src/http/index.js'
 import { toNodeHandler } from '../src/http/node.js'
 
@@ -107,12 +107,72 @@ export class ResponseTestService {
   }
 }
 
+export class InternalTestService {
+  async find(_params: Params) {
+    return [{ id: 1, name: 'Public' }]
+  }
+
+  @method({ args: ['data', 'params'], external: false })
+  async internalProcess(data: any, _params: Params) {
+    return { processed: data, internal: true }
+  }
+}
+
+export class CustomPathService {
+  messages: { id: string; text: string; status: string }[] = [
+    { id: '1', text: 'Hello', status: 'active' },
+    { id: '2', text: 'World', status: 'archived' }
+  ]
+
+  async find(_params: Params) {
+    return this.messages
+  }
+
+  async get(id: string, _params: Params) {
+    return this.messages.find((m) => m.id === id)
+  }
+
+  @method({ args: ['id', 'params'], http: 'GET', path: ':id/status' })
+  async status(id: string, _params: Params) {
+    const msg = this.messages.find((m) => m.id === id)
+    return { id, status: msg?.status || 'unknown' }
+  }
+
+  @method({ args: ['id', 'params'], http: 'POST', path: ':id/archive' })
+  async archive(id: string, _params: Params) {
+    const msg = this.messages.find((m) => m.id === id)
+    if (msg) {
+      msg.status = 'archived'
+    }
+    return msg
+  }
+
+  @method({ args: ['params'], http: 'GET', path: 'stats' })
+  async stats(_params: Params) {
+    return {
+      total: this.messages.length,
+      active: this.messages.filter((m) => m.status === 'active').length
+    }
+  }
+
+  @method({ args: ['id', 'data', 'params'], http: 'POST', path: ':id/update-status' })
+  async updateStatus(id: string, data: { status: string }, _params: Params) {
+    const msg = this.messages.find((m) => m.id === id)
+    if (msg) {
+      msg.status = data.status
+    }
+    return msg
+  }
+}
+
 export type TestServiceTypes = {
   todos: TestService
   uploads: UploadService
   streaming: StreamingService
   test: ResponseTestService
   sse: SseService
+  internal: InternalTestService
+  custom: CustomPathService
 }
 
 export type TestApplication = Application<TestServiceTypes>
@@ -131,6 +191,8 @@ export function getApp(): TestApplication {
   })
   app.use('test', new ResponseTestService())
   app.use('sse', new SseService())
+  app.use('internal', new InternalTestService())
+  app.use('custom', new CustomPathService())
 
   return app
 }

diff --git a/packages/feathers/src/application.test.ts b/packages/feathers/src/application.test.ts
@@ -1,7 +1,7 @@
 /* eslint-disable @typescript-eslint/ban-ts-comment */
 import { describe, it } from 'vitest'
 import assert from 'assert'
-import { feathers, Feathers, getServiceOptions, Id, version } from '../src/index.js'
+import { feathers, Feathers, getServiceOptions, Id, version, method } from '../src/index.js'
 
 describe('Feathers application', () => {
   it('initializes', () => {
@@ -563,4 +563,86 @@ describe('Feathers application', () => {
       })
     })
   })
+
+  describe('route conflicts', () => {
+    it('throws when custom method path conflicts with another service custom method', () => {
+      const app = feathers()
+
+      class MessageService {
+        @method({ args: ['id', 'params'], http: 'GET', path: ':id/status' })
+        async status(id: Id) {
+          return { id, status: 'message' }
+        }
+      }
+
+      class NotificationService {
+        // Same path pattern - this would conflict with messages/:id/status
+        @method({ args: ['id', 'params'], http: 'GET', path: ':id/status' })
+        async status(id: Id) {
+          return { id, status: 'notification' }
+        }
+      }
+
+      app.use('messages', new MessageService())
+      app.use('notifications', new NotificationService())
+
+      // These have different base paths, so they should NOT conflict
+      assert.ok(app.service('messages'))
+      assert.ok(app.service('notifications'))
+    })
+
+    it('throws when custom method path conflicts with another service base path', () => {
+      const app = feathers()
+
+      // Register a nested service first
+      app.use('messages/archived', {
+        async find() {
+          return []
+        }
+      })
+
+      // Now try to register a service with a custom method that would conflict
+      class MessageService {
+        async find() {
+          return []
+        }
+
+        @method({ args: ['params'], http: 'GET', path: 'archived' })
+        async archived() {
+          return []
+        }
+      }
+
+      assert.throws(
+        () => app.use('messages', new MessageService()),
+        /Path 'messages\/archived' for method 'archived' conflicts with another service/
+      )
+    })
+
+    it('allows different custom method paths on the same service', () => {
+      const app = feathers()
+
+      class MessageService {
+        @method({ args: ['id', 'params'], http: 'GET', path: ':id/status' })
+        async status(id: Id) {
+          return { id, status: 'active' }
+        }
+
+        @method({ args: ['id', 'params'], http: 'POST', path: ':id/archive' })
+        async archive(id: Id) {
+          return { id, archived: true }
+        }
+
+        @method({ args: ['params'], http: 'GET', path: 'stats' })
+        async stats() {
+          return { total: 100 }
+        }
+      }
+
+      // Should not throw
+      app.use('messages', new MessageService())
+
+      assert.ok(app.service('messages'))
+    })
+  })
 })
diff --git a/packages/feathers/src/application.ts b/packages/feathers/src/application.ts
@@ -155,12 +155,12 @@ export class Feathers<Services, Settings>
 
     const {
       params: colonParams,
-      data: { service, params: dataParams }
+      data: { service, params: dataParams, method, httpMethod }
     } = result
 
     const params = dataParams ? { ...dataParams, ...colonParams } : colonParams
 
-    return { service, params }
+    return { service, params, method, httpMethod }
   }
 
   protected _setup() {
@@ -277,6 +277,42 @@ export class Feathers<Services, Settings>
 
     this.routes.insert(path, routerParams)
     this.routes.insert(`${path}/:__id`, routerParams)
+
+    // Register routes for custom method paths
+    const { methodOptions } = serviceOptions
+    for (const [methodName, methodConfig] of Object.entries(methodOptions)) {
+      if (methodConfig.path && methodConfig.external !== false) {
+        // Convert :id in path to :__id for consistency with standard routes
+        const customPath = methodConfig.path.replace(/:id\b/g, ':__id')
+        const fullPath = `${path}/${customPath}`
+
+        // The router.insert() will throw if an exact path already exists.
+        // This catches duplicate custom method paths and conflicts with other services.
+        try {
+          this.routes.insert(fullPath, {
+            ...routerParams,
+            method: methodName,
+            httpMethod: methodConfig.http || 'POST'
+          })
+        } catch (error: any) {
+          if (error.message?.includes('already exists')) {
+            // Check what's already registered at this path to give a better error message
+            const existingRoute = this.routes.lookup(fullPath)
+            const existingMethod = existingRoute?.data?.method
+              ? `method '${existingRoute.data.method}'`
+              : 'another service'
+            throw new Error(
+              `Path '${fullPath}' for method '${methodName}' conflicts with ${existingMethod}. ` +
+                `Custom method paths must be unique.`
+            )
+          }
+          throw error
+        }
+
+        debug(`Registered custom path \`${fullPath}\` for method \`${methodName}\``)
+      }
+    }
+
     this.services[location] = protoService
 
     // If we ran setup already, set this service up explicitly, this will not `await`

diff --git a/packages/feathers/src/client/fetch.test.ts b/packages/feathers/src/client/fetch.test.ts
@@ -210,4 +210,57 @@ describe('fetch REST connector', function () {
   })
 
   clientTests(app, 'todos')
+
+  describe('custom method paths with client config', () => {
+    // Create a client with method configuration
+    const customConnection = fetchClient(fetch, {
+      baseUrl,
+      methods: {
+        custom: {
+          status: { args: ['id', 'params'], http: 'GET', path: ':id/status' },
+          stats: { args: ['params'], http: 'GET', path: 'stats' },
+          archive: { args: ['id', 'params'], http: 'POST', path: ':id/archive' },
+          updateStatus: { args: ['id', 'data', 'params'], http: 'POST', path: ':id/update-status' }
+        }
+      }
+    })
+    const customApp = feathers<TestServiceTypes>().configure(customConnection)
+    const customService = customApp.service('custom') as any
+
+    it('GET :id/status - client uses correct verb and path', async () => {
+      const result = await customService.status('1', {})
+
+      expect(result.id).toBe('1')
+      expect(result.status).toBeDefined()
+    })
+
+    it('GET stats - client calls without id', async () => {
+      const result = await customService.stats({})
+
+      expect(result).toHaveProperty('total')
+      expect(result).toHaveProperty('active')
+    })
+
+    it('POST :id/archive - client sends POST to path', async () => {
+      const result = await customService.archive('1', {})
+
+      expect(result.id).toBe('1')
+    })
+
+    it('POST :id/update-status - client sends id, data, params', async () => {
+      const result = await customService.updateStatus('1', { status: 'updated-via-client' }, {})
+
+      expect(result.id).toBe('1')
+      expect(result.status).toBe('updated-via-client')
+    })
+
+    it('falls back to header-based method when no path config', async () => {
+      // todoService doesn't have method config, so custom methods fall back
+      const todoService = customApp.service('todos') as any
+      const result = await todoService.customMethod({ text: 'Test' }, {})
+
+      expect(result.data.text).toBe('Test')
+      expect(result.method).toBe('customMethod')
+    })
+  })
 })