How can I ensure compatibility between ESM and CommonJS in Vite

Automatic Conversion During Development

During development, Vite automatically converts CommonJS and UMD dependencies to ESM using `esbuild`. This process includes:

- Crawling the source code to discover dependency imports[1][4]
- Pre-bundling the discovered dependencies with `esbuild`[2][4]
- Performing "smart import analysis" to ensure named imports from CommonJS modules work as expected[2][4]

For example, the following import works seamlessly:

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

Handling Mixed ESM and CJS Dependencies

When dealing with mixed ESM and CommonJS dependencies, especially those included from `node_modules`, Vite may not correctly resolve the dependency chains[5]. To mitigate this:

- Use the `optimizeDeps.include` option to manually specify which dependencies should be included in the optimization process[2][4]
- Add the dependencies to `optimizeDeps.include` and `build.commonjsOptions.include` in your Vite configuration[4]

javascript
export default defineConfig({
  optimizeDeps: {
    include: ['linked-dep'],
  },
  build: {
    commonjsOptions: {
      include: [/linked-dep/, /node_modules/],
    },
  },
})

Production Builds

In production, Vite switches to using `@rollup/plugin-commonjs` for handling CommonJS dependencies[1][4]. This ensures that the build process aligns with the requirements of production environments while still optimizing for performance.

By leveraging these strategies, Vite effectively manages the compatibility between ESM and CommonJS dependencies, ensuring a smooth development experience and optimized production builds.