ESM rollout plan

[bpasero]

Refs: #160416

Synopsis

We are now able to build a ESM variant of VS Code with a build flag that will run a migration script (node migrate.mjs). This script converts src into a ESM compatible format, specifically:

• Imports are relative with a .js suffix (for example import { untildify } from '../../../../base/common/labels.js';)
• CSS sees the vs/css! loader plugin removed (for example import './media/anythingQuickAccess.css';)
• everything in a // ESM-comment-begin / // ESM-comment-end block gets commented out
• everything in a // ESM-uncomment-begin / // ESM-uncomment-end block gets commented in
• a package.json with {"type": "module"} is added to src folder to mark it as ESM (this is temporary)
• tsconfig.base.json compiler options are changed to have es2022 as module

The migration ends up with around 3862 outgoing changes that we would like to bring to main in a single commit to mark the beginning of ESM and end of AMD.

Note: these changes are purely transformations, they are not removing any AMD related pieces from our source tree.

AMD Compatibility

We are aware that this transition comes with risks, so we will have support to convert back from ESM to AMD with a new migration script that we can run on-demand. The idea is that we should always be able to build the current state of main in AMD to have a recovery option, especially when we come to release this to stable.

This script will:

• preserve the relative imports but remove the .js suffix which our AMD loader does not understand
• add back vs/css! to CSS imports
• toggle the ESM related comments back
• remove the src/package.json that was added
• sets the tsconfig.base.json back to amd as module

Web: ESM-to-AMD Bridge

We are also aware that upstream components depend on our web standalone deliverable where moving to ESM is not an option right now. For that purpose we will ship our web standalone bits in an AMD compatible way. We will host this solution on vscode.dev for selfhosting.

Impact on PRs and Branches

Once the migration has run on main, we will enforce certain ESM related rules via ESLint, for example all imports have to be relative and have a file extension.

All opened PRs and branches will still run in the old format. We have to manually go into these and update them with main to get the ESLint checks in place so that a transformation can be done on the PRs as needed.

Monaco Editor

We ship the Monaco editor as AMD and ESM already for a long time. We should be able to ship the Monaco editor in a AMD compatible way, even if ESM is our only choice by providing a wrapper script. We can also decide to discontinue support for AMD and only ship a ESM variant (aka Monaco Editor 1.0).

Timeline

Our goal is to ship ESM enabled insiders in September and stable in October. Our goal is to do this with minimal disruption of engineering.

• Fri. 08-30
  • we have branched off release/1.93 but main will remain closed for the ESM merge
  • 1 commit with >3k changes lands in main enabling ESM and new ESLint rules
  • main is declared open for September work
• Wed. 09-04 / Thu. 09-05
  • we release stable 1.93.x as AMD to the world
  • we release insiders 1.94.x as ESM to the world
    • insiders.vscode.dev will transition to use the ESM-to-AMD bridge solution
    • github.dev starts to use the ESM-to-AMD variant as well for insiders but should work towards only consuming ESM
• Wed. 10-02 / Thu. 10-03
  • we release stable 1.94.x as ESM to the world
  • vscode.dev continues to use the ESM-to-AMD bridge solution
• October
  • we monitor incoming issues and decide if a AMD recovery is needed (we will try to avoid this at all cost)
  • we begin removing AMD traces from our sources and remove the option to build VS Code as AMD
• November
  •  depending on upstream components, we begin to remove the ESM-to-AMD bridge option for web and convert all web services to use pure ESM solution

[bpasero]

ESM code changes landed in main via #227184