DEV Community: Jinjiang

Understanding how Vite deals with your node_modules

Jinjiang — Mon, 21 Apr 2025 02:20:48 +0000

This is an article about Vite and its features which are related to the node_modules of your projects.

Background

As a Vite user so far, I guess there might be some questions in your head like:

Have you ever been confused about all the Vite configs for your project dependencies?
Have you ever wondered how Vite deals with it?
Have you ever tried to build a tool based on Vite and found it difficult to deal with the node_modules directory?
Have you ever seen a long error message in the browser or terminal that you have no idea what it means?
Does a CJS (CommonJS) dependency work in all the Vite cases?
Does a dependency in the normal SPA (Single Page Application) mode and the SSR (Server Side Rendering) mode work the same way?

In this article, we will explore how Vite deals with them in different modes and scenarios.

What is Vite?

Vite is a modern frontend build tool that provides a fast and efficient development experience. It uses native ES modules in the browser for development, and bundles your code by Rollup for production. Today, Vite has dominated the frontend world as the most popular build tool. Even It has become the de facto standard for modern frontend development.

"Every frontend project has a messy `node_modules` folder"

One of the most magical things about Vite is that it can work with your node_modules folder pretty well.

We all know that in modern JavaScript ecosystem, the node_modules folder is a big trouble. It's large, messy, and difficult to manage. It contains all kinds of dependencies, including CJS (CommonJS), ESM (ECMAScript Modules), UMD (Universal Module Definition), and even some non-JavaScript files like CSS, images, etc. It's a nightmare for a build tool to deal with.

And one of its biggest challenges is to deal with the CJS code. We all know that Vite is a ESM-first build tool. The whole idea of Vite is to use native ES modules in the browser for development. However, in the real world, CJS is still everywhere, and it's not supported in the browser.

However, Vite can handle all the challenges above. Not only handling it precisely, but also performantly. In most of the time, you don't even have to think about it. It just works by default.

But I have to say. It's just most of the time. There are still some edge cases that you have to take care of manually. And this is what this article is discussing.

How did this article come about?

As part of my job, recently I'm working on integrating Vite (also Vitest) into a dev tool called Bit, which originally uses webpack in most of the cases. Basically, Bit is a component-driven development tool for various frontend frameworks and Node.js. In Bit, everything is a component and eventually consumed as an npm package. So technically, you would deal with all kinds of components as packages in your node_modules folder, whatever they are in CJS or ESM, need to be further transformed or not.

During the integration, I've met a lot of cases which need extra attentions. I've also had a lot of discussions with the Vite/Vitest team via GitHub issues/PRs/discussions and a little more Discord chats. I'm glad most of them have been eventually figured out. And I also learned a lot of interesting details.

I'm thinking, maybe I can write something down, to help more people who also have the same issues, or just want to know more about Vite. So here we are.

To be noticed #1 that all the demos have been snapshotted step-by-step on this GitHub repo Jinjiang/reproduction - branch: vite-deps-demo-2025. You can always check it out there. At this moment, the latest Vite version is v6.2.0.

To be noticed #2 that in the future Vite will integrate Rolldown as its new core. Technically their config would be different, more precisely saying, simpler.

Let's begin.

Basic usage

Setup

Let's start from the official guide to create a React project:

BTW, feel free to choose your favorite package manager. Here we use pnpm as an example.

$ pnpm create vite
│
◇  Project name:
│  vite-project
│
◇  Select a framework:
│  React
│
◇  Select a variant:
│  TypeScript
│
◇  Scaffolding project in /home/jinjiang/Developer/vite-project...
│
└  Done. Now run:

  cd vite-project
  pnpm install
  pnpm run dev

Snapshot of the demo project #1 - basic setup

After the installation, we can see the node_modules folder is created with all the dependencies you need:

cd vite-project
pnpm install

Let's run the project:

$ pnpm run dev

  VITE v6.2.1  ready in 180 ms

  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h + enter to show help

Cool, now you can see the React project is running on http://localhost:5173/.

To better understand how it works, let's introduce 2 common inspection skills: node_modules/.vite folder and the "Network" panel in browser DevTools.

How to inspect 1: the `node_modules/.vite/deps` folder

First, you may have found there is a node_modules/.vite folder created with some files like this:

$ tree node_modules/.vite
node_modules/.vite
└── deps
    ├── _metadata.json
    ├── chunk-ENSPOGDT.js
    ├── chunk-ENSPOGDT.js.map
    ├── chunk-RO7GY43I.js
    ├── chunk-RO7GY43I.js.map
    ├── package.json
    ├── react-dom.js
    ├── react-dom.js.map
    ├── react-dom_client.js
    ├── react-dom_client.js.map
    ├── react.js
    ├── react.js.map
    ├── react_jsx-dev-runtime.js
    ├── react_jsx-dev-runtime.js.map
    ├── react_jsx-runtime.js
    └── react_jsx-runtime.js.map

1 directory, 16 files

This folder is created by Vite to store some temporary files. And it's easy to guess that the deps subfolder is used to store something related to the dependencies. We will jump into the details later.

How to inspect 2: the "Network" panel in browser DevTools

Second, open the browser DevTools and check the "Network" panel. You will see all the requests to the Vite dev server. And some of them point to this node_modules/.vite/deps folder.

For example, the source file src/main.tsx:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.tsx'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

is eventually requested into the browser roughly like (after some beautification):

// 'react/jsx-dev-runtime' transformed from jsx
import react_jsxDevRuntime from "/node_modules/.vite/deps/react_jsx-dev-runtime.js?v=<hash>";
// originally 'react'
import react from "/node_modules/.vite/deps/react.js?v=<hash>";
// originally 'react-dom/client'
import reactDom_client from "/node_modules/.vite/deps/react-dom_client.js?v=<hash>";

import "/src/index.css";
import App from "/src/App.tsx";

const jsxDEV = react_jsxDevRuntime["jsxDEV"];
const StrictMode = react["StrictMode"];
const createRoot = reactDom_client["createRoot"];

createRoot(document.getElementById("root")).render(
  jsxDEV(StrictMode, {
    children: jsxDEV(App, {}, void 0, false, {...}, this)
  }, void 0, false, {...}, this)
);

As you can see, all the package imports like import React from 'react' or import { createRoot } from 'react-dom/client' are resolved into a path to node_modules/.vite/deps/xxx.

A small recap

To inspect the dependencies, you can either check the code in node_modules/.vite/deps folder, or check the "Network" panel in browser DevTools. They usually just match each other.

This is the first Vite-magical thing we'd like to discover. More magically, whatever the source of a package import is in CJS or ESM, the eventual requested content will always be in ESM.

A simple case with CJS and ESM

Here, both react and react-dom are "bad" examples which are still CJS in 2025, but good examples to show how Vite deals with CJS package imports. To better understand how Vite deals with CJS and ESM package imports in a simpler way, let's create a new package:

mkdir node_modules/foo
touch node_modules/foo/package.json
touch node_modules/foo/foo-cjs.cjs
touch node_modules/foo/foo-esm.mjs

In node_modules/foo/package.json:

  {
    "name": "foo"
  }

In node_modules/foo/foo-cjs.cjs:

  exports.foo = 'foo-cjs'

In node_modules/foo/foo-esm.mjs:

  export const foo = 'foo-esm'

This will create a package named foo with 2 files:

foo-cjs.cjs in CJS and
foo-esm.mjs in ESM.

Then add 2 imports into src/main.tsx:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'

// 2 new imports
import { foo as fooCjs } from 'foo/foo-cjs.cjs'
import { foo as fooEsm } from 'foo/foo-esm.mjs'

import './index.css'
import App from './App.tsx'

console.log({ fooCjs, fooEsm });

...

Snapshot of the demo project #2 - a case with both CJS and ESM

Restart the Vite dev server, then you will find these imports have also been resolved into a path like /node_modules/.vite/deps/foo-esm.js?v=<hash> but in different ways:

// first new import
import foo_fooCjs from "/node_modules/.vite/deps/foo_foo-cjs__cjs.js?v=<hash>";
const fooCjs = foo_fooCjs["foo"];

// second new import
import { foo as fooEsm } from "/node_modules/.vite/deps/foo_foo-esm__mjs.js?v=<hash>";

At the same time, the eventual content of these 2 requested files are all in ESM:

node_modules/.vite/deps/foo_foo-cjs__cjs.js:

  import { __commonJS } from "/node_modules/.vite/deps/chunk-<hash1>.js?v=<hash2>";

  // node_modules/foo/foo-cjs.cjs
  var require_foo_cjs = __commonJS({
    "node_modules/foo/foo-cjs.cjs"(exports) {
      exports.foo = "foo-cjs";
    }
  });
  export default require_foo_cjs();

it imports a builtin helper __commonJS to wrap the CJS source code into ESM.

node_modules/.vite/deps/foo_foo-esm__mjs.js:

  import "/node_modules/.vite/deps/chunk-<hash1>.js?v=<hash2>";

  // node_modules/foo/foo-esm.mjs
  var foo = "foo-esm";
  export {
    foo
  };

it's almost the same as the original ESM source code.

And the __commonJS() helper looks like this:

node_modules/.vite/deps/chunk-<hash1>.js:

  var __getOwnPropNames = Object.getOwnPropertyNames;
  var __commonJS = (cb, mod) => function __require() {
      return mod || (0,
      cb[__getOwnPropNames(cb)[0]])((mod = {
          exports: {}
      }).exports, mod),
      mod.exports;
  }
  ;
  export { __commonJS };

So overall:

Vite can recognize whether a package import is in CJS or in ESM, not only per package but also per file, which quite makes sense.
For ESM package import, it's straightforward, nothing special to do.
For CJS package import (with exports.xxx in it), Vite will transform the package code (node_module/foo/foo-cjs.cjs) into ESM via default export. And it will be eventually imported as default in the importer file (src/main.tsx).

Please notice that, even though your CJS package import is in exports.xxx which is much closer to named exports in ESM, Vite will always transform it into default export in ESM. That is unituitive but makes sense because in CJS the exports can by complex and dynamic which are difficult to predict into static named imports, while putting all of them into a default export as a deal simplifies the transformation process. And later, we still have chance to distinguish between exports.foo = xxx and module.exports = xxx by a flag __esModule.

The case with `module.exports = xxx` in CJS

At last, you might also be curious about another kind of CJS package import module.exports = xxx.

Great question! Let's try it now:

touch node_modules/foo/foo-cjs-module.cjs

In node_modules/foo/foo-cjs-module.cjs:

  module.exports = 'foo-cjs-module'

And then add the import into src/main.tsx:

  import fooCjsModule from 'foo/foo-cjs-module.cjs'

Snapshot of the demo project #3 - module.exports in CJS

Restart the Vite server, now you will find the importer in the eventual requested content:

import fooImport from "/node_modules/.vite/deps/foo_foo-cjs-module__cjs.js?v=<hash>";
const fooCjsModule = fooImport.__esModule ? fooImport.default : fooImport;

That means, Vite will try to access the default property of the CJS package import if there is a __esModule flag in it. Otherwise, it will use the import itself directly.

and the imported file looks like:

node_modules/.vite/deps/foo_foo-cjs-module__cjs.js:

  import { __commonJS } from "/node_modules/.vite/deps/chunk-<hash1>.js?v=<hash2>";

  // node_modules/foo/foo-cjs-module.cjs
  var require_foo_cjs_module = __commonJS({
    "node_modules/foo/foo-cjs-module.cjs"(exports, module) {
      module.exports = "foo-cjs-module";
    }
  });
  export default require_foo_cjs_module();

Actually, even for the case you use exports.xxx in CJS package import, the resolved importing code would be in the same logic:

import fooCjsAll from 'foo/foo-cjs.cjs'

will be resolved into:

import fooImport from "/node_modules/.vite/deps/foo_foo-cjs__cjs.js?v=<hash>";
const fooCjs = fooImport.__esModule ? fooImport.default : fooImport;
// `fooCjs.foo` will be 'foo-cjs'

which also works as expected.

Snapshot of the demo project #4 - default import with exports.xxx in CJS

