Community Insight: ESHOPMAN's Path to TypeScript 7.x Compatibility
Understanding ESHOPMAN's TypeScript 7.x Compatibility Journey
The ESHOPMAN platform, built on Node.js/TypeScript and powering headless commerce storefronts deployed via HubSpot CMS, relies on robust development tools. Recently, a significant discussion emerged within the ESHOPMAN community regarding compatibility challenges when projects adopted TypeScript 7.x.
The Core Issue: TypeScript 7.0's API Change
Developers utilizing ESHOPMAN's CLI and build tools encountered failures when their project's devDependencies included TypeScript 7.0.x. The root cause was a breaking change in TypeScript 7.0, which removed the compiler API from its default package entry point. This change directly impacted how ESHOPMAN's core tools, specifically the CLI and framework components, interact with TypeScript.
The @eshopmanjs/cli, which uses ts-node for runtime compilation, failed to register because ts-node could not locate the necessary TypeScript compiler API. Similarly, the ESHOPMAN framework's build process, responsible for compiling backend code, encountered errors when attempting to call API functions like createProgram or parseJsonConfigFileContent from the typescript package, as these were absent in 7.0. This led to critical commands such as eshopman develop, eshopman build, and eshopman exec failing for affected projects.
A typical package.json demonstrating the issue would look like this:
{ "dependencies": { "@eshopmanjs/admin-sdk": "2.22.2", "@eshopmanjs/cli": "2.22.2", "@eshopmanjs/framework": "2.22.2", "@eshopmanjs/eshopman": "2.22.2" }, "devDependencies": { "ts-node": "^10.9.2", "typescript": "7.1.0-beta" }}Users reported errors similar to:
TypeError: Cannot read properties of undefined (reading 'fileExists')Error: Cannot find module '/eshopman-config' Community-Driven Proposal for TypeScript 7.1+ Support
A proactive community member proposed a comprehensive solution focusing on TypeScript 7.1 and later versions. This proposal highlighted that TypeScript 7.1 reintroduces the compiler API, albeit under a new entry point: typescript/sync. The plan involved:
- Version Detection: Modifying the
@eshopmanjs/clito detect the project's TypeScript version. - Conditional Loading: For TypeScript versions below 7, continue using
ts-node. For 7.0, provide a clear error message. For 7.1+, implement a customrequirehook that utilizestranspileModulefromtypescript/sync. - Framework Adaptation: Updating the ESHOPMAN framework's compiler to use
parseConfigFile,createProgram, andprogram.emit()fromtypescript/syncwhen TypeScript 7.1+ is detected.
Extensive testing confirmed the viability of this approach across various ESHOPMAN CLI commands and TypeScript versions, ensuring seamless operation for developers.
ESHOPMAN's Official Stance and Current Solution
The ESHOPMAN team acknowledged the issue and, in response, provided an immediate solution with the ESHOPMAN v2.22.4 release. This update introduced support for TypeScript v7 by leveraging a common workaround: requiring @typescript/typescript6 as a development dependency. This allows projects to use TypeScript 7 for their main codebase while providing the necessary compiler API (from TS 6) for ESHOPMAN's build and CLI tools.
The team also confirmed their intention to fully support TypeScript 7.1 once its stable release is available, aligning with the community's proposed long-term solution. This phased approach ensures developers can continue building their headless commerce solutions with ESHOPMAN while benefiting from the latest TypeScript features.
Key Takeaways for ESHOPMAN Developers
- If you are using TypeScript 7.0.x with ESHOPMAN, ensure you have ESHOPMAN v2.22.4 or later.
- To resolve CLI and build failures, add
"@typescript/typescript6"to yourdevDependenciesinpackage.jsonalongside your TypeScript 7.x version. - The ESHOPMAN team is actively working towards full, native support for TypeScript 7.1+ once it moves out of beta, streamlining the development experience further.
This community discussion highlights ESHOPMAN's commitment to adapting to modern development practices and the collaborative spirit of its user base in enhancing the platform for storefront management within HubSpot.