Which strategy should I use for AdonisJS v7 ESM and Node 22?
Evaluate whether to take the AdonisJS v7 migration now that newer runtime and ESM-oriented tooling requirements change deployment, test, and package-resolution behavior.
Blockers
- The upgrade guide states v7 requires Node.js 24 or above.
- The official upgrade guide calls out Vite 7 as part of the aligned tooling baseline.
- The official upgrade guide calls out ESLint 10 as part of the aligned tooling baseline.
- The official upgrade guide calls out TypeScript 5.9/6.0 as the aligned tooling baseline.
- The official upgrade guide calls out TypeScript 5.9/6.0 as the aligned tooling baseline.
- The migration requires replacing ts-node with @poppinss/ts-exec.
- If the current estate is still pinned to Node 22, v7 is blocked immediately because the official requirement is Node.js 24+.
Who this is for
- small-team
- monorepo
- low-ops
Candidates
Migrate to AdonisJS v7 now and uplift all environments to Node.js 24+
As of 2026-04-02, AdonisJS v7 is already generally available; the official release post says v7 shipped on 2026-02-25, and the upgrade guide states v7 requires Node.js 24 or above. The official upgrade guide also calls out TypeScript 5.9/6.0, ESLint 10, and Vite 7 as the aligned tooling baseline. The migration is presented as incremental with a small breaking-change surface, but the required changes are operationally real: replace `ts-node` with `@poppinss/ts-exec`, add new `package.json` `imports` aliases, move to `import.meta.dirname`/`import.meta.filename`, and re-run build, dev, and test verification. Production deployment also changes shape because AdonisJS documents `node ace build` as the production path, generating a `build/` directory where dependencies are then installed and the server started.
When to choose
Use this when you can raise local, CI, and production runtimes to Node.js 24+ in one coordinated pass and you want current framework defaults instead of carrying compatibility debt. The decisive factor is whether the Node 24 platform uplift is already acceptable for your deployment target, because that is the hard gate in the official docs.
Tradeoffs
You get the current supported major, upgraded tooling, new hooks, and the documented v7 fixes and features. In exchange, this is not just a package bump: runtime baseline, JIT execution, package aliasing, and some framework APIs all change together.
Cautions
If your current estate is still pinned to Node 22, v7 is blocked immediately because the official requirement is Node.js 24+. Watch especially for encrypted-data migrations, Inertia shared-data rewrites, renamed Request/Response classes, changed test glob syntax, removed helper APIs, and the new `imports` aliases in `package.json`.
Stay on AdonisJS v6 for now and defer the v7 move until Node.js 24 rollout is complete
As of 2026-04-02, this is still a valid temporary posture because the v7 release post explicitly links to the v6 docs for teams that need more time, and it says patched fixes were backported to v6 during the v7 development cycle. Official v6 documentation remains available, and its docs already describe an ES-module-based stack with Node.js sub-path imports and SWC-backed TypeScript execution, so deferral does not mean returning to a CommonJS-era toolchain. The main reason to defer is not feature immaturity in v7; it is avoiding a forced runtime uplift and the associated CI, build, and deployment rewiring right now. This buys schedule flexibility while you prepare Node 24 images, hosting, and test runners.
When to choose
Use this when your blocker is infrastructure readiness rather than framework desire: for example, production base images, managed platforms, or internal CI still standardize on Node 22. The decisive factor is whether a Node 24 rollout would be riskier this quarter than staying on v6 with backported fixes.
Tradeoffs
You avoid immediate migration churn and keep existing deployment and test conventions longer. The downside is deliberate lag: new v7 APIs, starter-kit defaults, and the current documented upgrade path remain deferred, so the eventual migration becomes a larger combined change.
Cautions
Do not treat deferral as a long-term steady state without a runtime plan. The official v7 materials make clear that the new major is built around Node 24-native behavior, `@poppinss/ts-exec`, `import.meta.*` replacements, and explicit `package.json` subpath imports, so the more custom tooling you add on v6 now, the more migration cleanup you create later.
Try with your AI agent
$ npm install -g pocketlantern $ pocketlantern init # Restart Claude Code, Cursor, or your MCP client, then ask: # "Which strategy should I use for AdonisJS v7 ESM and Node 22?"