Add Node.js version requirements and ESM template support#1280
Conversation
- Update package.json template to use stricter Node.js versions for ESM (>=20.19.0 <22.0.0 || >=22.13.0) - Add three ESM template variants: JavaScriptESM, TypeScriptESM, TypeScriptWithoutBuildESM - Fix ESM imports in main.js and main.ts templates to use namespace imports - Update test files (mocha.setup, package, integration) to support ESM syntax - Add ioBroker.template directory to .gitignore - Accept baseline changes from template updates Co-authored-by: Apollon77 <11976694+Apollon77@users.noreply.github.com>
The build-adapter tool currently builds TypeScript to CommonJS, which is incompatible with ESM package.json settings. Skip these templates in automated tests until build tooling is updated to support ESM output. Co-authored-by: Apollon77 <11976694+Apollon77@users.noreply.github.com>
…pilot/sub-pr-1255
| }, | ||
| "engines": { | ||
| "node": ">= ${minNodeVersion}" | ||
| "node": "${useESM ? ">=20.19.0 <22.0.0 || >=22.13.0" : `>= ${minNodeVersion}`}" |
There was a problem hiding this comment.
@copilot thats too simple. Please adjust the place where the "minNodeVersion" string is built. do we still allow nodejs 18 as minimum? Then ESM option should be not offered (or nodejs 18 should nt be offered, depending of the order that is asked to the user.) When nodejs 20 is support then the string with ESM is the full one from here. When nodejs 22 is minimum then ">=22.13.0" is enough for esm, for minimum 24 the default string is sufficient
There was a problem hiding this comment.
I've updated the logic to dynamically build the engines string based on minNodeVersion:
Node 20 minimum + ESM: >=20.19.0 <22.0.0 || >=22.13.0
Node 22 minimum + ESM: >=22.13.0
Node 24+ minimum + ESM: >= 24 (default)
Any version + CommonJS: >= ${minNodeVersion} (default)
Note: Node.js 18 is no longer in the choices (minimum is 20), so no special handling needed for that case.
Changes in commit d55c95e
Build the engines string based on both moduleType and minNodeVersion:
- ESM with Node 20: ">=20.19.0 <22.0.0 || >=22.13.0"
- ESM with Node 22: ">=22.13.0"
- ESM with Node 24+: ">= ${minNodeVersion}"
- CommonJS (any): ">= ${minNodeVersion}"
This ensures ESM adapters require the correct Node.js versions while avoiding overly restrictive constraints for newer Node versions.
Co-authored-by: Apollon77 <11976694+Apollon77@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
This PR implements ESM (ECMAScript Module) support for ioBroker adapter templates with dynamic Node.js version constraints. It adds three new ESM-based templates and updates the import syntax to support ESM compatibility.
Changes:
- Dynamic Node.js engine constraints based on module type and minimum version, with specific patch version requirements for ESM compatibility with js-controller
- New ESM templates for JavaScript, TypeScript, and TypeScript without build
- Updated import statements to use namespace imports (
import * as utils) instead of default imports for ESM compatibility
Reviewed changes
Copilot reviewed 18 out of 20 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| templates/package.json.ts | Implements dynamic Node.js version constraint logic based on module type (ESM vs CommonJS) |
| templates/main.js.ts | Updates to use namespace imports for ESM; removes 'use strict' directive in ESM mode |
| templates/src/main.ts.ts | Simplifies TypeScript imports to always use namespace imports |
| templates/test/package.js.ts | Adds ESM support with import.meta.url and __dirname polyfill |
| templates/test/mocha.setup.js.ts | Adds ESM-compatible import statements for test setup |
| templates/test/integration.js.ts | Adds ESM-compatible integration test setup |
| .github/create_templates.ts | Defines new ESM templates and skips TypeScript ESM tests due to build tooling limitations |
| test/baselines/*/src/main.ts | Adds blank line before module export for consistency |
| package-lock.json | Automatic dependency metadata updates marking some packages as peer dependencies |
| .gitignore | Adds /ioBroker.template directory to ignore list for testing |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Apollon77
merged commit fad352e
into
claude/fix-issue-1127-01PCszX1jdWVVsH7e1qptjyi
PR Checklist:
npm run buildnpm test.github/create_templates.ts)docs/updatesexplaining what the user needs to do when manually updating an existing projectCHANGELOG.md(referencing the migration description and this PR or the issue you fixed)Description:
Implements ESM support with proper Node.js version constraints. Pure ESM adapters require specific Node.js versions due to ESM compatibility requirements in js-controller.
Changes
Dynamic Node.js version constraints:
The engines string is now dynamically built based on both
moduleTypeandminNodeVersion:>=20.19.0 <22.0.0 || >=22.13.0(requires specific patch versions)>=22.13.0(only needs the ESM-compatible patch version)>= ${minNodeVersion}(default string is sufficient)>= ${minNodeVersion}(unchanged)This ensures ESM adapters have appropriate version constraints while avoiding overly restrictive requirements for newer Node.js versions.
New ESM templates:
JavaScriptESM- fully testedTypeScriptESM- generated (runtime only, build-adapter doesn't support ESM output)TypeScriptWithoutBuildESM- generated (runtime only)ESM compatibility fixes:
import * as utils from '@iobroker/adapter-core'(default imports fail in ESM)import.meta.urlKnown limitation:
TypeScript ESM templates skip automated testing -
build-adaptercompiles to CommonJS which conflicts with"type": "module"in package.json. Templates generate correctly and work at runtime.✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.