Add version check on startup to detect outdated cached versions
Problem
When using npx @iobroker/create-adapter, npm may cache an outdated version of the tool, leading users to unknowingly use old versions with potentially outdated templates or missing features. This is particularly problematic as users expect to always get the latest version when using npx.
Solution
This PR implements a version check at startup that:
- Detects outdated versions: Compares the current running version against the latest version published on npm
- Warns users clearly: Displays a prominent warning message showing both versions
- Prevents usage: Exits with code 1 to prevent creating adapters with outdated tooling
-
Provides fix instructions: Tells users to run
npx @iobroker/create-adapter@latestto get the latest version -
Can be bypassed: Adds
--ignoreOutdatedVersionflag for cases where using an older version is intentional
Example Warning Message
When a user runs an outdated version, they will see:
════════════════════════════════════════════════════════════
WARNING: You are using an outdated version!
Current version: 2.0.0
Latest version: 2.6.5
Please update by running:
npx @iobroker/create-adapter@latest
To skip this check, use --ignore-outdated-version
════════════════════════════════════════════════════════════
Implementation Details
- Version check runs before any user prompts
- Uses existing
fetchPackageVersion()andgetOwnVersion()utilities - Leverages
semver.gt()for proper semantic version comparison - Silently ignores network errors (won't fail if npm registry is unreachable)
- Respects the
TEST_STARTUPenvironment variable for CI testing - Supports environment variable
CREATE_ADAPTER_IGNORE_OUTDATED_VERSION
Changes
- Added
--ignoreOutdatedVersionCLI option - Added
checkVersion()function that runs at startup - Updated README.md with new option documentation
Closes #XXX (related to npx caching issue)
Testing
- ✅ All existing unit tests pass
- ✅ All baseline tests pass
- ✅ Linter passes
- ✅ Verified version check logic with various scenarios
- ✅ Confirmed flag bypasses the check
- ✅ Confirmed CI tests still work with TEST_STARTUP
Original prompt
This section details on the original issue you should resolve
<issue_title>Check for updates on startup</issue_title> <issue_description>With
npxit can happen that an old version is cached. We should detect that and warn the user. If that happens we need to tell him to use the npx command with @latest at the end of the package name. We should also update the docs to have have by default in. If the version does not match we should stop the process unless a parameter of "--ignore-outdated-version" is providedVersion check can be done like in dev-server: see https://github.com/ioBroker/dev-server/blob/93790110fa07cf60da42bfd97cbf51c6dc75b6f9/src/index.ts#L231-L259</issue_description>
Comments on the Issue (you are @copilot in this section)
Fixes ioBroker/create-adapter#1021
✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.