1. EcmaScript

For years, Node.js has been on a on-going transition from CommonJS (CJS) to EcmaScript Modules (ESM). While ESM has already been adopted by all major browsers, there are still many NPM packages that are not fully compatible with the standard. The following describes the limbo caused by this "on-going transition".
  • • CJS uses and while ESM uses and . These are fundamentally incompatible at the syntax level.
  • • CJS is synchronous and ESM is asynchronous. Code that assumes synchronous module loading can break under ESM.
  • • It is not possible to import ESM modules into CJS. While it is possible to import CJS modules into ESM, it's more of a backwards compatible feature for now, not a long-term solution.
  • • ESM has this wierd rule of adding the extension to all imports that dont have a package.json export rule. This gets even more confusing when developing in Typescript.
  • • ESM cannot import files.
  • • Bundlers blur the line between CJS and ESM making it more confusing to understand the differences and fully transition to ESM.
While Stackpress publishes in both ESM and CJS, it hasn't been an easy road marrying the two. The following explains our findings while developing and testing the framework.
  • • Stackpress distributables have both CJS and ESM, because it is unclear which one works better depending on the end use case.
  • • You can setup your project as CJS, if your project is not using the default Reactus view engine because Reactus uses Vite to build the server and client views that can be used on a production environment. And, because Vite only generates ESM, it's generally better to setup your project root as ESM.
  • • Projects using Stackpress with the latest Vercel needs to be strictly ESM.

1.1. Configure Package

From the project root create or update the package.json file with the following configuration.
❐ Copy
To make a project ESM, you need to set the property to . This tells Node.js to treat all .js files in the project as ESM. The provided in the example are the minimal provisions needed by Stackpress to complete this tutorial.

1.2. Configure Typescript

Next, from the project root create or update the tsconfig.json file with the following configuration.
❐ Copy
Stackpress has a general ESM configuration at stackpress/tsconfig/esm. Adding the value emphasizes the use of ESM rules in Typescript.

1.3. Check Point

In case you got lost along the way, here is a checkpoint of what your project should look like.
PROJECT
package.json
tsconfig.json
package.json
tsconfig.json
❐ Copy
Setting your project like this, sets your project to a strict ESM standard and provisions packages that will be used in later tutorials. The next section will cover setting up your project using a plugin architecture.