How the auto importer works

[brillout]

⚠️ This is for expert users who want to know how the auto importer works. Do NOT read this if you merely want to solve your problem, see the README instead.

The auto importer uses two tricks to automagically load your server build. (I.e. to automagically load your server files built at dist/server/, or ${build.outDir}/server in case you use vite.config.js#build.outDir.)

Trick 1

Trick 1: @brillout/vite-plugin-server-entry generates a file that automatically imports dist/server/entry.js on your behalf:

// node_modules/@brillout/vite-plugin-server-entry/dist/importServerEntry/autoImporter.js

require('../../../../dist/server/entry.js');

If you use vite.config.js#build.outDir, then the path is generated accordingly. (I.e. dist/ is replaced with your build.outDir value.)

The dist/server/entry.js file is generated by @brillout/vite-plugin-server-entry and acts as the entry of the server build.

But this trick doesn't work:

• If you install npm packages after you build your app (i.e. after running $ vite build).

  Because @brillout/vite-plugin-server-entry generates node_modules/@brillout/vite-plugin-server-entry/dist/importServerEntry/autoImporter.js at build-time (when running $ vite build). So, if we $ rm -r node_modules/ && npm install, then the generated file node_modules/@brillout/vite-plugin-server-entry/dist/importServerEntry/autoImporter.js is erased.

• When using Yarn PnP which installs dependencies in an immutable way.

  Because @brillout/vite-plugin-server-entry cannot generate node_modules/@brillout/vite-plugin-server-entry/dist/importServerEntry/autoImporter.js.

In theses situations, @brillout/vite-plugin-server-entry uses a second trick.

Trick 2

Trick 2: @brillout/vite-plugin-server-entry dynamically searches for and loads dist/server/entry.js.

But that doesn't work:

• If you use vite.config.js#build.outDir.

  Because the config values set by vite.config.js aren't available to the production runtime. (The vite.config.js configuration is meant for transpilation, not for the production runtime.) Thus the build.outDir value is unknown to the production runtime.

• In edge environments where dynamically importing modules isn't possible (e.g. Cloudflare Workers).
• If you want to bundle all our server code into a single file.

Fallback

If both tricks don't work, then you can fallback to manually importing dist/server/entry.js, as described in the README.

You need the fallback only if both tricks 1 and trick 2 don't work which, all-in-all, is a rare situation.