bug: @ionic/angular incompatible with Angular 21 native Vitest (@angular/build:unit-test) - ESM directory imports

[devsappines]

Prerequisites

• I have read the Contributing Guidelines.
• I agree to follow the Code of Conduct.
• I have searched for existing issues that already report this problem, without success.

Ionic Framework Version

v8.x

Current Behavior

When using Angular 21's native Vitest support (@angular/build:unit-test builder), tests fail with ESM directory import errors for any component that imports from @ionic/angular.

Error message:
Error: Directory import '/node_modules/@ionic/core/loader' is not supported resolving ES modules imported from /node_modules/@ionic/angular/fesm2022/ionic-angular.mjs
Did you mean to import "@ionic/core/loader/index.js"?

And:
Error: Directory import '/node_modules/@ionic/core/components' is not supported resolving ES modules imported from /node_modules/@ionic/angular/fesm2022/ionic-angular-standalone.mjs
Did you mean to import "@ionic/core/components/index.js"?

Expected Behavior

Tests should run successfully when using Angular 21's native Vitest builder with @ionic/angular.

Steps to Reproduce

Steps to Reproduce

1. Create an Angular 21 project with Ionic 8
2. Configure angular.json to use:

   "test": {
     "builder": "@angular/build:unit-test",
     "options": {
       "tsConfig": "tsconfig.spec.json"
     }
   }
 }

3. Create a test file that imports any Ionic component
4. Run ng test

Code Reproduction URL

https://angular.dev/guide/testing

Ionic Info

Ionic:
Ionic CLI : 7.2.0
Ionic Framework : @ionic/angular 8.7.18
@angular-devkit/build-angular : 21.2.0
@angular-devkit/schematics : 20.3.15
@angular/cli : 21.2.0
@ionic/angular-toolkit : 12.3.0
Angular version: 21.2.0
Vitest version: 4.0.18

Capacitor:
Capacitor CLI : 7.4.5
@capacitor/android : 7.4.5
@capacitor/core : 7.4.5
@capacitor/ios : 7.4.5

Utility:
cordova-res : not installed globally
native-run : 2.0.3

System:
NodeJS : v22.22.0
npm : 10.9.4

Additional Information

The issue is that @ionic/angular uses directory imports:

Current (broken)	Should be
@ionic/core/components	@ionic/core/components/index.js
@ionic/core/loader	@ionic/core/loader/index.js

Node.js ESM does not support directory imports, and Vitest runs in ESM mode.

---

Workarounds Attempted

Workaround	Result
runnerConfig with server.deps.inline	❌ No effect - Angular's builder overrides settings

---

Related Issues

• bug: Directory import ... is not supported resolving ES modules imported from ... Did you mean to import "@ionic/core/components/index.js"? #30686 - Similar issue with @ionic/react
• bug: Directory import is not supported resolving ES modules #30730 - Similar issue with @ionic/vue
• [@angular/build:unit-test][vitest] Configurable vitest angular/angular-cli#30429 - Request for Vitest configuration support

---

Additional Context

Angular 21 has made Vitest the default test runner. This incompatibility prevents Ionic Angular users from adopting Angular 21's native testing approach.

[cunhaedu]

I ran into the same ESM directory import errors, but using a custom vitest.config.ts instead of Angular's native builder. I tried several Vite/Vitest config approaches (resolve.alias, server.deps.inline, custom plugins) and none of them worked, the error happens before Vite gets a chance to intercept the import.

The only thing that actually worked for me was patching the files directly. Sharing here in case it helps anyone:

---

Workaround

# scripts/patch-ionic.sh
#!/bin/bash
sed -i '' "s|from '@ionic/core/components'|from '@ionic/core/components/index.js'|g" node_modules/@ionic/angular/fesm2022/ionic-angular-common.mjs
sed -i '' "s|from '@ionic/core/components'|from '@ionic/core/components/index.js'|g" node_modules/@ionic/angular/fesm2022/ionic-angular-standalone.mjs
sed -i '' "s|from '@ionic/core/loader'|from '@ionic/core/loader/index.js'|g" node_modules/@ionic/angular/fesm2022/ionic-angular.mjs
echo "✓ Ionic Angular imports patched"

// package.json
{
  "scripts": {
    "postinstall": "bash scripts/patch-ionic.sh"
  }
}

⚠️ The -i '' flag is macOS/BSD syntax. On Linux, use sed -i without the empty string.

---

If you prefer a more robust alternative, you can use patch-package instead since it ensures your postinstall fails explicitly if the patch no longer applies after an @ionic/angular update.
After running patch-ionic.sh, generate the patch file with:

npm install patch-package --save-dev
npx patch-package @ionic/angular

This generates a patches/@ionic+angular+<version>.patch file. Commit it, then:

{
  "scripts": {
    "postinstall": "patch-package"
  }
}

If a future release of @ionic/angular fixes this natively, patch-package will throw on install, signaling the patch can be removed.

---

Why this happens

Node.js in ESM mode does not resolve directory imports implicitly — it won't infer index.js from a bare directory path. The published .mjs files in @ionic/angular contain imports like from '@ionic/core/components' which violates the ESM spec. The fix needs to land in the package itself; this workaround just patch the published files until that happens.

[ShaneK]

Hey! I merged a PR that will fix this in v9 when it releases. It had to be done in v9 because it limits the exports to our documented exports and that's a breaking change since we can't predict if people are importing things that aren't documented.

Unfortunately, for that reason, it is a breaking change (since it would break for those people) and we can't put it into v8.

There is a dev build for it here: 8.8.9-dev.11780086312.13aac420 but note that it's a dev build for v9, which will have many other breaking changes (RR6, Angular 21 support soon, Vue, and Ionic Modular are all coming in v9), so migrating to it at this time might be a bad idea before it's fully settled.