A small recap

All the package imports will be resolved into imports to a path like /node_modules/.vite/deps/xxx.
For ESM package import, it's more straightforward, almost nothing extra.
For CJS package import, Vite will transform the package code into ESM with default export. And eventually, the consuming import code will be pointed to the default import as well.

The code inside node_modules/.vite/deps/ is generated by Vite which we call "dependency pre-bundling" or "dependency optimization". Next, let's dive into it and see how to customize it for your own needs.

Custom Dependency Pre-bundling

What is `vite optimize` and `optimizeDeps` config in Vite?

You may have noticed that, on Vite official docs, there is a vite optimize command. The job is actually part of what Vite dev server does. It can figure out all the needed dependencies in node_modules and then "pre-bundles" them into node_modules/.vite/deps/. Then all the package imports like react can be resolved to the new optimized imports like node_modules/.vite/deps/react.js instead of the original one.

The rough steps of this "optimize" process are:

Traverse all the source code from the entry file of your project (usually it's the index.html) and find out all the imports to node_modules. and then draw a "optimization boundary" around them.
- e.g. in the project above, the analyzation prcess would be:
  - index.html: imports src/main.tsx
  - src/main.tsx: imports react/jsx-dev-runtime (boundary), react (boundary), react-dom/client (boundary), ./App.tsx, ./index.css, foo/foo-cjs.cjs (boundary), foo/foo-esm.mjs (boundary), foo/foo-cjs-module.cjs (boundary)
  - ./App.tsx: imports react/jsx-dev-runtime (boundary), react (boundary), ./assets/react.svg, /vite.svg, ./App.css
  - ./index.css: no more imports
  - ./App.css: no more imports
  - ./assets/react.svg: no more imports
  - ./vite.svg: no more imports
- Then the full "optimization boundary" would be:
  - react/jsx-dev-runtime (invisible from source code)
  - react (invisible from source code)
  - react-dom/client
  - foo/foo-cjs.cjs
  - foo/foo-esm.mjs
  - foo/foo-cjs-module.cjs
Pre-bundle all the dependencies on the "optimization boundary" list into node_modules/.vite/deps/ folder. This step is done by esbuild.

After those, we are able to replace all the package imports into the optimized imports.

You usually don't have to do this because Vite dev server will do it automatically for you. Just in case you need to force it to be done or rebuilt, you can also run vite --force to force the rebuild.

Why we need dependency optimization?

In short:

To support CJS package imports in the browser.
To reduce the number of requests to the server for better performance.

What is `optimizeDeps` config in Vite?

Now, it's time to understand why we have a optimizeDeps config in Vite. This config is designed to give you more control over the "optimization boundary" settings. For example, you can exclude some packages from the boundary, or include more packages into the boundary.

This is very useful when Vite somehow is not able to do the analyzation correctly, or you want to skip some packages from the pre-bundling process for special reasons. For example, you may want to change the content of a certain package in a special case. Then, it's not recommended to pre-bundle it. Because once you have changed the content, the whole pre-bundle needs to be rebuilt, not to mention Vite may not rebuild it immediately during the dev server running. Even when you restart it, Vite sometimes can't detect the changes. So you have to force the rebuild manually to make it right.

Back to the demo project, first of all, let's disable the automatic analyzation by setting optimizeDeps.noDiscovery to true in vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  optimizeDeps: {
    noDiscovery: true,
  },
  plugins: [
    react(),
  ],
})

Snapshot of the demo project #5 - optimizeDeps.noDiscovery

Then restart the Vite dev server by pnpm run dev --force. You will see your web app not working anymore with a browser runtime error:

Uncaught SyntaxError: The requested module '/node_modules/.pnpm/react-dom@19.0.0_react@19.0.0/node_modules/react-dom/client.js?v=4eaecffa' does not provide an export named 'createRoot'

If you inspect the "Network" panel now, you will find the package imports like import { createRoot } from 'react-dom/client' in src/main.tsx are not resolved into node_modules/.vite/deps/xxx anymore. They will be pointed to the original package imports:

import { createRoot } from "/node_modules/.pnpm/react-dom@19.0.0_react@19.0.0/node_modules/react-dom/client.js?v=<hash>";
import { foo as fooCjs } from "/node_modules/foo/foo-cjs.cjs?import&v=<hash>";
import { foo as fooEsm } from "/node_modules/foo/foo-esm.mjs?v=<hash>";
import fooCjsAll from "/node_modules/foo/foo-cjs.cjs?import&v=<hash>";
import fooCjsModule from "/node_modules/foo/foo-cjs-module.cjs?import&v=<hash>";

And You can also see the eventual content of react-dom/client.js is in CJS which doesn't work in browser. Now we know that Vite itself can't deal with CJS code directly without the "optimization".

To make the app works again, let's add all the package imports of the "optimization boundary" into the optimizeDeps.include config:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  optimizeDeps: {
    noDiscovery: true,
    include: [
      `react-dom/client`,
      'foo/foo-cjs.cjs',
      'foo/foo-esm.mjs',
      'foo/foo-cjs-module.cjs',
    ],
  },
  plugins: [
    react(),
  ],
})

Snapshot of the demo project #6 - fix with optimizeDeps.include

Now, all the package imports are resolved back to node_modules/.vite/deps. And the web app is working again.

Among these optimizeDeps.include items, you actually can remove the ESM package imports like foo/foo-esm.mjs because the browser can work with them natively without the optimization:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  optimizeDeps: {
    noDiscovery: true,
    include: [
      `react-dom/client`,
      'foo/foo-cjs.cjs',
      // 'foo/foo-esm.mjs',
      'foo/foo-cjs-module.cjs',
    ],
  },
  plugins: [
    react(),
  ],
})

Snapshot of the demo project #7 - remove ESM from optimizeDeps.include

Another way to achieve the same effect is to remove noDiscovery and include fields to turn all of them on but exclude the ESM package imports from the "optimization boundary" by setting optimizeDeps.exclude:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  optimizeDeps: {
    exclude: [
      'foo/foo-esm.mjs',
    ],
  },
  plugins: [
    react(),
  ],
})

Snapshot of the demo project #8 - equivalent optimizeDeps.exclude

This also means, in node_modules, only ESM content can be technically modified without the pre-bundle rebuild. Otherwise, all the code changes in node_modules need a forced pre-bundle rebuild to make it works. However, to support the advanced features like HMR (Hot Module Replacement), you need something else. This is framework-specific and won't be covered in this article.

A small recap:

By default, Vite will automatically analyze the project and draw a "optimization boundary" around all the package imports. The "optimization boundary" is used to pre-bundle the dependencies into ESM and put them into node_modules/.vite/deps.
Option optimizeDeps.noDiscovery can be set to disable the default deps analyzation.
Option optimizeDeps.include and optimizeDeps.exclude are used to opt-in/opt-out certain package imports to/from the "optimization boundary".
Command vite optimize and vite --force can be used to do the optimization manually.

And it's easy to get those tips below:

Never exclude CJS package imports.
If you want to include all the dependencies by default and exclude some exceptions, just use optimizeDeps.exclude.
If you want to manually list the "boundary" from zero, use optimizeDeps.noDiscovery + optimizeDeps.include instead.

Advanced case: deep dependencies configuration

Now, let's think about an advanced case: what if I'd like to exclude a package import like foo/foo-esm.mjs but include (optimize) one of its package imports to a deep dependency (in CJS)?

Let's create a deep dependency foo-dep-a with a CJS file foo-dep-a-cjs.cjs:

mkdir node_modules/foo/node_modules
mkdir node_modules/foo/node_modules/foo-dep-a
touch node_modules/foo/node_modules/foo-dep-a/package.json
touch node_modules/foo/node_modules/foo-dep-a/foo-dep-a-cjs.cjs

In node_modules/foo/node_modules/foo-dep-a/package.json:

  {
    "name": "foo-dep-a"
  }

In node_modules/foo/node_modules/foo-dep-a/foo-dep-a-cjs.cjs:

  exports.fooDepA = 'foo-dep-a-cjs'

And then add the import into node_modules/foo/foo-esm.mjs:

  import { fooDepA } from 'foo-dep-a/foo-dep-a-cjs.cjs'
  export const foo = fooDepA

Snapshot of the demo project #9 - a case of deep deps

Restart the server, you will see the browser runtime error when you opt-out foo/foo-esm.mjs since the new CJS file isn't optimized.

To fix it, we can use this syntax to include the deep dependency:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  optimizeDeps: {
    include: [
      'foo > foo-dep-a/foo-dep-a-cjs.cjs',
    ],
    exclude: [
      'foo/foo-esm.mjs',
    ],
  },
  plugins: [react()],
})

Snapshot of the demo project #10 - fix with deep optimizeDeps.include

For the optimizeDeps config, besides noDiscovery, include, and exclude, there are also some other options like entries, esbuildOptions, holdUntilCrawlEnd, needsInterop, etc. You can check the official docs for more details.

Also, to force the pre-bundle rebuild, there is also a config optimizeDeps.force which does the same thing as vite --force. It's very useful for debugging purposes. We will turn it on by default in the following sections.

I guess so far everything is still quite clear and straightforward. And nothing is uncovered from the official docs yet, right? Next, let's dive into the SSR (Server Side Rendering) world. I bet you will find something really interesting and surprising.

Basic SSR usage

The SSR mode will let your project run more logics on the server side, which is quite different from the default (SPA) mode. In short, comparing to SPA, SSR will additionally:

render the app into a html string on the server, and
run most of the code in the server environment like Node.js rather than only in the browser.

This brings more technical challenges, especially when it comes to the node_modules in a mixed CJS and ESM world. Let's see how Vite deals with it.

Setup

First thing first, let's turn this project into a SSR one. For demonstration, we will do it in a minimal way:

Create 2 entries: src/client.tsx and src/server.tsx instead of the original src/main.tsx.
Update index.html to include src/client.tsx instead of src/main.tsx. at the same time, add a placeholder inside the <div id="root"></div> as <div id="root"></div> for the server-rendered content replacement.
Add a run.mjs file to run the whole service.
Add a dev:ssr npm scripts in package.json with node ./run.mjs.
And don't forget to install express and compression which are used in run.mjs.

Some particular file changes are:

src/client.tsx:

  import { createRoot, hydrateRoot } from 'react-dom/client';
  import './index.css'
  import App from './App';

  const root = document.getElementById('root');

  if (import.meta.env.SSR) {
    hydrateRoot(root!, (<App />));
  }
  else {
    createRoot(root!).render(<App />);
  }

src/server.tsx:

  import { renderToString } from "react-dom/server";
  import App from './App';

  export const render = async () =>
    renderToString(<App />);

run.mjs:

  import { readFileSync } from "node:fs";
  import express from "express";
  import compression from 'compression'
  import { createServer } from "vite";

  const PORT = 5173;

  // create Vite dev server in middleware mode
  const devServer = await createServer({
    server: { middlewareMode: true },
    appType: "custom",
  });

  // create the main server with an express app
  const app = express();
  app.use(compression());
  app.use(devServer.middlewares);

  // handle all the requests with the Vite dev server
  app.use("/", async (req, res, next) => {
    const url = req.originalUrl;

    try {
      // 1. get the index.html template
      // 2. transform the template with some necessary setup
      // 3. render the app into a string
      // 4. replace the final html with the rendered app string
      const template = readFileSync('./index.html', "utf-8");
      const tranformedTemplate = await devServer.transformIndexHtml(url, template);
      const { render } = await devServer.ssrLoadModule('./src/server.tsx');
      const appHtml = await render();
      const html = tranformedTemplate.replace(`<!--ssr-outlet-->`, appHtml);
      res.statusCode = 200;
      res.setHeader("Content-Type", "text/html");
      res.end(html);
    } catch (error) {
      next(error);
    }
  });

  // listen to the port
  app.listen(PORT, () => {
    console.log(`Server running on http://localhost:${PORT}`);
  });

Snapshot of the demo project #11 - SSR setup

