Migrate Your Plugin to ESM

Node.js supports two ways of packaging JavaScript and TypeScript code: CommonJS modules and ECMAScript modules (or ESM). If you generated your Salesforce CLI plugin using sf dev generate before November 2023, the command generates plugins that use CommonJS modules. After November 2023, sf dev generate generates plugins that use ESM.

Salesforce continues to support CommonJS-based plugins in sf. But because the Node.js ecosystem is moving towards ESM, we recommend that you migrate your plugin to ESM. This way you can take advantage of the latest and greatest updates.

There are two main benefits to using ESM.

Dependencies imports are more efficient, and thus command executions are faster.
You can seamlessly continue to use the latest versions of dependencies that have migrated to ESM. For instance, chalk, got, and inquirer have all migrated to ESM. While you can continue to use these dependencies in CommonJS, you must change your imports of them to dynamic imports (for example, await import('chalk')), but they can't be top-level imports. Migrating your plugin to ESM allows you to stay on the latest without the inconvenience of dynamic imports.

But here's the caveat: Currently, linked ESM plugins aren't auto compiled at runtime. This is a limitation with the current state of ESM and Node.js. We hope to support this again in the future. But in the meantime, you must either run yarn compile on your plugin before linking it. Or, if you're actively developing a plugin, open a separate terminal to your plugin directory and run yarn tsc -w to immediately compile your changes as you save them.

Follow these steps to migrate your plugin to ESM.

The type key of your plugin's package.json file tells Node.js what type of modules your plugin is using. Without this key, Node.js assumes your plugin is CommonJS. Here's a pared-down example from plugin-org:

Your plugin's tsconfig.json file must now extend either @salesforce/dev-config/tsconfig-esm or @salesforce/dev-config/tsconfig-strict-esm. The strict variant adds strict: true to the TSConfig file, which is what we recommended, and is what Salesforce CLI itself uses. See plugin-org for an example.

Likewise, test/tsconfig.json must now extend @salesforce/dev-config/tsconfig-test-esm or @salesforce/dev-config/tsconfig-test-strict-esm. Here's how plugin-org does it.

Replace the contents of your plugin's bin directory with these files.

In ESM, all local imports must have the .js extension. For example:

Before:

After:

If you're importing from an index file, you must now explicitly specify index.js.

Before:

After:

ESM doesn't support using require(), so you must replace it with import. For example:

Before:

After:

If you absolutely need require, because maybe you need require.resolve, then you can create it like this:

For example:

Before:

After:

ESM doesn't support the __dirname and __filename variables. You most likely use them when instantiating Messages. Use the fileUrlToPath(import.meta.url) method instead. Here's a __dirname example:

Replace __filename with just fileURLToPath(import.meta.url).

If you used the dev generate plugin command to generate your plugin, then the src/index.ts file probably looks like this:

Update the file to look like this:

Rename config files such as commitlint.config.js to commitlint.config.cjs. Alternatively, migrate the files to ESM.

Add this to your .mocharc.json file so that mocha can run ESM:

The sinon library can stub ESM only if the imports in the source code match the imports used in the tests.

For example, if you want to stub writeFileSync from fs, then make sure that the source file and test file import the fs module in the same way.

The first example isn't stubbable because the source file uses a deconstructed import, but the test file doesn't. The second example fixes this by using the same import fs from 'node:fs' in both files.

❌ Not stubbable

✅ Stubbable