Enhancing ESHOPMAN Flexibility: Safely Managing Core Admin API Routes

As an ESHOPMAN expert, we recognize that deep customization is key to leveraging a headless commerce platform. ESHOPMAN, with its Node.js/TypeScript foundation, Admin/Store APIs, and HubSpot integration, offers immense flexibility. However, for advanced scenarios like custom marketplace frameworks, tailoring core platform behaviors can present unique challenges.

The Challenge: Customizing Core Admin API Routes

Custom ESHOPMAN applications, particularly marketplace frameworks, often need to replace or hide default Admin API routes—for instance, managing products through specialized flows instead of ESHOPMAN's standard interface. This commonly involves routes like:

/admin/products/**
/admin/product-variants/**

Currently, achieving this safely is difficult. Some developers resort to patching ESHOPMAN's internal module files (e.g., within node_modules/@eshopman/eshopman/dist/api/admin/...) at startup. While functional, this approach is brittle and complicates maintenance and upgrades.

Limitations of Current Customization Methods

The ESHOPMAN community has explored various extension mechanisms, but they don't reliably address the need to disable or cleanly override core routes:

• Middleware Blockers: Ineffective for nested routes (e.g., /admin/products/:id/options) because ESHOPMAN's core policies and middlewares execute first.
• Route File Shadowing: Adding custom route stubs at matching paths (e.g., src/api/admin/products/**/route.ts) does not cleanly override ESHOPMAN's core handlers.
• Plugin Middleware Overrides: Implementing plugin-level middleware (e.g., src/api/admin/products/middlewares.ts) does not disable core product middlewares.

ESHOPMAN's Route Registration Order

The root cause lies in ESHOPMAN's API layer registration sequence:

Core → Plugins → Application

This order means core route middlewares/policies run before any plugin or application-specific ones. Consequently, exact-path core route handlers cannot be cleanly overridden. The "Replicate, Don't Override" pattern is suitable for adding new routes but not for replacing existing core ones.

The Proposed Solution: A Dedicated Route Disablement Mechanism

To provide a robust and maintainable extension point, the ESHOPMAN community advocates for a supported way to disable selected core API routes before ESHOPMAN's route and policy registration. This would eliminate the need for fragile internal file patching.

Potential implementations include:

• Configuration Option: A setting in eshopman-config.ts:

  // eshopman-config.ts
  export default defineConfig({
    projectConfig: {
      // ...
    },
    api: {
      disabledCoreRoutes: [
        "/admin/products*",
        "/admin/product-variants*",
      ],
    },
  })

• Plugin/Application Hook: A hook within a route configuration file:

  export default defineRouteConfig({
    disableCoreRoutes: [
      "/admin/products*",
      "/admin/product-variants*",
    ],
  })

The key requirements are early execution, support for route/method matching, usability from an application/plugin without node_modules patching, and effective disabling of both handlers and associated middlewares/policies.

Why This Matters for ESHOPMAN Development

For ESHOPMAN developers building sophisticated custom applications, a supported route-disable mechanism is vital. It enables:

• Safer Customization: Replace default Admin API behaviors without exposing unnecessary core routes.
• Improved Maintainability: Eliminate brittle runtime patching.
• Easier Upgrades: Ensure custom logic remains compatible across ESHOPMAN upgrades.
• Enhanced Flexibility: Tailor ESHOPMAN's headless capabilities to unique business needs, fostering innovation within the ESHOPMAN ecosystem and richer HubSpot-integrated commerce experiences.