Now you can run the project with either pnpm run dev or pnpm run dev:ssr. It will run the web app on http://localhost:5173 in normal (SPA) or SSR mode. And you may already guess out in SSR mode, Vite deals with node_modules far more differently from SPA mode.

What is `ssr.external` and `ssr.noExternal` config in Vite?

Imagine there could be all kinds of content in node_modules which are:

JavaScript files 🆚 other files like CSS files, TypeScript file, JSX files, etc.
in ESM 🆚 in CJS, if it's a JavaScript file.
pure JavaScript code which can be run in the server environment like Node.js (whatever it's in ESM or CJS) 🆚 not (e.g. having CSS imports or assets imports that need further transformation before the running in server).

It's easy to confirm that technically all the pure JavaScript code can be run in the server environment without transformation. But the non-pure JavaScript code have to be transformed beforehand.

With this background, the term "external" is introduced as a special concept in Vite SSR. It has a similar role as optimizeDeps for SPA to draw a "transformation boundary" for the server environment to decide whether the code needs to be transformed beforehand. And of course, their criteria are slightly different:

In SPA mode, the main issue of the package imports is the CJS support. So we have to optimize all the CJS code into ESM beforehand.
In SSR mode, the main issue of the package imports is non-pure JavaScript code. So we have to transform all of them beforehand.

A simple case

As the first example, let's see what if we have a package import which is in ESM but not pure JavaScript. Let's create a package named bar with an ESM file bar-esm.mjs and a CSS file style.css:

mkdir node_modules/bar
touch node_modules/bar/package.json
touch node_modules/bar/bar-esm.mjs
touch node_modules/bar/style.css

In node_modules/bar/package.json:

  {
    "name": "bar"
  }

node_modules/bar/bar-esm.mjs:

  import './style.css'

  export const bar = 'bar'

node_modules/bar/style.css:

  .bar {
    background-color: red;
  }

Then we update src/App.tsx to consume Bar only:

src/App.tsx:

  import { bar } from 'bar/bar-esm.mjs'

  export default function App() {
    return (<h1 className='bar'>{bar}</h1>)
  }

Snapshot of the demo project #12 - a case for SSR externals

Now, if you run the project in SPA mode via pnpm run dev, it works. However, in SSR mode via pnpm run dev:ssr, you will see the error both in browser runtime and server environment (terminal):

00:00:00 AM [vite] (ssr) Error when evaluating SSR module ./src/server.tsx: Unknown file extension ".css" for /xxx/node_modules/bar/style.css

That's because the CSS import wasn't transformed into pure JavaScript beforehand. To do that, we need to add the package import into the ssr.noExternal config in vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  ssr: {
    // ensure all the imports of 'bar' being transformed
    // before running in the server environment
    noExternal: ['bar'],
  },
  plugins: [
    react(),
  ],
})

Snapshot of the demo project #13 - fix with ssr.noExternal

With ths config, all the package imports of bar will be transformed by Vite before running in the server environment. So it works.

How to inspect 3: the module evaluation process in SSR mode

To better understand how it works in SSR mode, honestly, I didn't find an easy way to inspect what happens, especially when it goes to an error. You know what, let's dive into the Vite source in a hard way. Don't be scared, it's not that difficult.

You have 2 options to go:

git clone the Vite source code, install all the dependencies, modify something, rebuild it, and then link it to your project.
a little dirty but quick one, just jump into the node_modules/vite folder and modify the dist code directly.

Whatever you choose, find a class named ESModulesEvaluator:

in source code it's in packages/vite/src/module-runner/esmEvaluator.ts
in node_modules/vite it's in node_modules/vite/dist/node/module-runner.js

In short, this class defines 2 methods runExternalModule() and runInlinedModule() to run the code as "external" or "inlined" ("noExternal") in SSR mode.

The simplified version is below:

// simplified `ESModulesEvaluator`
// - in source code: `packages/vite/src/module-runner/esmEvaluator.ts`
// - in generated code: `node_modules/vite/dist/node/module-runner.js`
export class ESModulesEvaluator implements ModuleEvaluator {
  async runInlinedModule(code: string): Promise<any> {
    const initModule = new AsyncFunction(`"use strict";${code}`)
    await initModule(...)
  }
  runExternalModule(filepath: string): Promise<any> {
    return import(filepath)
  }
}

It's easy to imagine that:

For external packages, it will go to the runExternalModule() method which is the native import statement in server environment like Node.js.
For noExternal packages, it will go to the runInlinedModule() method which is a custom AsyncFunction to run the code, which has an opportunity to be transformed beforehand.

You can add some logs to print the code and filepath in these 2 methods to see both the transformed/resolved content and their execution order. Now re-run the server, I believe you will find something really interesting being printed.

Execution differences between "external" and "inlined" packages

Let's do it without the noExternal: ['bar'] config first:

// 1st request (inlined)
const __0__ = await __vite_ssr_import__("react/jsx-dev-runtime", {"importedNames":["jsxDEV"]});
const __1__ = await __vite_ssr_import__("react-dom/server", {"importedNames":["renderToString"]});
const __2__ = await __vite_ssr_import__("/src/App.tsx", {"importedNames":["default"]});

const render = async () => __1__.renderToString(
  __0__.jsxDEV(__2__.default, ..., this)
);

Object.defineProperty(
  __vite_ssr_exports__,
  "render",
  { enumerable: true, configurable: true, get() { return render } }
);

// 2nd request (external)
file:///xxx/node_modules/.pnpm/react@19.0.0/node_modules/react/jsx-dev-runtime.js

// 3rd request (external)
file:///xxx/node_modules/.pnpm/react-dom@19.0.0_react@19.0.0/node_modules/react-dom/server.node.js

// 4th request (inlined)
const __0__ = await __vite_ssr_import__("react/jsx-dev-runtime", {"importedNames":["jsxDEV"]});
const __1__ = await __vite_ssr_import__("bar/bar-esm.mjs", {"importedNames":["bar"]});

function App() {
  return __0__.jsxDEV(..., this);
}

Object.defineProperty(
  __vite_ssr_exports__,
  "default",
  { enumerable: true, configurable: true, value: App }
);

// 5th request (external)
file:///xxx/node_modules/bar/bar-esm.mjs

// and then the runtime error
// 00:00:00 AM [vite] (ssr) Error when evaluating SSR module ./src/server.tsx: Unknown file extension ".css" for /xxx/node_modules/bar/style.css

According to the printed logs, now we know:

The runtime error was caused by the 5th request, which import(./node_modules/bar/bar-esm.mjs) natively, while bar-esm.mjs is non-pure JavaScript.
All the imports in inlined resources are transformed into a await __vite_ssr_import__() function call, which is an async custom helper function to load the target asynchronously. Actually, it's easy to guess this helper function calls native await import() inside. So basically, it turns the static imports into dynamic ones.
Also, the helper function await __vite_ssr_import__() has a second parameter which accepts an object with importedNames property. This is used to describe the target name(s) to be imported.

Great! Now, let's add the noExternal: ['bar'] config back and run the server again. You will find from the 4th request, the logs are different:

...

// 4th request (external)
const __0__ = await __vite_ssr_import__("react/jsx-dev-runtime", {"importedNames":["jsxDEV"]});
const __1__ = await __vite_ssr_import__("/node_modules/bar/bar-esm.mjs", {"importedNames":["bar"]});

function App() {
  return __0__.jsxDEV(..., this);
}

Object.defineProperty(
  __vite_ssr_exports__,
  "default",
  { enumerable: true, configurable: true, value: App }
);

// 5th request (inlined)
const __0__ = await __vite_ssr_import__("/node_modules/bar/style.css");

const bar = 'bar'

Object.defineProperty(
  __vite_ssr_exports__,
  "bar",
  { enumerable: true, configurable: true, get() { return bar } }
);

// 6th request (inlined)
// (empty, actually it's from ./node_modules/bar/style.css)

// the end

If you look carefully, you will find:

The 5th request becomes inlined which further makes the CSS import as the 6th request as an inlined resource. But more importantly,
in the 4th request, the original __vite_ssr_import__("bar/bar-esm.mjs") is now replaced with __vite_ssr_import__("/node_modules/bar/bar-esm.mjs").

From this difference, we can roughly guess that: Vite will treat

the package imports like bar/bar-esm.mjs as external, while
the relative path import like ./node_modules/bar/bar-esm.mjs as inlined.

Don't use named imports in an inlined file for an external `module.exports` CJS resource

There is actually a following special case that needs your attention.

Let's create another deep dependency with pure CJS code:

mkdir node_modules/bar/node_modules
mkdir node_modules/bar/node_modules/bar-sub
touch node_modules/bar/node_modules/bar-sub/package.json
touch node_modules/bar/node_modules/bar-sub/bar-sub-cjs.cjs

In node_modules/bar/node_modules/bar-sub/package.json:

  {
    "name": "bar-sub"
  }

In node_modules/bar/node_modules/bar-sub/bar-sub-cjs.cjs:

  exports.barSub = 'bar-sub-cjs'

And then update node_modules/bar/bar-esm.mjs to import bar-sub:

  import { barSub } from 'bar-sub/bar-sub-cjs.cjs'

Snapshot of the demo project #14 - SSR external CJS with exports.xxx

It works in both SPA and SSR mode. However, if we change the CJS code into module.exports style:

In node_modules/bar/node_modules/bar-sub/bar-sub-cjs.cjs:

  module.exports = {
    barSub: 'bar-sub-cjs',
  }

Snapshot of the demo project #15 - SSR external CJS with module.exports

After this change, the SPA mode still works, but the SSR mode will throw a runtime error:

SyntaxError: [vite] Named export 'barSub' not found. The requested module 'bar-sub/bar-sub-cjs.cjs' is a CommonJS module, which may not support all module.exports as named exports.
CommonJS modules can always be imported via the default export, for example using:

import pkg from 'bar-sub/bar-sub-cjs.cjs';
const {barSub} = pkg;

You might have seen the similar error when you use the popular JS lib called "lodash". When you import lodash via a named import like import { merge } from 'lodash, it will throw the same runtime error message in SSR mode.

After knowing package imports are treated as await import() in Vite SSR mode. It's easy to understand what happened: the native import() can't get the named exports from a module.exports CJS resource.

Let's do a simple quick test. Open a Node.js REPL and run the following code:

await import('./node_modules/bar/node_modules/bar-sub/bar-sub-cjs.cjs')
// [Module: null prototype] { default: { barSub: 'bar-sub-cjs' } }

As you see the imported result is all in the default field. So a statement like const { barSub } = await import() won't get what you want. But if you change the CJS code back to exports.barSub = 'bar-sub-cjs', it will work as expected:

await import('./node_modules/bar/node_modules/bar-sub/bar-sub-cjs.cjs')
// [Module: null prototype] {
//   barSub: 'bar-sub-cjs',
//   default: { barSub: 'bar-sub-cjs' }
// }

So, as the error message suggested, in this case you have to use the default import instead of the named import:

import pkg from 'bar-sub/bar-sub-cjs.cjs'
const { barSub } = pkg;

Snapshot of the demo project #16 - fix with default import + destructure

The package 'lodash' is exactly the same case. It uses module.exports to export the whole object, which is not compatible with the named import syntax. So you have to use the default import instead:

import pkg from 'lodash'
const { merge } = pkg

Now, we already know how Vite deals with JavaScript code as inlined or external resource in server environment, and how to inspect the whole process. Next, we will explore all the other ways to configure them in Vite.

Other relevant options

Beside ssr.noExternal, there is another option ssr.external to ensure certain packages to be executed directly without transformation.

For either of the options, giving a true value means all the packages will be transformed or not. You can also specify a package list to another option to toggle them off or on.

For example:

{
  ssr: {
    // all the packages will be executed directly, except...
    external: true,
    // only 'foo' and 'bar' will be transformed
    noExternal: ['foo', 'bar'],
  },
}

or:

{
  ssr: {
    // all the packages will be transformed, except...
    noExternal: true,
    // only 'react' and 'react-dom' will be executed directly
    external: ['react', 'react-dom'],
  },
}

