Mix CommonJS and ES6 modules in same project

I'm NOT a javascript person so I humbly accept any corrections here. I had the same question and was surprised at the lack of clarity on it in the usual places.

The confusing thing is that where you actually mix these, there are two files (modules) involved - the importing file and the imported file. So, if your index (or other entry point) file is ES-based and it needs to include a CommonJS file - which format do you use? For the most common basic case of importing CommonJS files/libraries into a modern ES6 app):

1. Do NOT specify type:module in package.json (this leaves the default as CommonJS)
2. File Extensions: Use the .mjs extension for all of the ES6 files. Use (or leave) the older .js extension for all of the CommonJS files
3. Export statements: Use export keyword (e.g."export functionName") for all ES6 exports - use "module.exports" for all CommonJS exports
4. Import statements: use the importing syntax for whatever file type you are importing to. For example, if you are in an ES6 module file and need to bring in a CommonJS file, use the ES6 import syntax

For node.js 16.18.0

package.json

{
  "name": "es6_commonjs",
  "version": "1.0.0",
  "description": "",
  "type": "module",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

book.cjs

module.exports = class Book {
    constructor(name) {
        this.name = name;
    }
}

student.js

export class Student {
    constructor(name) {
        this.name = name;
    }
}

app.js

import { Student } from "./student.js";
import Book from './book.cjs';

const student = new Student('Name');
console.log(student);

const book = new Book('Name');
console.log(book);

run command node ./app.js

result:

Student { name: 'Name' }
Book { name: 'Name' }

Here's how to deal with ES6 in a CommonJS project:

const thing=await import('thing'); //remember to add "async" to the containing function definition

Nothing else is needed. Also, nothing bad will happen. Everything will just work. This should have been the only answer.

I update the NodeJs documentation link: https://nodejs.org/api/packages.html#determining-module-system

The rules for dual CommonJS/ES module packages are well explained...

The simple way to make this work (as already answered by @tqwhite) is to use dynamic imports. This poses some challenges because:

• we can not await at the top level (yet), so we need to create an async function around it
• we might need to use the imported module in several places and importing multiple times might break things

Here is a slightly improved version that can work in a wide range of use cases

let thiing;
const initialize = async () => {
  if (!thing) thing = await import('thing');
  return thing;
}
// ...
// use inside async function
await initialize();
thing.someFunction();
// use with promise chaining
initialize().then(thing => thing.someFunction());
// use with React => your component will know when when it's safe ot use 'thing'
const [initialized, setInitialized] = React.useState(false);
React.useEffect(() => {
  initialize().then(() => setInitialized(true));
}, [])

Important: if you do use Babel and preset-env, it is important to exclude the proposal-dynamic-import plugin or it will break the dynamic import.

I wanted to give a full example based on @tqwhite's answer. I have a simple legacy javascript code base and want to use the ES6 based "svgcanvas" library. This is how I import it in my html file:

<script type="module">
// es6 modules javascript

async function loadEsModules() {
    const module = await import('./js/svgcanvas.js');
    window.SvgCanvas = module.default;
}
await loadEsModules();

</script>

<script>
    //legacy javascript
    let editor = new SvgCanvas(...)
</script>