diff --git a/packages/pluggable-widgets-tools/CHANGELOG.md b/packages/pluggable-widgets-tools/CHANGELOG.md index ba2575d4..7d121166 100644 --- a/packages/pluggable-widgets-tools/CHANGELOG.md +++ b/packages/pluggable-widgets-tools/CHANGELOG.md @@ -12,64 +12,9 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), ### Changed +- We upgraded rollup to version 3. Custom rollup.config.js files [likely require changes](./docs/rollup3-guide.md). - The renderMode property in the preview arguments is no longer considered optional. - -#### Rollup 3 - -We upgraded the bundling setup. For most packages this meant updating to the latest minor or patch versions, but for Rollup we upgraded from major version 2 to 3. If your widget uses custom configurations you may need to perform some actions. - -1. Ensure you are using node 20 or above. -2. Upgrade any Rollup related package to their latest (Rollup 3 supporting) version: `npm install @latest`. -3. Update your custom rollup configuration: - - If your rollup configuration imports our base rollup configuration, rename the import to `@mendix/pluggable-widgets-tools/configs/rollup.config.mjs`. - - Rollup now offers native support for ES Modules for Rollup configuration. This does mean it is stricter with regards to ESM and CJS, ensure that: - - If you are using ESM to use the `.mjs` extension for your `rollup.config.mjs` file. - - If you are using CJS you can continue using the `.js` extension for your `rollup.config.js` file. - -If you decide to continue using ES Modules for your rollup configuration, there are [some caveats to be aware of](https://rollupjs.org/command-line-interface/#caveats-when-using-native-node-es-modules). Below we highlight a few. - -##### ES Module Imports - -When using ESM you should rename your Rollup configuration files to `.mjs`. This tells node to expect ESM for that particular file. Import statements targeting local files should be updated to include the file extension. - -When importing some CJS packages you may no longer be able to access individual named exports directly. In this case you will need to import the full module. You can [desctructure](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) the module to keep the rest of your implementation the same. - -```js -// Partial import -import { cp } from "shelljs"; -// Full namespace import -import shelljs from "shelljs"; -const { cp } = shelljs; -``` - -##### ES Module __Dirname - -In ESM files the `__dirname` variable is not available. Instead, you can access the current file's path using `import.meta.url`. Do note that this includes the `file:` protocol prefix. An easy way to work with the file's url is to use it as the [base value for the URL constructor](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL#base). This will allow you to resolve a relative path from that path. For example `new URL("../", "file:/a/b/c.txt")` results in the URL `file:/a`. - -```js -// ESM equivalent of __dirname -const dirname = new URL("./", import.meta.url).pathname; -``` - -Also note that `require()` is unavailable in ESM files. A common usecase for rollup setups is accessing the package.json of a project. If this is a static location relative to the script, you may use a typed import. Otherwise, read the file from the file system and parse it as JSON. - -```js -// CJS method -import { join } from "node:path"; -const packagePath = join(process.cwd(), "/package.json"); -const package = require(packagePath); - -// ESM import with attributes -import package from "../package.json" with { type: "json" } - -// Dynamic import with attributes -const package = await import(packagePath, { with: { type: "json" }}) - -// Read file and parse (async version with fs.readFile) -import { readFileSync } from "node:fs" -const package = JSON.parse(readFileSync(packagePath)) -``` - +- We updated the Mendix package to 10.18.54340. ## [10.16.0] - 2024-10-31 diff --git a/packages/pluggable-widgets-tools/README.md b/packages/pluggable-widgets-tools/README.md index b4abbc85..d2c90724 100644 --- a/packages/pluggable-widgets-tools/README.md +++ b/packages/pluggable-widgets-tools/README.md @@ -72,7 +72,7 @@ In your `package.json` scripts, use the following command with the desired task: ## Migrating from previous versions -- 10.17 includes an upgrade from Rollup 2 to 3. See the [changelog](./CHANGELOG.md) for upgrade notes. +- 10.17 includes an upgrade from Rollup 2 to 3. Custom `rollup.config.js` files [likely require changes](./docs/rollup3-guide.md). - Webpack bundler is changed to a Rollup. You must migrate your custom configuration. - Update `pluggable-widgets-tools` commands used in your `package.json` file to one of the described in this readme. In particular `start:js`, `start:ts`, and `start:server` commands should be changed to `start:web`. - You now can use named exports in your widget. That is, you can write `export MyWidget;` instead of `export default MyWidget;`. diff --git a/packages/pluggable-widgets-tools/docs/rollup3-guide.md b/packages/pluggable-widgets-tools/docs/rollup3-guide.md new file mode 100644 index 00000000..05a28bcc --- /dev/null +++ b/packages/pluggable-widgets-tools/docs/rollup3-guide.md @@ -0,0 +1,64 @@ + +# Rollup 3 Upgrade Guide + +In 10.18 we upgraded the Rollup bundling setup from major version 2 to 3. If your widget uses custom configurations you may need to perform some actions. + +1. Ensure you are using node 20 or above. +2. Upgrade any Rollup related package to their latest (Rollup 3 supporting) version: `npm install @latest`. +3. Update your custom rollup configuration: + - If your rollup configuration imports our base rollup configuration, rename the import to `@mendix/pluggable-widgets-tools/configs/rollup.config.mjs`. + - Rollup now offers native support for ECMAScript Modules (ESM) for Rollup configuration. This does mean it is stricter with regards to ESM and CJS, ensure that: + - If you are using ESM to use the `.mjs` extension for your `rollup.config.mjs` file. + - If you are using CJS you can continue using the `.js` extension for your `rollup.config.js` file. + +## ECMAScript Module Caveats + +If you decide to continue using ES Modules for your rollup configuration, there are [some caveats to be aware of](https://rollupjs.org/command-line-interface/#caveats-when-using-native-node-es-modules). Below we highlight a few. + +### Rollup Config Filenames + +When using ESM you should rename your Rollup configuration files to `.mjs`. This tells node to expect ESM for that particular file. Import statements targeting local files should be updated to include the file extension. + +### Importing CommonJS files + +When importing some CJS packages you may no longer be able to access individual named exports directly. In this case you will need to import the full module. You can [desctructure](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Destructuring_assignment) the module to keep the rest of your implementation the same. + +```js +// Partial import +import { cp } from "shelljs"; +// Full namespace import +import shelljs from "shelljs"; +const { cp } = shelljs; +``` + +### __Dirname + +In ESM files the `__dirname` variable is not available. Instead, you can access the current file's path using `import.meta.url`. Do note that this includes the `file:` protocol prefix. An easy way to work with the file's url is to use it as the [base value for the URL constructor](https://developer.mozilla.org/en-US/docs/Web/API/URL/URL#base). This will allow you to resolve a relative path from that path. For example `new URL("../", "file:/a/b/c.txt")` results in the URL `file:/a`. + +```js +// ESM equivalent of __dirname +const dirname = new URL("./", import.meta.url).pathname; +``` + +### Absense of require() + +Also note that `require()` is unavailable in ESM files. A common usecase for rollup setups is accessing the package.json of a project. If this is a static location relative to the script, you may use a typed import. Otherwise, read the file from the file system and parse it as JSON. + +```js +// CJS method +import { join } from "node:path"; +const packagePath = join(process.cwd(), "/package.json"); +const package = require(packagePath); + +// ESM import with attributes +import package from "../package.json" with { type: "json" } + +// Dynamic import with attributes +const package = await import(packagePath, { with: { type: "json" }}) + +// Read file and parse (async version with fs.readFile) +import { readFileSync } from "node:fs" +const package = JSON.parse(readFileSync(packagePath)) +``` + +