To choose which way to configure, I think it depends on whether your project is more likely to have more packages to be transformed or not. However, by default, ssr.external is true and ssr.noExternal is []. For ssr.noExternal, you can even use regular expressions to match the package names like:

{
  ssr: {
    // `external` is `true` by default
    noExternal: [/^foo/, 'bar'],
  },
}

Advanced case: deep dependencies configuration

Now for a Vite project with a simple dependency, I guess that's enough to go. However, what about the deep dependencies? For example, what if the package bar has a sub-dependency named bar-dep-a? Will it be transformed or not? May I specify bar-dep-a in ssr.noExternal or ssr.external?

Well, that's a little bit tricky:

if a package has been specified as ssr.external, all its sub-dependencies will be treated as external as well. there is no way to interfere with it anymore.
if a package has been specified as ssr.noExternal, all its sub-dependencies will still be treated according to the ssr.external and ssr.noExternal settings.

For example, if the dependency tree looks like:

bar
└── bar-dep-a
    └── bar-dep-b

Then:

config:
```
{
  ssr: {
    external: true,
    noExternal: ['bar-dep-a'],
  },
}
```
will make all of them external since the top-level bar is external and the setting for its sub-dependency bar-dep-a won't take effect.

config:

{
  ssr: {
    external: true,
    noExternal: ['bar'],
  },
}

will make bar inline, but bar-dep-a and bar-dep-b still external.

config:

{
  ssr: {
    external: true,
    noExternal: ['bar', 'bar-dep-a', 'bar-dep-b'],
  },
}

or:

{
  ssr: {
    external: true,
    noExternal: [/^bar/],
  },
}

or:

{
  ssr: {
    noExternal: true,
    external: [],
  },
}

will make all of them inline.

non-JS files in `node_modules`

During writing this article, I've tried multiple different combinations of the files and configs. Although the official docs say that Vite will "externalized all dependencies by default", I still found some cases that Vite will transform and inline them, which are the non-JS files like TSX. For example, if we create a TSX file with the same content as bar-esm.mjs:

touch node_modules/bar/bar-tsx.tsx

node_modules/bar/bar-tsx.tsx:

  import './style.css'

  export const bar = 'bar'

Snapshot of the demo project #17 - non-JS file

Then update src/App.tsx to import bar/bar-tsx.tsx instead, the server will still work as expected without the noExternal: ['bar'] config.

A small recap:

Vite will treat all the JavaScript files in node_modules as external by default, whatever it's in CJS or ESM.
Vite will treat all the non-JS files (e.g. TS/TSX files) in node_modules as inlined and transform them by default before execution.
You can configure ssr.noExternal to transform certain packages and execute them as inlined resources. This is useful when the resource is not pure JavaScript code. e.g. with CSS imports or assets imports.
If you set a package as "external", all its sub-dependencies will be treated as external as well. You can't change it anymore.
If you set a package as "noExternal", all its sub-dependencies will be also treated according to the ssr.external and ssr.noExternal settings.
You can either set ssr.external or ssr.noExternal to true and then specify certain packages in the other one. For ssr.noExternal, you can also use a regular expression to match the package names.
If you want to inline a certain package and all its deep dependencies, you have to set ssr.noExternal to true or explicitly list all of them in ssr.noExternal, and luckly we have regular expressions to help.

Till now, there is still a special case not discussed yet: what about a non-pure CJS package import in SSR mode? For example a CJS file which includes a require('./style.css') in it. Obviously, Vite can't load it directly, nor transform it neither. How should we deal with it?

You may wonder if we could somehow "optimize" it like Vite does in SPA mode. The answer is yes. But it's not enabled by default. Next, let's dive into this topic.

What is `ssr.optimizeDeps` config in Vite?

In short, ssr.optimizeDeps is like the second "optimization boundary" for SSR mode. So with this "optimization boundary", we can optimize CJS code into ESM. And then with the first "transformation boundary", we can transform the non-pure JavaScript code into pure JavaScript code.

A simple case

Let's make a scenario to demonstrate the problem. Just create a package named baz with a CJS file baz-cjs.cjs and a CSS file style.css:

mkdir node_modules/baz
touch node_modules/baz/package.json
touch node_modules/baz/baz-cjs.cjs
touch node_modules/baz/style.css

In node_modules/baz/package.json:

  {
    "name": "baz"
  }

node_modules/baz/baz-cjs.cjs:

  require('./style.css')

  exports.baz = 'baz'

node_modules/baz/style.css:

  .baz {
    color: white;
    background-color: green;
  }

Now, update src/App.tsx to consume Baz only:

src/App.tsx:

  import { baz } from 'baz/baz-cjs.cjs'

  export default function App() {
    return (<h1 className='baz'>{baz}</h1>)
  }

Snapshot of the demo project #18 - a case for non-pure CJS

If you run the project in SPA mode via pnpm run dev, it works as expected. However, if you run it in SSR mode via pnpm run dev:ssr, you will see the runtime error:

/<project-root>/node_modules/baz/style.css:1
.baz {
^

SyntaxError: Unexpected token '.'
    at wrapSafe (node:internal/modules/cjs/loader:1281:20)
    ...

Being different from the client side, the ssr.optimizeDeps config for the server-side is not enabled by default.

To solve it, as we mentioned before, we need to manually add it into vite.config.ts:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  ssr: {
    optimizeDeps: {
      include: [
        'baz/baz-cjs.cjs'
      ],
    },
    noExternal: [
      'baz'
    ]
  },
  plugins: [react()],
})

Snapshot of the demo project #19 - fix with ssr.noExternal + ssr.optimizeDeps

It includes 2 separate options:

ssr.optimizeDeps.include: to specify the package imports to be pre-bundled (baz/baz-cjs.cjs).
ssr.noExternal: to specify the packages not be executed directly (baz). So the pre-bundled baz/baz-cjs.cjs can be consumed instead.

Now, restart the server, it works as expected.

How to inspect 4: the `node_modules/.vite/deps_ssr` folder

To see what happened behind, now you can find an additional ./node_modules/.vite/deps_ssr folder generated besides ./node_modules/.vite/deps and quite similar to it. It's for SSR mode as we mentioned above. e.g. the package import baz/baz-cjs.cjs has a corresponding file there ./node_modules/.vite/deps_ssr/baz_baz-cjs__cjs.js. This is the actual resource that will be consumed in the server environment.

$ tree node_modules/.vite/
node_modules/.vite/
├── deps
│   ├── ...
│   └── ...
└── deps_ssr
    ├── _metadata.json
    ├── baz_baz-cjs__cjs.js
    ├── baz_baz-cjs__cjs.js.map
    └── package.json

2 directories, 26 files

And of course, you can also use ssr.optimizeDeps.exclude as you like according to your situation.

If you also inspect the module evaluation process, you will see:

without noExternal: ['baz'], the execution code is like:

  ...
  const __1__ = await __vite_ssr_import__("baz/baz-cjs.cjs", {"importedNames":["baz"]});
  ...

which is still a package import and will be imported natively which causes the runtime error.

with noExternal: ['baz'], the execution code is like:

  ...
  const __1__ = await __vite_ssr_import__("/node_modules/.vite/deps_ssr/baz_baz-cjs__cjs.js?v=<hash>", {"importedNames":["default"]});
  ...

which is an optimized import in node_modules/.vite/deps_ssr. So it works as expected.

I think this is the last piece of the puzzle for all kinds of dependency consumptions in Vite.

A small recap

For pure ESM code, you can go anywhere.
For pure CJS code, you can go to ssr.external. Vite will load them directly.
For ESM code with CSS imports or assets imports, you can go to ssr.noExternal. Vite will transform them before execution.
For CJS code with CSS imports or assets imports, you can go to both ssr.noExternal and ssr.optimizeDeps. Vite will pre-bundle them first into ESM and then transform them before execution. And of course this approach is also available for pure CJS code.

Also remember:

optimizeDeps is enabled by default in client-side. You can disable it by setting optimizeDeps.noDiscovery.
optimizeDeps is disabled by default in server-side.
external is by enabled default in SSR mode. You can disable it by setting ssr.noExternal as true.

So far, that's all about how Vite deals with all kinds of dependencies in your projects. Next, let's talk about some other Vite config options those can possibly confuse you by affecting the dependency consumptions.

What if I add `resolve.alias` in Vite config?

In Vite, resolve.alias is used to create aliases for particular imports. It follows rollup's alias plugin config. Usually, you need to specify a find string or regexp to match the import path, and then a replacement string. As an advanced usage, you can also specify a customResolver function to resolve the import path further.

Here, we will focus on the replacement of package imports or related to certain resources in node_modules. For example, you might want to make a certain package in "singleton" mode, that means all the package imports with the same name should go to the same file. Let's try to do it with resolve.alias.

A simple case

First, let's create another version of package foo as a dependency of bar:

mkdir node_modules/bar/node_modules/foo
touch node_modules/bar/node_modules/foo/package.json
touch node_modules/bar/node_modules/foo/foo-cjs.cjs

In node_modules/bar/node_modules/foo/package.json:

  {
    "name": "foo",
    "version": "2.0.0"
  }

In node_modules/bar/node_modules/foo/foo-cjs.cjs:

  exports.foo = 'foo-cjs-v2'

next, update node_modules/bar/bar-esm.mjs to consume foo:

  import './style.css'
  import { foo } from 'foo/foo-cjs.cjs'

  export const bar = foo

revert the src/App.tsx to consume Bar again:

  import { foo } from 'foo/foo-cjs.cjs'
  import { bar } from 'bar/bar-esm.mjs'

  console.log({ foo, bar })

  export default function App() {
    return (<h1 className='bar'>{foo === bar ? 'Yes' : 'No' }</h1>)
  }

revert the vite.config.ts to mark bar as inlined:

  import { defineConfig } from 'vite'
  import react from '@vitejs/plugin-react'

  // https://vite.dev/config/
  export default defineConfig({
    ssr: {
      noExternal: ['bar'],
    },
    plugins: [
      react(),
    ],
  })

Snapshot of the demo project #20 - a case for resolve.alias

Now, restart the Vite dev server, you will see "No" in the browser, in both SPA mode and SSR mode. Because the 2 imports are from different versions of foo.

Let's add an alias in vite.config.ts to make them the same:

import { dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

const __dirname = dirname(fileURLToPath(import.meta.url));

// https://vite.dev/config/
export default defineConfig({
  resolve: {
    alias: [
      {
        find: 'foo',
        replacement: `${__dirname}/node_modules/foo`,
      },
    ],
  },
  ssr: {
    noExternal: ['bar'],
  },
  plugins: [
    react(),
  ],
})

It's also recommended to install @types/node as a dev dependency to avoid type errors in the code above.

Snapshot of the demo project #21 - fix SPA with resolve.alias

Now you can see the rendering result is "Yes" in SPA mode via pnpm run dev. That means the 2 imports are from the same version of foo. However, in SSR mode via pnpm run dev:ssr, you will see the runtime error:

00:00:00 AM [vite] (ssr) Error when evaluating SSR module ./src/server.tsx: exports is not defined.
       at eval (/xxx/node_modules/foo/foo-cjs.cjs:3:14)
       ...

If you inspect the module evaluation process, you will see:

before the alias:

  // inlined
  const __1__ = await __vite_ssr_import__("foo/foo-cjs.cjs", {"importedNames":["foo"]});
  const __2__ = await __vite_ssr_import__("/node_modules/bar/bar-esm.mjs", {"importedNames":["bar"]});

after the alias:

  // inlined
  const __1__ = await __vite_ssr_import__("/node_modules/foo/foo-cjs.cjs", {"importedNames":["foo"]});
  const __2__ = await __vite_ssr_import__("/node_modules/bar/bar-esm.mjs", {"importedNames":["bar"]});

The package import of foo/foo-cjs.cjs became a relative path import after the alias. So it will never be imported as an external resource. And it further caused the runtime error because it was written in CJS.

I've tried multiple different combinations of ssr.external and resolve.alias settings to fix it but they all failed. The lesson I learned from this case is that:

A small recap

The resolve.alias config will affect the package imports in node_modules and make them into relative path imports. This further makes them always inlined in SSR mode.

So, it's easy to know if you have a CJS package needs to be ensured as singleton, resolve.alias doesn't help in SSR mode. You need something else.

What if I add `resolve.dedupe` in Vite config?

According to the official docs, besides resolve.alias, Vite also provides another option resolve.dedupe to deduplicate the package imports. Does it work here? Let's give it a try.

Fix the previous case

In vite.config.ts, remove the resolve.alias config and add the resolve.dedupe:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  resolve: {
    dedupe: ['foo'],
  },
  ssr: {
    noExternal: ['bar'],
  },
  plugins: [
    react(),
  ],
})

