bug: v6, describe how to account for es modules in project

[dashreel]

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

• v4.x
• v5.x
• v6.x

Current Behavior

When using next-build with ionic/core

I get this error with beta 6 version 6 or greater

^^^^^^

SyntaxError: Unexpected token 'export'

Expected Behavior

Would build like it does with beta 6 version 5

Steps to Reproduce

run next build with ionic beta 6 version 6 or great with ionic/core

Code Reproduction URL

No response

Ionic Info

No response

Additional Information

No response

[ionitron-bot]

Thanks for the issue! This issue has been labeled as needs reproduction. This label is added to issues that need a code reproduction.

Please reproduce this issue in an Ionic starter application and provide a way for us to access it (GitHub repo, StackBlitz, etc). Without a reliable code reproduction, it is unlikely we will be able to resolve the issue, leading to it being closed.

If you have already provided a code snippet and are seeing this message, it is likely that the code snippet was not enough for our team to reproduce the issue.

For a guide on how to create a good reproduction, see our Contributing Guide.

[Polarisation]

I'm also seeing this issue.

@liamdebeasi I've put together a reproduction. To see the error, run yarn install then yarn build.

Stack track for error when running yarn build:

info  - Collecting page data .node:internal/process/promises:246
          triggerUncaughtException(err, true /* fromPromise */);
          ^

ionic-next-js/node_modules/@ionic/core/components/index.js:1
export { setAssetPath, setPlatformOptions } from '@stencil/core/internal/client';
^^^^^^

SyntaxError: Unexpected token 'export'
    at Object.compileFunction (node:vm:355:18)
    at wrapSafe (node:internal/modules/cjs/loader:1039:15)
    at Module._compile (node:internal/modules/cjs/loader:1073:27)
    at Object.Module._extensions..js (node:internal/modules/cjs/loader:1138:10)
    at Module.load (node:internal/modules/cjs/loader:989:32)
    at Function.Module._load (node:internal/modules/cjs/loader:829:14)
    at Module.require (node:internal/modules/cjs/loader:1013:19)
    at require (node:internal/modules/cjs/helpers:93:18)
    at Object.<anonymous> (ionic-next-js/node_modules/@ionic/react/dist/index.js:6:20)
    at Module._compile (node:internal/modules/cjs/loader:1109:14) {
  type: 'SyntaxError'
}
error Command failed with exit code 1.

The source of the error seems to be in @ionic/core but for some only appears when using it via @ionic/react.

[liamdebeasi]

Ionic 6 will be using ES Modules, and it looks like Next.js still has a few issues with supporting ES Modules: https://github.com/vercel/next.js/issues?q=is%3Aissue+is%3Aopen+Unexpected+token+%27export%27

As a temporary workaround, you can use https://www.npmjs.com/package/next-transpile-modules which is a Next.js plugin that will transpile ES Modules to Common JS (CJS).

While we do not consider this a bug in Ionic, we are still discussing the best path forward in terms of documentation and migration guides. I will update this thread when I have more to share. Thanks!

[liamdebeasi]

Actually there are 2 issues here, 1 Ionic and 1 non-Ionic. The Ionic issue is that the custom elements generated directly reference HTMLElement which is not defined in an SSR environment. The fix for this likely needs to be in the Stencil, so I will work with them to resolve that. Thanks again!

[Polarisation]

Thank you, transpiring the Ionic/Stencil modules looks like a promising and reasonable solution, once the Stencil bug is fixed.

[liamdebeasi]

Hi everyone,

A couple updates here:

1. We have a branch open that will update Ionic Vue and Ionic React starters to automatically compile ES Modules down to CommonJS (CJS) so that Jest tests will work.
2. We have written a migration guide for developers going to Ionic 6 using React or Vue. I have provided it below for those looking to make the migration now, but it will also be part of a full migration guide when Ionic 6 ships.

I am going to close this issue out as the main work required to get this issue resolved has been completed. Keep an eye out for the full migration guide as it will detail other breaking changes in Ionic 6. Thanks!

---

Jest Migration

Ionic 6 now ships as ES Modules. ES Modules are supported in all major browsers and bring developer experience and code maintenance improvements. Developers testing with Jest will need to update their Jest configuration as Jest does not have full support for ES Modules as of Jest 27.

This update involves using Babel to compile Ionic's ES Modules down to the CommonJS (CJS) format, a format that Jest can understand. Once Jest ships support for ES Modules, this change will no longer be necessary. See jestjs/jest#9430 for updates on ES Modules support in Jest.

If you are starting fresh with a new Ionic app, this configuration is done for you in our starter applications. For those with existing Ionic apps, follow the steps below to get Jest working with Ionic 6.

Ionic Vue

1. In your Jest config (either in jest.config.js or the "jest" field in your package.json), add the following transformIgnorePatterns:

modules.exports = {
  ...,
  transformIgnorePatterns: ['/node_modules/(?!@ionic/vue|@ionic/vue-router|@ionic/core|@stencil/core|ionicons)']
}

Ionic React

For developers using Create React App (CRA), there is currently no way to update the transformIgnorePatterns in a Jest config file. This is a CRA restriction and not something Ionic has control over. We can, however, pass the transformIgnorePatterns directly into the react-scripts test command.

1. In your package.json, update the "test" field in the "scripts" object:

"scripts": {
  "test": "react-scripts test --transformIgnorePatterns 'node_modules/(?!(@ionic/react|@ionic/react-router|@ionic/core|@stencil/core|ionicons)/)'",
  ...
}

[ionitron-bot]

Thanks for the issue! This issue is being locked to prevent comments that are not relevant to the original issue. If this is still an issue with the latest version of Ionic, please create a new issue and ensure the template is fully filled out.