Streamlining Your ESHOPMAN Builds: Understanding Linting Behavior and Non-Blocking Errors

For ESHOPMAN developers leveraging Node.js and TypeScript to power their headless commerce storefronts and deploy them via HubSpot CMS, a smooth and predictable build process is paramount. Our community recently highlighted an important nuance in how ESHOPMAN handles linting errors during the build phase, shedding light on a discrepancy between intended behavior and current implementation.

The core of the discussion revolves around ESHOPMAN's build command – let's refer to it as eshopman build – and its interaction with project linting. The expectation, as outlined in internal documentation, is that eshopman build should treat linting errors as non-blocking warnings, similar to how TypeScript compilation errors are handled. This means the build should complete, producing the necessary artifacts for your HubSpot CMS storefront, even if linting issues are present. In contrast, the development server command, eshopman develop, is correctly designed to gate the server's startup on successful linting, ensuring a clean development environment.

The Discrepancy: Build Exits on Lint Errors

Despite the clear intent for eshopman build to be non-blocking regarding lint errors, developers observed that the build process was actually exiting with an error code (process.exit(1)) whenever linting issues were detected. This behavior mirrored that of eshopman develop, which is contrary to the documented design.

Upon investigation into ESHOPMAN's core build utilities, the root cause was identified within the internal logic. Specifically, the build() function, which orchestrates the build process, calls a utility function named runLintStep. The critical observation was that runLintStep was being invoked without explicitly passing the failOnError parameter:

// Lint after type generation.
await runLintStep({ directory, lint, fix, quiet, logger })

Within the runLintStep utility itself, the failOnError parameter defaults to true if not provided:

const fail ?? true

This default behavior meant that without failOnError: false being explicitly passed by the eshopman build command, any linting error would cause the process to terminate prematurely. This directly contradicted the internal JSDoc comment for runLintStep, which states:

develop gates the dev server on lint passing, so it uses the default failOnError: true. build treats lint like the compiler treats type errors — non-blocking: it surfaces problems but still produces a build, so it passes failOnError: false.

Impact on ESHOPMAN Developers

This behavior can significantly impact the ESHOPMAN development workflow, particularly for projects integrated with `@eshopman/eslint-plugin` and custom eslint.config.js setups. Developers expecting a non-blocking build might find their CI/CD pipelines failing or local builds stalling due to linting issues, even when the underlying TypeScript code is valid and ready for deployment to HubSpot CMS.

Expected Behavior and Resolution

The community insight underscores the importance of aligning the actual implementation with the documented intent. The expected behavior for eshopman build is to:

• Complete the build process successfully.
• Surface any linting errors as warnings in the console output.
• Not exit prematurely due to linting errors, allowing the generation of storefront assets for HubSpot CMS.

The resolution would involve modifying the eshopman build command's internal logic to explicitly pass failOnError: false to the runLintStep function, ensuring that linting errors are treated as non-blocking warnings as originally intended. This change would enhance the developer experience, making the ESHOPMAN build process more robust and predictable for Node.js/TypeScript projects.

Understanding these nuances is crucial for ESHOPMAN developers to effectively manage their storefront projects and ensure smooth deployments to HubSpot CMS.