Snapshot of the demo project #22 - fix SSR with resolve.dedupe

Then try pnpm run dev and pnpm run dev:ssr. They both work now.

How does it work?

If you inspect the module evaluation process, you will find the foo/foo-cjs.cjs import is still the package import:

// inlined
const __1__ = await __vite_ssr_import__("foo/foo-cjs.cjs", {"importedNames":["foo"]});

which ensures the CJS code to be executed as an external resource. If you wonder how resolve.dedupe works, you can check the source code in packages/vite/src/node/plugins/resolve.ts:

export function tryNodeResolve(...) {
  ...
  if (dedupe.includes(pkgId)) {
    basedir = root
  }
  ...
}

The way it works is simple: for packages on the dedupe list, Vite always resolves them from the project root instead of the importer's location. So the package import foo/foo-cjs.cjs all over the project will be resolved to the same file <project-root>/node_modules/foo/foo-cjs.cjs.

Then the last question: does resolve.dedupe even work with external resources?

Another case with external resources

According to its implementation, if a package import happens in an external resource, there is no way to deduplicate it. For example, let's create a package named qux with another version of foo as a dependency, at the same time, add a pure JavaScript file in qux which imports foo/foo-cjs.cjs:

mkdir node_modules/qux
touch node_modules/qux/package.json
touch node_modules/qux/qux-cjs.cjs
mkdir node_modules/qux/node_modules
mkdir node_modules/qux/node_modules/foo
touch node_modules/qux/node_modules/foo/package.json
touch node_modules/qux/node_modules/foo/foo-cjs.cjs

In node_modules/qux/package.json:

  {
    "name": "qux"
  }

node_modules/qux/qux-cjs.cjs:

  const { foo } = require('foo/foo-cjs.cjs')

  exports.qux = foo

In node_modules/qux/node_modules/foo/package.json:

  {
    "name": "foo",
    "version": "3.0.0"
  }

node_modules/qux/node_modules/foo/foo-cjs.cjs:

  exports.foo = 'foo-cjs-v3'

Now, update src/App.tsx to consume Qux:

src/App.tsx:

  import { foo } from 'foo/foo-cjs.cjs'
  import { qux } from 'qux/qux-cjs.cjs'

  console.log({ foo, qux })

  export default function App() {
    return (<h1>{foo === qux ? 'Yes' : 'No' }</h1>)
  }

Snapshot of the demo project #23 - a case for resolve.dedupe with external resources

In this case, you will find the client-side rendering result is "Yes", while the server-side rendering result is "No" (see the requested HTML content from server).

To make the server-side works, we have to make the qux package as ssr.noExternal, however, qux/qux-cjs.cjs is in CJS which can't be transformed properly. So we additionally need to add ssr.optimizeDeps.include to pre-bundle it:

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

// https://vite.dev/config/
export default defineConfig({
  resolve: {
    dedupe: ['foo'],
  },
  ssr: {
    optimizeDeps: {
      include: ['qux/qux-cjs.cjs'],
    },
    noExternal: ['qux'],
  },
  plugins: [react()],
})

Snapshot of the demo project #24 - fix with ssr.optimizeDeps + ssr.noExternal

With these combined options above, all the modes work perfectly.

A small recap

The resolve.dedupe config will deduplicate the package imports in node_modules without resolving them into relative path imports. This further helps them skipping unnecessary CJS inline transformation in SSR mode.
The resolve.dedupe won't affect the dependencies of external resources. So your target package can still be not singleton. To ensure it, you have to find all the external targets and keep them inlined by ssr.noExternal. You also need to keep them into ssr.optimizeDeps.include if they are in CJS.

The new way to config SSR mode: `environments`

