Change to ESM (ECMAScript module)

[shaunanoordin]

Project Improvement / Code Standardisation

Suggestion as of f797e52

We should change this project to an ESM format. This can be done by adding { "type": "module" } to package.json (docs), which tells Node.js to treat our project as an ECMAScript module, instead of the default CommonJS module.

// package.json
{
  "type": "module",
  ...
}

Q: is it essential?
A: nope!

Q: why do this?
A: code standardisation.

Q: what's the catch?
A: it kinda breaks the current builds.

Things To Do

Step 1: Add { "type": "module" } to package.json

Step 2: jest.config.js

• Change module.exports = config to export default config
• Check that it works: run npm run test

Step 3: webpack.dev.js and webpack.prod.js

• Change module.exports = { ... } to const config = { ... } plus export default config
• Change const whatever = require('whatever') to import whatever from 'whatever'
• Add missing __dirname variable
  • Node.js bakes __dirname into CommonJS modules but not ESM (??), so we'll need to set up that var somehow.
  • Add this to the code:

    import * as url from 'url'
    // const __filename = url.fileURLToPath(import.meta.url)  // We don't need this, but I thought it's neat to have
    const __dirname = url.fileURLToPath(new URL('.', import.meta.url))
    

  • Additional reading: (blog post with solution and way more info) (alt stackoverflow solution) (MDN notes on import.meta)
• ❗ Find replacement for require.resolve()
  • 2023.08.28 Roadblock: I have no idea how to do this
  • In theory we could use import.meta.resolve, but as of Node 20, this is experimental as heck
  • Additional reading: (possible solution on stackoverflow?) (Node.js's implementation of import.meta.resolve())
• Check that it works pt 1: run npm start and browse local.zooniverse.org:8080
• Check that it works pt 2: npm run build

Status

Low priority for the moment, but if we can solve those gotchas, it'd be a nice improvement to have to the code. Thanks to Jim for pointing out why running Jest requires module.exports = ... in the config instead of export ..., in PR 163's discussions

[eatyourgreens]

Where you're currently doing something like:

import { subjects } from '@zooniverse/panoptes-js'

you're importing the entire client object, then destructuring client.subjects. That means that you're loading in dependencies that you don't need, like jose.

You should be able to get around this by importing just the object that you need. Something like this:

import subjects from '@zooniverse/panoptes-js/resources/subjects'

[eatyourgreens]

Node's documentation on interoperability with CommonJS, including __dirname and require.resolve.

https://nodejs.org/api/esm.html#differences-between-es-modules-and-commonjs

Also worth noting that you can rename the webpack config to .cjs if you need to use require.

[eatyourgreens]

If you're building a new package from scratch, then Rollup might be a better choice than Webpack, for bundling an ES module.