Mastering ESHOPMAN Custom Middleware: Addressing Exact Path Matching for Admin API Routes

Mastering ESHOPMAN Custom Middleware: Addressing Exact Path Matching for Admin API Routes

Custom middleware is a cornerstone for extending the functionality of your ESHOPMAN platform, especially when building bespoke features for your storefronts managed via HubSpot. It allows developers to inject custom logic, such as authentication checks, logging, or data transformations, directly into the request-response cycle of the ESHOPMAN Admin API or Store API.

The Challenge: Exact Path Middleware Silently Ignored

Recently, the ESHOPMAN developer community identified an unexpected behavior concerning custom middleware defined with exact route paths. Developers observed that when registering middleware using defineMiddlewares in their ESHOPMAN application's src/api/middlewares.ts, a matcher like "/admin/products" for a specific Admin API route would silently fail to execute the middleware function. This meant that any custom logic intended for that precise route was never triggered.

For instance, consider a scenario where you want to intercept POST requests to /admin/products to add custom validation or logging before a new product is created. The expected setup:

import { defineMiddlewares } from "@eshopman/framework/http"

function myMiddleware(req, res, next) {
  console.log("MIDDLEWARE HIT")
  next()
}

export default defineMiddlewares({
  routes: [
    {
      matcher: "/admin/products",
      methods: ["POST"],
      middlewares: [myMiddleware],
    },
  ],
})

Despite this configuration, developers found that the "MIDDLEWARE HIT" log would never appear when a POST request was made to /admin/products.

Key Observations from the ESHOPMAN Community

• The middleware module itself was correctly loaded during ESHOPMAN startup.
• The issue persisted regardless of whether specific HTTP methods (like POST) were defined or omitted.
• Interestingly, middleware registered by ESHOPMAN plugins on the same exact paths (e.g., GET /admin/products) functioned without issues.
• A critical observation was that using a wildcard matcher, such as "/admin/*", for the same middleware did work correctly, indicating the core issue was with the exact path matching mechanism for custom application-level middleware.

The ESHOPMAN Community Workaround

To ensure that custom logic can still be applied precisely to specific Admin API routes, the ESHOPMAN community quickly converged on an effective workaround. This involves using a broader wildcard matcher in defineMiddlewares and then implementing a conditional path check directly within the middleware function itself.

This approach leverages the fact that wildcard matchers are reliably triggered, allowing developers to then filter for the exact path they need inside their middleware:

import { defineMiddlewares } from "@eshopman/framework/http"

function myMiddleware(req, res, next) {
  // Apply path guard for the specific route
  if (!req.path.endsWith("/admin/products")) {
    return next()
  }
  
  console.log("MIDDLEWARE HIT for /admin/products")
  // Your custom logic for /admin/products POST requests goes here
  next()
}

export default defineMiddlewares({
  routes: [
    {
      matcher: "/admin/*", // Use a wildcard matcher
      methods: ["POST"], // Still specify methods if needed
      middlewares: [myMiddleware],
    },
  ],
})

By implementing this path guard, ESHOPMAN developers can ensure their custom middleware logic is executed only for the intended exact route, providing the necessary precision for tailored storefront management and Admin API extensions.

Impact and Best Practices for ESHOPMAN Developers

This insight is crucial for developers building custom functionality and integrations for their ESHOPMAN stores. While the ESHOPMAN framework continues to evolve, understanding and applying such community-driven workarounds ensures that development efforts for HubSpot-managed storefronts remain unhindered.

When developing custom middleware for ESHOPMAN, especially for Admin API routes, consider these best practices:

• Always test your middleware thoroughly for both exact and wildcard matches.
• If an exact path matcher doesn't trigger, implement the wildcard matcher with an internal path guard as demonstrated.
• Stay engaged with the ESHOPMAN community for the latest insights and solutions.

At Move My Store, we advocate for leveraging the collective knowledge of the ESHOPMAN community to navigate development challenges and build robust, custom headless commerce solutions integrated with HubSpot.