From Vite 6, the "Environment Instances" and relevant APIs and config options are introduced to better manage the multiple environments like SSR mode in Vite. In the future, the ssr config will be deprecated and replaced by the new environments.ssr config. At the same time, the client-side-only config options can be specified into environments.client. I think this new config design makes more sense. Also, you can have more control over it, e.g. specifying different resolve.dedupe in SPA and SSR mode, etc. (However, till I wrote this article, the resolve.alias config is still global and not environment-specific. Not sure about the reason. Since this could be also very helpful when you'd like to hack some code only in SPA mode or SSR mode.)

Check this official blog post and this official doc for more details.

How to deal with dependencies in Vitest?

Vitest is another Vite family member. It is a unit test framework based on Vite. So it has a similar server environment to execute your code and dependencies for testing. When you run the tests, you will face the same issues like whether a resource should be transformed beforehand or imported directly. Luckily, Vitest also provides such config options. However, their option names are slightly different:

server.deps.external: to specify the packages being imported directly.
server.deps.inline: to specify the packages being transformed beforehand.

If those 2 options above are not enough, you might need to try option deps.optimizer.

You might be also interested in option deps.web.transformAssets and deps.web.transformCss. However, most of the time, you don't have to worry about them because they are true by default.

Conclusion

So overall, we have:

In normal (SPA) mode, Vite can't deal with CJS code without the optimization process to pre-bundle them into ESM. The optimization process is on for all the code in node_modules by default, but configurable by optimizeDeps option.
In SSR mode, Vite can't deal with non-pure JavaScript code (with CSS imports or assets imports) by default. To make it works, you have to specify them as "inlined" via ssr.noExternal/ssr.noExternal config. For non-pure CJS code, you additionally need ssr.optimizeDeps to pre-bundle them into ESM.
The resolve.alias config will force the matched code to be inlined in SSR mode. So be careful when they are in CJS. Because once they are being inlined, you have to also "optimize" them beforehand.
The resolve.dedupe config won't deduplicate the dependencies in external resources in SSR mode. To make it works, you have to specify all of them as "inlined" and also "optimize" them beforehand necessarily.
Be careful when you deal with nested dependencies via ssr.external/ssr.noExternal and resolve.dedupe.
In Vitest, the corresponding options are server.deps.external/server.deps.inline and deps.optimizer.
The new config in Vite 6: environments.ssr and environments.client.

Why I have to know so much details to use Vite?

I think for most of the common cases, the default settings of Vite are just the best. For example:

You usually just want better performance so optimizing all the dependencies makes sense.
You usually just consume pure JavaScript code in node_modules and again want better performance so externalizing them by default in SSR mode makes sense.
You usually have no large amount of inlined resources in node_modules so no optimization process by default in SSR mode makes sense.
You usually can't execute TS/TSX files directly so transforming them in node_modules by default makes sense.

So for simple and fresh projects, you can just go with the default settings. However, when your project grows larger and larger, or as a dev tool author, you may need to deal with all the edge cases sooner or later. So you need to know the necessary details of how Vite works to help you make the right choices. At some rare cases and points, I don't think people could figure them out easily, just by reading the official config references, without diving into the details above.

Once again, after the full integration of Rolldown as its new core, I believe the logic above would be much simpler since it could possibly run to a new trade-off which can resolve and transform all kinds of resources in an organically same way without losing speed. And it might also eliminate most of the edge cases above. Let's keep an eye on that.

However, there might still be some other edge cases that I haven't covered yet. Please DO let us know if you find any. And of course, it's also always good to open a discussion, an issue or a PR in the Vite repo for them.

I will keep this article updated as well.

Cheers!

Vlite - a lite demo server inspired by Vite

Jinjiang — Thu, 07 Mar 2024 03:12:56 +0000

Today, I'd like to introduce Vlite, a lite demo server inspired by Vite.

Usage

With Vlite, you can show your ideas in an instant way.

To install Vlite:

npm install -g @jinjiang/vlite
# or
yarn global add @jinjiang/vlite
# or
pnpm add -g @jinjiang/vlite

Now you can prepare an index.html and further write your Vue, React, or vanilla code besides it. e.g.:

Then just run vlite on this directory, you will preview your app on your browser. That's it. No npm installation, no build steps, just works like a static local server.

The idea

It came out when I built some quick frontend demos. Usually there are 3 possible ways to do that:

use static server like http-serve or serve, with which you can write HTML, CSS, and JavaScript that browsers natively support.
use a local dev env like Vite, more or less you have to set up your local project and install dependencies via a package manager like npm.
use an online edit-n-preview platform like CodeSandbox or StackBlitz.

For me, none of them was straightforward enough. So I was wondering whether we could have a more instant way to achieve that. It was better to be local first, but not too many steps to get started.

At the same time, I'd like to put some extra considerations and trade-offs in:

Target 1: ESM-friendly

Nowadays, all the browsers natively support ES Modules very well. That means you don't have to bundle your large project to run. We can just treat every file as an ESM to response.

For the possible upstream and downstream workflow, I think sticking on ESM is always a good idea. For example, I've noticed a new proposal from tc39 called "JavaScript Module Declarations" to inline your modules. Maybe one day we can further bundle your project in a simple action with this. That's why I'd like to make it as ESM-friendly as possible.

Target 2: Simplifying the compilations

For local demos, I can see a lot of potentials to simplify the compilations.

Polyfills and syntax sugar compilations can be skipped for local demos.
I feel the frontend syntax choices are slightly converging. And their compilers are more and more mature. I decided to start from React and Vue projects, which include TS/JSX, CSS, and Vue SFC.
You can find faster and simpler options every day. They make the compilation for each file on the fly possible.
Removing all the optional processes like HMR, SSR, source maps, or any other DX enhancements.

It's just for local demos, right? So taking all above is not a big deal. On the other hand, you might be surprised how simple it could be. 😉

How it works?

Basically, the whole tool consists of 3 parts:

a http server to accept requests
a plugin system to manage the compilation process
a set of plugins to handle all kinds of files into ESMs

A simple plugin system

The plugin system is heavily inspired by Vite/Rollup. I have to say their plugin system is SO good.

In Vlite, the plugin system only accepts 2 hooks (in pseudo code):

load(filepath): string | Buffer | undefined: First of all, the default loader is always the plain file reader. And every plugin has a chance to overwrite the result by returning a string or a buffer
transform(filepath, queryParams, content): string | Buffer | undefined: Every plugin has a chance to handle it. You can detect whether to handle or skip it by checking the file extension name or query params.

Comparing to Vite/Rollup:

I removed the resolveId() hook since technically every request should correspond to a local file.
I provided a default load() behavior to read content from file system. In all the cases so far it's enough. The load() hook was only designed for future usage like virtual modules.
I didn't introduce source maps neither. So the input and output could be simple and straightforward.

Compiler choices

For TS and JSX files, I chose sucrase, the same choice as Vue Playground made. It's super fast and esay to config.

For CSS files, I converted each of them into ESM code with document.createElement('style') and document.head.appendChild().

e.g. imaging a CSS file:

body { margin: 0 }

it will be processed into:

const style = document.createElement('style')
style.textContent = 'body { margin: 0 }'
document.head.appendChild(style)

You might ask how to deal with CSS Modules and their generated class names. I used postcss-modules to convert it and export those class names as a JSON object.

e.g. a CSS Module file:

.foo { color: red }

will be processed into:

const style = document.createElement('style')
style.textContent = '.foo_xxxxxx { color: red }'
document.head.appendChild(style)
export default { foo: 'foo_xxxxxx' }

For Vue SFCs, I reused another package that I created: vue-simple-compiler. It can compile a Vue SFC into plain JavaScript and CSS imports.

For assets like images, it's a little bit tricky. Since there are 2 ways to consume them:

request the file in browsers,
import the file path in JavaScript.

So I introduced a special query parameter ?url. If the request has this query parameter, the server will respond with the file path as the default export in ESM.

e.g. for an image logo.png:

If you request it directly from the browser, you will get the image file in binary data.
If you write import logo from './logo.png' in JS/TS, the import statement will be compiled into import logo from './logo.png?url'. Then the request /logo.png?url would return export default '/logo.png'. So when you further write code like <img src={logo} /> it will work as well.

For npm packages, I used a ES imports parser parse-imports to find them, and replaced each of them with a esm.sh URL. It's a fast CDN providing npm packages in ESM on the fly.

e.g. the import import { createApp } from 'vue' will be compiled into import { createApp } from 'https://esm.sh/vue'.

Conclusions and future plans

That's all above Vlite. It's designed for quick demos with simplicity and straightforwardness. No extra stuff like HMR, SSR, source maps, etc.

To be honest, I still have some other ideas to put in, like:

Pick more performant parsers and compilers.
Support a few more frameworks, probably.
SPA mode to serve HTML entry file in any case the request path doesn't match a file.
Offline mode by caching certain packages from esm.sh
Build mode to generate all the files into ESM for further static servers usage.
A new "bundle" mode to bundle generated file into one piece by JavaScript Module Declarations

Anyway, just all for quick demos. And you are very welcome to give a try.

Cheers.

Understanding Reactivity in Vue 3.0

Jinjiang — Tue, 26 May 2020 15:12:15 +0000

This article is just written for my knowledge and understanding of the coolest part in Vue: the reactivity system.

Background

As we know, Vue.js team is working on 3.0 for a while. Recently it released the first Beta version. That means the core tech design is stable enough. Now I think it's time to walk through something inside Vue 3.0. That's one of my most favorite parts: the reactivity system.

What's reactivity?

For short, reactivity means, the result of calculations, which depends on some certain data, will be automatically updated, when the data changes.

In modern web development, we always need to render some data-related or state-related views. So obviously, making data reactive could give us lots of benefits. In Vue, the reactivity system always exists from its very early version till now. And I think that's one of the biggest reasons why Vue is so popular.

Let's have a look at the reactivity system in the early version of Vue first.

Reactivity in Vue from 0.x to 1.x

The first time I touched Vue is about 2014, I guess it was Vue 0.10. At that time, you could just pass a plain JavaScript object into a Vue component through data option. Then you could use them in a piece of document fragment as its template with reactivity. Once the data changes, the view would be automatically updated. Also you could use computed and watch options to benefit yourself from the reactivity system in more flexible ways. Same to the later Vue 1.x.

new Vue({
  el: '#app',
  template: '<div @click="x++">{{x}} + {{y}} = {{z}}</div>',
  data() {
    return { x: 1, y: 2 }
  },
  computed: {
    z() { return this.x + this.y }
  },
  watch: {
    x(newValue, oldValue) {
      console.log(`x is changed from ${oldValue} to ${newValue}`)
    }
  }
})

You may found these APIs didn't change too much so far. Because they work the same totally.

So how does it work? How to make a plain JavaScript object reactive automatically?

Fortunately, in JavaScript we have an API Object.defineProperty() which could overwrite the getter/setter of an object property. So to make them reactive, there could be 3 steps:

Use Object.defineProperty() to overwrite getters/setters of all the properties inside a data object recursively. Besides behaving normally, it additionally injects a trigger inside all setters, and a tracker inside all getters. Also it will create a small Dep instance inside each time to record all the calculations which depend on this property.
Every time we set a value into a property, it will call the setter, which will re-evaluate those related calculations inside the Dep instance. Then you may ask how could we record all the related calculations. The fact is when each time we define a calculation like a watch function or a DOM update function, it would run once first - sometimes it runs as the initialization, sometimes it's just a dry-run. And during that running, it will touch every tracker inside the getters it depends on. Each tracker will push the current calculation function into the corresponding Dep instance.
So next time when some data changes, it will find out all related calculations inside the corresponding Dep instance, and then run them again. So the effect of these calculations will be updated automatically.

A simple implementation to observe data using Object.defineProperty is like:

// data
const data = { x: 1, y: 2 }

// real data and deps behind
let realX = data.x
let realY = data.y
const realDepsX = []
const realDepsY = []

// make it reactive
Object.defineProperty(data, 'x', {
  get() {
    trackX()
    return realX
  },
  set(v) {
    realX = v
    triggerX()
  }
})
Object.defineProperty(data, 'y', {
  get() {
    trackY()
    return realY
  },
  set(v) {
    realY = v
    triggerY()
  }
})

// track and trigger a property
const trackX = () => {
  if (isDryRun && currentDep) {
    realDepsX.push(currentDep)
  }
}
const trackY = () => {
  if (isDryRun && currentDep) {
    realDepsY.push(currentDep)
  }
}
const triggerX = () => {
  realDepsX.forEach(dep => dep())
}
const triggerY = () => {
  realDepsY.forEach(dep => dep())
}

// observe a function
let isDryRun = false
let currentDep = null
const observe = fn => {
  isDryRun = true
  currentDep = fn
  fn()
  currentDep = null
  isDryRun = false
}

// define 3 functions
const depA = () => console.log(`x = ${data.x}`)
const depB = () => console.log(`y = ${data.y}`)
const depC = () => console.log(`x + y = ${data.x + data.y}`)

// dry-run all dependents
observe(depA)
observe(depB)
observe(depC)
// output: x = 1, y = 2, x + y = 3

// mutate data
data.x = 3
// output: x = 3, x + y = 5
data.y = 4
// output: y = 4, x + y = 7

Inside Vue 2.x and earlier, the mechanism roughly like this above, but much better abstracted, designed, and implemented.

For supporting more complex cases like arrays, nested properties, or mutating more than 2 properties at the same time, there are more implementation and optimization details inside Vue, but basically, the same mechanism to we mentioned before.

Reactivity in Vue 2.x

From 1.x to 2.x, it was a total rewrite. And it introduced some really cool features like virtual DOM, server-side rendering, low-level render functions, etc. But the interesting thing is the reactivity system didn't change too much, however, the usage above was totally different:

From 0.x to 1.x, the rendering logic depends on maintaining a document fragment. Inside that document fragment, there are some DOM update functions for each dynamic element, attribute, and text content. So the reactivity system mostly works between the data object and these DOM update functions. Since the functions all real DOM functions so the performance is not quite good. In Vue 2.x, this rendering logic of a Vue component became a whole pure JavaScript render function. So it would firstly return virtual nodes instead of real DOM nodes. Then it would update the real DOM based on the result of a fast mutation diff algorithm for the virtual DOM nodes. It was faster than before.
In Vue 2.6, it introduced a standalone API Vue.observalue(obj) to generate reactive plain JavaScript objects. So you could use them inside a render function or a computed property. It was more flexible to use.

At the same time, there are some discussions in Vue community about abstracting the reactivity system into an independent package for wider usage. However it didn't happen at that time.

Limitation of the reactivity system before 3.0

So far, Vue didn't change the reactivity mechanism. But it doesn't mean the current solution is ideally perfect. As I personally understand, there are some caveats:

Because of the limitation of Object.defineProperty we couldn't observe some data changes like:
1. Setting array items by assigning value to a certain index. (e.g. arr[0] = value)
2. Setting the length of an array. (e.g. arr.length = 0)
3. Adding a new property to an object. (e.g. obj.newKey = value) So it needs some complementary APIs like Vue.$set(obj, newKey, value).
Because of the limitation of plain JavaScript data structure, for each reactive object there would be an unenumerable property named __ob__, which might lead to conflict in some extreme cases.
It didn't support more data types like Map and Set. Neither other non-plain JavaScript objects.
The performance is an issue. When the data is large, making it reactive when the initialization would cost visible time. There are some tips to flatten the initial cost but a little bit tricky.

Reactivity system in Vue 3.0

For short, in Vue 3.0, the reactivity system was totally rewritten with a new mechanism and new abstraction, as an independent package. And it also supports more modern JavaScript data types.

You may be familiar with it, maybe not. No worry. Let's quickly take a look at it first by creating a Vue 3.0 project.

Create a Vue 3.0 project

Until now, there is no stable full-featured project generator, since it's still in Beta. We could try Vue 3.0 through an experimental project named "vite":

vitejs / vite

Next generation frontend tooling. It's fast!

Vite ⚡

Next Generation Frontend Tooling

💡 Instant Server Start
⚡️ Lightning Fast HMR
🛠️ Rich Features
📦 Optimized Build
🔩 Universal Plugin Interface
🔑 Fully Typed APIs

Vite (French word for "quick", pronounced /vit/, like "veet") is a new breed of frontend build tooling that significantly improves the frontend development experience. It consists of two major parts:

A dev server that serves your source files over native ES modules, with rich built-in features and astonishingly fast Hot Module Replacement (HMR).
A build command that bundles your code with Rollup, pre-configured to output highly optimized static assets for production.

In addition, Vite is highly extensible via its Plugin API and JavaScript API with full typing support.

Read the Docs to Learn More.

Packages

Package	Version (click for changelogs)
vite
@vitejs/plugin-legacy
create-vite

Contribution

See Contributing Guide.

License

MIT.

How it works

For short, the reactivity system in Vue 3.0 suits up with ES2015!

First part: simple data observer

Since ES2015, there are a pair of APIs - Proxy and Reflect. They are born to reactivity systems! Vue 3.0 reactivity system just be built based on that.

With Proxy you could set a "trap" to observe any operation on a certain JavaScript object.

const data = { x: 1, y: 2 }

// all behaviors of a proxy by operation types
const handlers = {
  get(data, propName, proxy) {
    console.log(`Get ${propName}: ${data[propName]}!`)
    return data[propName]
  },
  has(data, propName) { ... },
  set(data, propName, value, proxy) { ... },
  deleteProperty(data, propName) { ... },
  // ...
}

// create a proxy object for the data
const proxy = new Proxy(data, handlers)

// print: 'Get x: 1' and return `1`
proxy.x

With Reflect you could behave the same as the original object.

const data = { x: 1, y: 2 }

// all behaviors of a proxy by operation types
const handlers = {
  get(data, propName, proxy) {
    console.log(`Get ${propName}: ${data[propName]}!`)
    // same behavior as before
    return Reflect.get(data, propName, proxy)
  },
  has(...args) { return Reflect.set(...args) },
  set(...args) { return Reflect.set(...args) },
  deleteProperty(...args) { return Reflect.set(...args) },
  // ...
}

// create a proxy object for the data
const proxy = new Proxy(data, handlers)

// print: 'Get x: 1' and return `1`
proxy.x

So with Proxy + Reflect together, we could easily make a JavaScript object observable, and then, reactive.

const track = (...args) => console.log('track', ...args)

const trigger = (...args) => console.log('trigger', ...args)

// all behaviors of a proxy by operation types
const handlers = {
  get(...args) { track('get', ...args); return Reflect.get(...args) },
  has(...args) { track('has', ...args); return Reflect.set(...args) },
  set(...args) { Reflect.set(...args); trigger('set', ...args) },
  deleteProperty(...args) {
    Reflect.set(...args);
    trigger('delete', ...args)
  },
  // ...
}

// create a proxy object for the data
const data = { x: 1, y: 2 }
const proxy = new Proxy(data, handlers)

// will call `trigger()` in `set()`
proxy.z = 3

// create a proxy object for an array
const arr = [1,2,3]
const arrProxy = new Proxy(arr, handlers)

// will call `track()` & `trigger()` when get/set by index
arrProxy[0]
arrProxy[1] = 4

// will call `trigger()` when set `length`
arrProxy.length = 0

So this observer is better than Object.defineProperty because it could observe every former dead angle. Also the observer just needs to set up a "trap" to an object. So less cost during the initialization.

And it's not all the implementation, because in Proxy it could handle ALL kinds of behaviors with different purposes. So the completed code of handlers in Vue 3.0 is more complex.

For example if we run arrProxy.push(10), the proxy would trigger a set handler with 3 as its propName and 10 as its value. But we don't literally know whether or not it's a new index. So if we would like to track arrProxy.length, we should do more precise determination about whether a set or a deleteProperty operation would change the length.

Also this Proxy + Reflect mechanism supports you to track and trigger mutations in a Set or a Map. That means operations like:

const map = new Map()
map.has('x')
map.get('x')
map.set('x', 1)
map.delete('x')

would also be observable.

Second: more reactivity APIs

In Vue 3.0, we also provide some other APIs like readonly and markRaw. For readonly what you need is just change the handlers like set and deleteProperty to avoid mutations. Probably like:

const track = (...args) => console.log('track', ...args)
const trigger = (...args) => console.log('trigger', ...args)

// all behaviors of a proxy by operation types
const handlers = {
  get(...args) { track('get', ...args); return Reflect.get(...args) },
  has(...args) { track('has', ...args); return Reflect.set(...args) },
  set(...args) {
    console.warn('This is a readonly proxy, you couldn\'t modify it.')
  },
  deleteProperty(...args) {
    console.warn('This is a readonly proxy, you couldn\'t modify it.')
  },
  // ...
}

// create a proxy object for the data
const data = { x: 1, y: 2 }
const readonly = new Proxy(data, handlers)

// will warn that you couldn't modify it
readonly.z = 3

// will warn that you couldn't modify it
delete readonly.x

For markRaw, in Vue 3.0 it would set a unenumerable flag property named __v_skip. So when we are creating a proxy for data, if there is a __v_skip flag property, then it would be skipped. Probably like:

// track, trigger, reactive handlers
const track = (...args) => console.log('track', ...args)
const trigger = (...args) => console.log('trigger', ...args)
const reactiveHandlers = { ... }

// set an invisible skip flag to raw data
const markRaw = data => Object.defineProperty(
  data,
  '__v_skip',
  { value: true }
)

// create a proxy only when there is no skip flag on the data
const reactive = data => {
  if (data.__v_skip) {
    return data
  }
  return new Proxy(data, reactiveHandlers)
}

// create a proxy object for the data
const data = { x: 1, y: 2 }
const rawData = markRaw(data)
const reactiveData = readonly(data)
console.log(rawData === data) // true
console.log(reactiveData === data) // true

Additionally, a trial of using WeakMap to record deps and flags

Although it's not implemented in Vue 3.0 finally. But there was another try to record deps and flags using new data structures in ES2015.

With Set and Map, we could maintain the relationship out of the data itself. So we don't need flag properties like __v_skip inside data any more - actually there are some other flag properties like __v_isReactive and __v_isReadonly in Vue 3.0. For example:

// a Map to record dependets
const dependentMap = new Map()

// track and trigger a property
const track = (type, data, propName) => {
  if (isDryRun && currentFn) {
    if (!dependentMap.has(data)) {
      dependentMap.set(data, new Map())
    }
    if (!dependentMap.get(data).has(propName)) {
      dependentMap.get(data).set(propName, new Set())
    }
    dependentMap.get(data).get(propName).add(currentFn)
  }
}
const trigger = (type, data, propName) => {
  dependentMap.get(data).get(propName).forEach(fn => fn())
}

// observe
let isDryRun = false
let currentFn = null
const observe = fn => {
  isDryRun = true
  currentFn = fn
  fn()
  currentFn = null
  isDryRun = false
}

Then with Proxy/Reflect together, we could track data mutation and trigger dependent functions:

// … handlers
// … observe
// make data and arr reactive
const data = { x: 1, y: 2 }
const proxy = new Proxy(data, handlers)
const arr = [1, 2, 3]
const arrProxy = new Proxy(arr, handlers)

// observe functions
const depA = () => console.log(`x = ${proxy.x}`)
const depB = () => console.log(`y = ${proxy.y}`)
const depC = () => console.log(`x + y = ${proxy.x + proxy.y}`)
const depD = () => {
 let sum = 0
 for (let i = 0; i < arrProxy.length; i++) {
 sum += arrProxy[i]
 }
 console.log(`sum = ${sum}`)
}

// dry-run all dependents
observe(depA)
observe(depB)
observe(depC)
observe(depD)
// output: x = 1, y = 2, x + y = 3, sum = 6

// mutate data
proxy.x = 3
// output: x = 3, x + y = 5
arrProxy[1] = 4
// output: sum = 8

Actually in early beta version of Vue 3.0, it uses WeakMap instead of Map so there won't be any memory leak to be worried about. But unfortunately, the performance is not good when data goes large. So later it changed back to flag properties.

Btw, there is also a trial of using Symbols as the flag property names. With Symbols the extreme cases could also be relieved a lot. But the same, the performance is still not good as normal string property names.

Although these experiments are not preserved finally, I think it's a good choice if you would like to make a pure (but maybe not quite performant) data observer on your own. So just mention this a little bit here.

Quick summary

Anyway we make data reactive first, and observe functions to track all the data they depend on. Then when we mutate the reactive data, relevant functions would be triggered to run again.

All the features and their further issues above have already been completed in Vue 3.0, with the power of ES2015 features.

If you would like to see all the live version of the code sample about explaining main mechanism of reactivity system in Vue from 0.x to 3.0. You could check out this CodePen and see its "Console" panel:

https://codepen.io/Jinjiang/pen/abvMyQa

Now we have already known the basic usage of it - that's passing something into the data option into a Vue component, and then using it into other options like computed, watch, or the template. But this time, in Vue 3.0, it provides more util APIs, like markRaw we mentioned before. So let's take a look at these util APIs.

Encapsulation

1. Proxy for objects

1.1 Basic: `reactive(data)`, `readonly(data)`, `markRaw(data)`

First let me introduce reactive(data). Just as the name, this API would create a reactive proxy for the data. But here maybe you don't need to use this directly, because the data object you return from the data option will be set up with this API automatically.

Then if you just would like:

Some pieces of data immutable, then you could use readonly(data).
Some pieces of data not reactive, then you could use markRaw(data).

For example:

import { reactive, readonly, markRaw } from 'vue'

const ComponentFoo = {
  data() {
    return {
      reactiveX: { x: 1 },
      reactiveXInAnotherWay: reactive({ x: 1 }),
      immutableY: readonly({ y: 2 }),
      needntChangeReactivelyZ: markRaw({ z: 3 })
    }
  },
  // ...
}

In this case:

If the properties in reactiveX or reactiveXInAnotherWay changed, the view using them in the template will be re-rendered automatically.
If you modify the properties in immutableY, there would be an error thrown. At the same time the view won't be re-rendered.
If you modify the properties in needntChangeReactivelyZ, the view won't be re-rendered.

Also for marking as raw data, you could mark the data, and then use it anywhere else:

const { markRaw } from 'vue'

const obj = { x: 1 }
const result = markRaw(obj)

console.log(obj === result) // true

const ComponentFoo = {
  data() {
    return {
      obj,
      result
    }
  },
  // ...
}

Here the properties in this.obj and this.result are both non-reactive.

1.2 Utils: `isReactive(data)`, `isReadonly(data)`, `isProxy(data)`, `toRaw(data)`

Then you may need some util APIs to help you do the job better.

For the reactive data proxy, then both isProxy(data) and isReactive(data) would be true.
For the readonly data proxy, then both isProxy(data) and isReadonly(data) would be true.
For the original data, whether or not it is marked as raw, then all the isProxy(data) and isReactive(data) and isReadonly(data) would be false.
For the reactive or readonly data proxy, you could use toRaw(data) to get the raw data back.

1.3 Advanced: `shallowReactive(data)`, `shallowReadonly(data)`

With these 2 APIs, you could create a "shallow" data proxy, which means they won't setting traps deeply. Only the first-layer properties in these data proxies would be reactive or readonly. For example:

import { shallowReactive, shallowReadonly } from 'vue'

const ComponentFoo = {
  data() {
    return {
      x: shallowReactive({ a: { b: 1 } }),
      y: shallowReadonly({ a: { b: 1 } })
    }
  }
}

In this case, this.x.a is reactive, but this.x.a.b is not; this.y.a is readonly, but this.y.a.b is not.

If you only consume reactive data inside its own component, I think these APIs above are totally enough. But when things come to the real world, sometimes we would like to share states between components, or just abstract state out of a component for better maintenance. So we need more APIs below.

2. Ref for primitive values

A ref could help you to hold a reference for a reactive value. Mostly it's used for a primitive value. For example, somehow we have a number variable named counter in an ES module, but the code below doesn't work:

// store.js

// This won't work.
export const counter = 0;

// This won't works neither.
// import { reactive } from 'vue'
// export const counter = reactive(0)

<!-- foo.vue -->

<template>
  <div>
    {{ counter }}
  </div>
</template>

<script>
import { counter } from './store.js'

export {
  data() {
    return { counter }
  }
}
</script>

<!-- bar.vue -->

<template>
  <button @click="counter++">increment</button>
</template>

<script>
import { counter } from './store.js'

export {
  data() {
    return { counter }
  }
}
</script>

… because primitive values are immutable. When importing and exporting primitive values, we lose the track. To do this, we could use a ref instead.

2.1 Basic: `ref(data)`

To support the previous example, let's introduce ref(data):

// store.js
import { ref } from 'vue'
export const counter = ref(0)

Then it would work properly.

There is one thing to notice: if you would like to access the value of refs out of a template, you should access its value property instead. For example, if we'd like to modify bar.vue to avoid data option, we could add an increment method to do this, with counter.value:

<!-- bar.vue  -->

<template>
  <button @click="increment">increment</button>
</template>

<script>
import { counter } from './store.js'

export {
  methods: {
    increment() { counter.value++ }
  }
}
</script>

For more caveats, we could do some quick tests later.

2.2 Utils: `isRef(data)`, `unref(data)`

I think these 2 util APIs are easy to understand:

isRef(data): check a value is a ref or not.
unref(data): return the value of a ref.

2.3 Proxy to ref: `toRef(data, key)`, `toRefs(data)`

These 2 util APIs are used for get refs from proxy data:

import { reactive, toRef, toRefs } from 'vue'

const proxy = reactive({ x: 1, y: 2 })

const refX = toRef(proxy, 'x')
proxy.x = 3
console.log(refX.value) // 3

const refs = toRefs(proxy)
proxy.y = 4
console.log(refs.x.value) // 3
console.log(refs.y.value) // 4

As the example above, the typical usage of these APIs is spreading a reactive object into several sub variables and keep the reactivity at the same time.

2.4 Advanced: `shallowRef(data)`

Only trigger update when the ref.value is assigned by another value. For example:

import { shallowRef } from 'vue'
const data = { x: 1, y: 2 }
const ref = shallowRef(data)

// won't trigger update
ref.value.x = 3

// will trigger update
ref.value = { x: 3, y: 2 }

Case: `computed(…)`

Similar idea to computed option inside a Vue component. But if you would like to share a computed state out of a component, I suggest you try this API:

// store.js
import { ref, computed } from 'vue'

export const firstName = ref('Jinjiang')
export const lastName = ref('Zhao')

// getter only version
export const fullName = computed(() => `${firstName.value} ${lastName.value}`)

// getter + setter version
export const fullName2 = computed({
  get: () => `${firstName.value} ${lastName.value}`,
  set: (v) => {
    const names = v.split(' ')
    if (names.length > 0) {
      firstName.value = names[0]
    }
    if (names.length > 1) {
      lastName.value = names[names.length - 1]
    }
  }
})

// another-file.js
import { firstName, lastName, fullName, fullName2 } from './store.js'

console.log(fullName.value) // Jinjiang Zhao

firstName.value = 'Evan'
lastName.value = 'You'
console.log(fullName.value) // Evan You

fullName2.value = 'Jinjiang Zhao'
console.log(firstName.value) // Jinjiang
console.log(lastName.value) // Zhao

Case: `customRef(…)`

This API is my best favorite API in Vue 3.0. Because with this API, you could define how and when to track/trigger your data, during getting or setting the value, that's totally mind-blowing!

For example:

<template>
  <input v-model="email" />
</template>

<script>
import { customRef } from 'vue'
import { validate } from 'isemail'

export default {
  data() {
    return {
      email: customRef((track, trigger) => {
        const value = ''
        return {
          get() {
            track()
            return value
          },
          set(v) {
            if (validate(v)) {
              value = v
              trigger()
            }
          }
        }
      })
    }
  }
}
</script>

That makes real-world user input much easier to handle.

3. Watch for effects

`watchEffect(function)`, `watch(deps, callback)`

In a Vue component, we could watch data mutations by watch option or vm.$watch() instance API. But the same question: what about watching data mutations out of a Vue component?

Similar to computed reactivity API vs. computed option, we have 2 reactivity APIs: watchEffect and watch.

// store.js
import { ref, watch, watchEffect } from 'vue'

export const counter = ref(0)

// Will print the counter every time it's mutated.
watchEffect(() => console.log(`The counter is ${counter.value}`))

// Do the similar thing with more options
watch(counter, (newValue, oldValue) =>
  console.log(`The counter: from ${oldValue} to ${newValue}`)
)

4. Standalone package & usage

Also in Vue 3.0, we have a standalone package for these. That is @vue/reactivity. You could also import most of the APIs we mentioned above, from this package. So the code is almost the same to above:

import { reactive, computed, effect } from '@vue/reactivity'

const data = { x: 1, y: 2 }
const proxy = reactive(data)
const z = computed(() => proxy.x + proxy.y)

// print 'sum: 3'
effect(() => console.log(`sum: ${z.value}`))

console.log(proxy.x, proxy.y, z.value) // 1, 2, 3

proxy.x = 11 // print 'sum: 13'

console.log(proxy.x, proxy.y, z.value) // 11, 2, 13

The only difference is there is no watch and watchEffect. Instead there is another low-level API named effect. Its basic usage is just similar to watchEffect but more flexible and powerful.

For more details, I suggest you to read the source code directly:

https://github.com/vuejs/vue-next/tree/master/packages/reactivity

So you could even use these APIs in non-Vue related projects as you like.

From now on, you could think about it: with reactivity APIs, what else amazing stuff could you make? 😉

Benefit & caveats

So far we know how reactivity APIs work in Vue 3.0. Comparing to 2.x and earlier version, it:

Fully covers all kinds of mutations of data, like adding a new property to an object, setting a value to an index of an array, etc.
Fully support all new data structures, like Map and Set.
Has better performance.
It could be used as a standalone package.

So if you really need or love any of the above, maybe it's time to try.

At the same time, there are some caveats for you:

It only works on ES2015+
DO use refs for primitive values for keeping the reactivity.
The reactive proxy doesn't equal to the original data in JavaScript.

For more details, I prepared a cheat sheet on Gist below:

https://gist.github.com/Jinjiang/f795b943d4315a42077b7261caf25187

Also there are 2 more casual Codesandbox projects I test for myself previously. Maybe it's somehow a little bit useful:

for reactive, readonly, and markRaw: https://codesandbox.io/s/vue-reactivity-tests-1-jm3d4
for ref and computed: https://codesandbox.io/s/vue-reactivity-tests-2-vyykh

Further use cases

So far we know a lot of things about the reactivity system in Vue, from the early version to 3.0. Now it's time to show some use cases based on that.

Composition API

The first thing is definitely the Vue Composition API, which is new in 3.0. With reactivity APIs, we could organize our code logic more flexibly.

import { ref, reactive, readonly, markRaw, computed, toRefs } from 'vue'

export default {
  setup(props) {
    const counter = ref(0)
    const increment = () => counter.value++
    const proxy = reactive({ x: 1, y: 2 })
    const frozen = readonly({ x: 1, y: 2 })
    const oneTimeLargeData = markRaw({ ... })
    const isZero = computed(() => counter.value === 0)
    const propRefs = toRefs(props)

    // could use a,b,c,d,e,f in template and `this`
    return {
      a: counter,
      b: increment,
      c: proxy,
      d: frozen,
      e: oneTimeLargeData,
      f: isZero,
      ...propRefs
    }
  }
}

I don't wanna show more demos about that because they are already everywhere. But IMO, for a further benefit few people talking about is, previously in Vue 2.x and earlier, we are used to putting everything on this, when we:

Create reactive data for a component instance.
Access data/functions in the template.
Access data/functions outside the component instance, mostly it happens when we set a template ref on a sub Vue component.

All 3 things always happen together. That means maybe we just:

Would like to access something in the template, but don't need reactivity.
Would like to create reactive data, but don't use that in the template.

Vue Composition API elegantly decouples them out by 2 steps:

create reactive data;
decide what the template needs.

Btw, for public instance members, I think the potential problem is still there. However, it's not a big matter so far.

Also, there are some other benefits, including but not limited to:

Maintain reusable code without worrying about the naming conflict.
Gathering logically related code together, rather than gathering instance members together with the same option type.
Better and easier TypeScript support.

Also in Composition API, there are more APIs like provide()/inject(), lifecycle hooks, template refs, etc. For more about Composition API, please check out this URL: https://composition-api.vuejs.org/.

Cross-component state sharing

When sharing data between components. Reactivity APIs is also a good choice. We could even use them out of any Vue component, and finally use them into a Vue app, for example, with the composition APIs provide and inject:

// store.js
import { ref } from 'vue'

// use Symbol to avoid naming conflict
export const key = Symbol()

// create the store
export const createStore = () => {
  const counter = ref(0)
  const increment = () => counter.value++
  return { counter, increment }
}

// App.vue
import { provide } from 'vue'
import { key, createStore } from './store'

export default {
  setup() {
    // provide data first
    provide(key, createStore())
  }
}

// Foo.vue
import { inject } from 'vue'
import { key } from './store'

export default {
  setup() {
    // you could inject state with the key
    // and rename it before you pass it into the template
    const { counter } = inject(key)
    return { x: counter }
  }
}

// Bar.vue
import { inject } from 'vue'
import { key } from './store'

export default {
  setup() {
    // you could inject state with the key
    // and rename it before you pass it into the template
    const { increment } = inject(key)
    return { y: increment }
  }
}

https://codesandbox.io/s/vue-reactivity-shared-state-nkfc0

So once user call y() in Bar.vue, the x in Foo.vue would be updated as well. You don't even need any more state management library to do that. That's quite easy to use.

Remember vue-hooks?

It's not an active project anymore. But I remember after React Hooks first time announced, Evan, the creator of Vue, just gave a POC under Vue in 1 day with less than 100 lines of code.

Here is the live demo in Codesandbox:

https://codesandbox.io/s/jpqo566289

Why it could be done so easily with Vue. I think mostly because of the reactivity system in Vue. It already helps you done most of the job. What we need to do is just encapsulate them into a new pattern or more friendly APIs.

Writing React with Vue reactivity system

So let's try one more step POC. How about using Reactivity APIs in React to create React components?

import * as React from "react";
import { effect, reactive } from "@vue/reactivity";

const Vue = ({ setup, render }) => {
  const Comp = props => {
    const [renderResult, setRenderResult] = React.useState(null);
    const [reactiveProps] = React.useState(reactive({}));
    Object.assign(reactiveProps, props);
    React.useEffect(() => {
      const data = { ...setup(reactiveProps) };
      effect(() => setRenderResult(render(data)));
    }, []);
    return renderResult;
  };
  return Comp;
};

const Foo = Vue({
  setup: () => {
    const counter = ref(0);
    const increment = () => {
      counter.value++;
    };
    return { x: counter, y: increment };
  },
  render: ({ x, y }) => <h1 onClick={y}>Hello World {x.value}</h1>
});

https://codesandbox.io/s/react-vue-reactivity-evdll

I did a little test like above, it's not a full implementation. But somehow we could maintain a basic React component with 2 parts:

Pure data logic with reactivity.
Any data update would be observed and trigger component re-render.

Those correspond to setup and render functions as a Vue component does.

And there is no way to worry about whether or not I write a React hook outside a React component or inside a conditional block. Just code it as you like and make it happen as you imagine.

Final final conclusions

So that's all about the reactivity system in Vue, from early version to the latest 3.0 Beta. I'm still learning a lot of new stuff like programming languages, paradigms, frameworks, and ideas. They are all great and shining. But the reactivity system is always a powerful and elegant tool to help me solve all kinds of problems. And it's still keeping evolved.

With ES2015+, the new Reactivity APIs and its independent package, Composition APIs, Vue 3.0, and more amazing stuff in the ecosystem and community. Hope you could use them or get inspired from them, to build more great things much easier.

Hope you could know Vue and its reactivity system better through this article.

All the code samples in this article: https://gist.github.com/Jinjiang/f9b6f968af980cfd21cfc713e59db91b

DEV Community: Jinjiang

Understanding how Vite deals with your node_modules

Background

What is Vite?

"Every frontend project has a messy node_modules folder"

How did this article come about?

Basic usage

Setup

How to inspect 1: the node_modules/.vite/deps folder

How to inspect 2: the "Network" panel in browser DevTools

A small recap

A simple case with CJS and ESM

The case with module.exports = xxx in CJS

A small recap

Custom Dependency Pre-bundling

What is vite optimize and optimizeDeps config in Vite?

Why we need dependency optimization?

What is optimizeDeps config in Vite?

A small recap:

Advanced case: deep dependencies configuration

Basic SSR usage

Setup

What is ssr.external and ssr.noExternal config in Vite?

A simple case

How to inspect 3: the module evaluation process in SSR mode

Execution differences between "external" and "inlined" packages

Don't use named imports in an inlined file for an external module.exports CJS resource

Other relevant options

Advanced case: deep dependencies configuration

non-JS files in node_modules

A small recap:

What is ssr.optimizeDeps config in Vite?

A simple case

How to inspect 4: the node_modules/.vite/deps_ssr folder

A small recap

What if I add resolve.alias in Vite config?

A simple case

A small recap

What if I add resolve.dedupe in Vite config?

Fix the previous case

How does it work?

Another case with external resources

A small recap

The new way to config SSR mode: environments

How to deal with dependencies in Vitest?

Conclusion

Why I have to know so much details to use Vite?

Vlite - a lite demo server inspired by Vite

Usage

The idea

Target 1: ESM-friendly

Target 2: Simplifying the compilations

How it works?

A simple plugin system

Compiler choices

Conclusions and future plans

Understanding Reactivity in Vue 3.0

Background

What's reactivity?

Reactivity in Vue from 0.x to 1.x

Reactivity in Vue 2.x

Limitation of the reactivity system before 3.0

Reactivity system in Vue 3.0

Create a Vue 3.0 project

vitejs / vite

Next generation frontend tooling. It's fast!

Vite ⚡

Packages

Contribution

License

Sponsors

1. Adding new property

2. Assigning items to an array by index

3. Setting the length property of an array

4. Using ES Set/Map

5. Using non-reactive properties

How it works

First part: simple data observer

Second: more reactivity APIs

Additionally, a trial of using WeakMap to record deps and flags

"Every frontend project has a messy `node_modules` folder"

How to inspect 1: the `node_modules/.vite/deps` folder

The case with `module.exports = xxx` in CJS

What is `vite optimize` and `optimizeDeps` config in Vite?

What is `optimizeDeps` config in Vite?

What is `ssr.external` and `ssr.noExternal` config in Vite?

Don't use named imports in an inlined file for an external `module.exports` CJS resource

non-JS files in `node_modules`

What is `ssr.optimizeDeps` config in Vite?

How to inspect 4: the `node_modules/.vite/deps_ssr` folder

What if I add `resolve.alias` in Vite config?

What if I add `resolve.dedupe` in Vite config?

The new way to config SSR mode: `environments`

1.1 Basic: `reactive(data)`, `readonly(data)`, `markRaw(data)`

1.2 Utils: `isReactive(data)`, `isReadonly(data)`, `isProxy(data)`, `toRaw(data)`

1.3 Advanced: `shallowReactive(data)`, `shallowReadonly(data)`

2.1 Basic: `ref(data)`

2.2 Utils: `isRef(data)`, `unref(data)`

2.3 Proxy to ref: `toRef(data, key)`, `toRefs(data)`

2.4 Advanced: `shallowRef(data)`

Case: `computed(…)`

Case: `customRef(…)`

`watchEffect(function)`, `watch(deps, callback)`