Navigating Root Path API Routing: A Key Fix for ESHOPMAN Developers

For ESHOPMAN developers building custom API endpoints or implementing global middlewares, understanding how the platform handles routing is crucial. Recently, our community identified and resolved a silent issue affecting routes and middlewares defined for the bare root path (/) within the ESHOPMAN Admin and Store APIs. This insight details the problem, its impact, and the solution, ensuring your custom logic deploys as expected.

The Challenge: Silent 404s on the Root Path

Developers using ESHOPMAN's Node.js/TypeScript framework might have encountered a peculiar issue: attempts to define a custom API route at src/api/route.ts or register a global middleware with matcher: "/" would result in a 404 Not Found error. Crucially, this failure was silent—no errors were logged during build or server startup, making it challenging to diagnose.

For instance, a simple root API endpoint:

// src/api/route.ts
import { EshopmanRequest, EshopmanResponse } from "@eshopman/framework";

export const GET = async (req: EshopmanRequest, res: EshopmanResponse) => {
  res.json({ ok: true });
};

When accessed via curl -i http://localhost:9000/, would return a 404, instead of the expected {"ok":true}. The same behavior was observed with root-level middlewares intended for redirects or authentication:

// src/api/middlewares.ts
import { defineMiddlewares } from "@eshopman/eshopman";

export default defineMiddlewares({
  routes: [
    {
      matcher: "/",
      middlewares: [(req, res, next) => { res.redirect("/app"); }],
    },
  ],
});

This meant any custom logic intended for the primary entry point of your ESHOPMAN headless commerce solution, whether for a custom storefront deployed via HubSpot CMS or an Admin API extension, simply wouldn't activate.

Understanding the Root Cause

The core of the problem lay within ESHOPMAN's internal routing mechanism, specifically how it processed route matchers. When a path like "/" was split and filtered to identify its segments, it resulted in an empty array. The routing logic, designed to iterate over these segments, would then skip the route entirely because there were no segments to process. Consequently, the route or middleware was never registered with the underlying Express application, leading to the silent 404.

Immediate Workaround (for ESHOPMAN versions prior to v2.18.0)

For developers on ESHOPMAN versions older than v2.18.0, a practical workaround was devised. Instead of using matcher: "/", you could leverage matcher: "*" and then conditionally check the original URL within your middleware:

{
  matcher: "*",
  middlewares: [
    (req, res, next) => {
      if (req.originalUrl === "/") {
        return res.redirect("/app/login"); // Or handle your root path logic
      }
      next();
    },
  ],
}

It's crucial to use req.originalUrl here, as req.path would always be "/" inside a matcher: "*" middleware, potentially causing unintended redirects for all API requests.

The Resolution: ESHOPMAN v2.18.0 and Beyond

We are pleased to confirm that this routing anomaly was officially addressed and resolved in ESHOPMAN v2.18.0. A specific guard was added to the routing processor to correctly handle zero-segment matchers (like "/"), ensuring they are properly registered. This fix was included in the release of v2.18.0 on July 23, 2026.

If you are currently experiencing this issue, upgrading your ESHOPMAN installation to v2.18.0 or a newer version will resolve it, allowing your src/api/route.ts files and matcher: "/" middlewares to function as intended. This ensures seamless integration for your custom storefronts and Admin API extensions within the HubSpot ecosystem.

The ESHOPMAN community is committed to refining the platform, making it a robust foundation for your headless commerce needs, from storefront management in HubSpot to powerful Admin API capabilities.