Home Arrow Icon Knowledge base Arrow Icon Global Arrow Icon How does Vite convert CommonJS dependencies to ESM during development
    Vite CommonJS to ESM conversion esbuild dependency pre-bundling performance optimization monorepo linked dependencies


How does Vite convert CommonJS dependencies to ESM during development


Vite handles the conversion of CommonJS dependencies to ESM during development in the following way:

1. Automatic Dependency Discovery:
- When Vite starts, it crawls your source code to automatically discover dependency imports (bare imports that expect to be resolved from `node_modules`).

2. Pre-Bundling with `esbuild`:
- Vite uses the `esbuild` tool to pre-bundle the discovered dependencies. This process includes converting CommonJS and UMD modules to ESM.

3. CommonJS to ESM Conversion:
- During the pre-bundling process, Vite performs "smart import analysis" to ensure that named imports to CommonJS modules work as expected, even if the exports are dynamically assigned (e.g., in the case of React).

- For example, the following code will work as expected:

javascript
     import React, { useState } from 'react';
     

- Vite achieves this by converting the CommonJS module to an ESM module that preserves the expected behavior.

4. Performance Optimization:
- Vite also optimizes the performance of the pre-bundled dependencies by converting ESM dependencies with many internal modules into a single module. This reduces the number of HTTP requests during page load, improving the overall performance.

5. Handling Updates:
- After the server has started, if a new dependency import is encountered that isn't already in the cache, Vite will re-run the dependency bundling process and reload the page if needed.

6. Monorepo and Linked Dependencies:
- In a monorepo setup, Vite automatically detects dependencies that are not resolved from `node_modules` and treats the linked dependencies as source code. It will not attempt to bundle the linked dependencies, and will analyze the linked dependency's dependency list instead.
- If the linked dependency is not exported as ESM, you can add it to the `optimizeDeps.include` and `build.commonjsOptions.include` options in your Vite configuration.

By leveraging `esbuild` and its smart import analysis, Vite is able to efficiently convert CommonJS dependencies to ESM during the development phase, ensuring a seamless experience for developers working with both ESM and CommonJS modules.

Citations:
[1] https://github.com/vitejs/vite/discussions/8726
[2] https://www.npmjs.com/package/%40originjs/vite-plugin-commonjs
[3] https://vitejs.dev/guide/dep-pre-bundling
[4] https://github.com/vitejs/vite/issues/2652
[5] https://www.npmjs.com/package/vite-plugin-esmodule