ESHOPMAN Build Gotcha: Why Your 'Test' Scripts Might Be Missing from Deployments

As ESHOPMAN developers, we often rely on custom scripts for various tasks, from seeding data to running specific administrative functions via the Admin API. When deploying your ESHOPMAN storefronts and backend services through HubSpot CMS, ensuring all your custom code is correctly bundled is paramount. However, a subtle behavior in the ESHOPMAN build process can silently exclude certain files, leading to unexpected omissions in your deployed application.

The Silent Exclusion: When 'test' Means Trouble for Your ESHOPMAN Builds

A recent community discussion highlighted an important insight: the eshopman build command, responsible for compiling your ESHOPMAN application for deployment, has a default behavior that can inadvertently drop files from your build output. Specifically, any file whose path contains the substring 'test' is silently excluded. While the intention is to skip directories like integration-tests/, test/, or unit-tests/, the current implementation uses a broad string match, affecting legitimate user-authored scripts.

Imagine creating a script named src/scripts/seed-test-accounts.ts or src/scripts/reset-test-vendor-password.ts. You develop and test it locally, expecting it to be part of your ESHOPMAN deployment to HubSpot. However, these files might never make it into your compiled .eshopman/server/src/scripts/ directory, leading to missing functionality in your live environment or when interacting with the Admin API.

Reproducing the ESHOPMAN Build Behavior

You can easily observe this behavior:

• Create a TypeScript file, for example, src/scripts/reset-test-vendor-password.ts, with some simple output:

  import type { ExecArgs } from "@eshopman/framework/types"
  export default async function ({ container }: ExecArgs) {
    console.log("hello ESHOPMAN deployment!")
  }
  

• Run your ESHOPMAN build command: npx eshopman build.
• Inspect the compiled output directory (e.g., .eshopman/server/src/scripts/). You'll find that reset-test-vendor-password.js is missing.
• Now, rename the file to something like src/scripts/reset-fixture-vendor-password.ts and rebuild. The file will now appear in the compiled output.

Understanding the Root Cause

The ESHOPMAN framework's build tools include a hardcoded list of file path segments to ignore during compilation. This list includes entries like "integration-tests", "test", and "unit-tests". The filtering mechanism then checks if any file path includes these substrings. This broad matching means that a filename containing "test" (e.g., my-test-helper.ts) will be treated the same as a file within a test/ directory.

This behavior is particularly impactful because it's entirely silent. There are no warnings or logs indicating that a file has been excluded. Developers might spend considerable time debugging why a script isn't executing or why a specific Admin API endpoint isn't working as expected, only to discover the file never made it to the server.

Immediate Workaround for ESHOPMAN Developers

The most straightforward solution is to rename any custom scripts or files that contain the substring 'test' in their path. Many ESHOPMAN community members have adopted alternatives like using 'fixture' (e.g., seed-fixture-accounts.ts) or other descriptive terms that don't trigger the exclusion. This ensures your critical scripts are correctly bundled and deployed to your HubSpot-managed ESHOPMAN storefront.

Looking Ahead: Community Suggestions for Improvement

The ESHOPMAN community has suggested more robust filtering mechanisms for future updates, such as matching specific path segments (e.g., /test/) rather than any substring, or leveraging proper glob semantics through tsconfig.exclude. These improvements would provide more precise control over the build process and prevent such silent exclusions, enhancing the developer experience for ESHOPMAN on Node.js/TypeScript.

By understanding this nuance in the ESHOPMAN build process, you can proactively manage your custom scripts and ensure a seamless deployment of your headless commerce solution via HubSpot CMS, maintaining the integrity of your storefront and Admin API functionalities.