Feathers 5 ESM-first modules create a CommonJS compatibility boundary for existing applications

Answer

The documented compatibility boundary is at module loading. Feathers 5 packages publish ESM-first entry points. A CommonJS file that calls require('@feathersjs/feathers') will fail with ERR_REQUIRE_ESM because Node.js will not load an ESM-only export via require. Once an ESM module is loaded, it runs under ESM semantics.

Dynamic import() from a CommonJS entry point is the standard Node.js mechanism to load ESM-only code. It is technically possible to bootstrap Feathers 5 with await import('@feathersjs/feathers') inside a CommonJS file, but the bootstrap becomes asynchronous. That changes initialization order for transports, hooks and plugin configuration that were previously synchronous in Feathers 4 CommonJS apps. There is no documented Feathers 5 guarantee that a mixed CJS/ESM app will behave identically to a pure ESM app, and mixing can create the dual package hazard if the same dependency is loaded once via require and once via import.

Confirmed facts

• Feathers 5 adopts an ESM-first architecture. Primary package exports resolve through ES module entry points.
• CommonJS require() cannot load ESM-only packages. Node.js returns ERR_REQUIRE_ESM.
• Dynamic import() is the standard way to load ESM from CommonJS. It is asynchronous.
• TypeScript module resolution for Feathers 5 typically requires moduleResolution: 'NodeNext' or equivalent to resolve ESM exports.

Likely explanation, not confirmed

• Feathers 5 is not documented as supporting a long-term mixed CJS host with ESM core. The intended migration path is a full ESM codebase.
• Third-party Feathers plugins may work in ESM even if written in CJS, but ESM-only plugins cannot be required. Compatibility depends on each plugin's package.json exports and type field.
• Behavioral differences in transport and plugin configuration from async bootstrapping are likely but not formally documented. They depend on Node.js version and how the app awaits the imported Feathers instance before starting the server.

Steps needed for this case

1. Verify the boundary. In a .cjs file run a test require to confirm ERR_REQUIRE_ESM, then check package.json 'type' and 'exports' for @feathersjs/feathers and key plugins.
2. Prototype an async bootstrap. Wrap Feathers initialization in an async IIFE and load the core with await import('@feathersjs/feathers'). Start the server only after the import resolves.
3. Audit the plugin ecosystem. For each plugin, inspect its package.json for 'type': 'module' or an ESM entry in 'exports'. If a plugin only provides a CommonJS main, it cannot be required from ESM without an interop layer.
4. Update TypeScript if used. Set moduleResolution to NodeNext and ensure .ts files use explicit file extensions for ESM imports.

One missing diagnostic that changes the recommendation: Node.js runtime version and whether the application entry uses package.json "type": "module" or .mjs/.cjs extensions. Pure ESM loading requirements and dynamic import support vary by Node.js version, and the file extension determines whether the entry itself is treated as CJS or ESM.