More docs about externals inlining

[Gwynerva]

Environment

Nitro 2.11.8

Reproduction

https://github.com/Gwynerva/nitro-alias-bug

pnpm i
cd packages/nitro-app
pnpm nitro dev

Describe the bug

Nitro does not to recognize aliases defined in nitro.config.ts in files from external dependencies. When it meets aliases in such external files, it treats them as external dependencies, throwing an error.

@pi0 explained the context:

Any code that needs import aliases to work needs to be bundled and not externalized. By default, Nitro externalizes all node modules for performance reasons. We need to manually enlist these patterns.

Workaround

The only way to solve this issue for now is to manually tell Nitro to inline modules that use imports with aliases:

// nitro.config.ts

import { resolve } from "node:path";

export default defineNitroConfig({
  compatibilityDate: "2025-03-01",
  srcDir: "server",
  alias: {
    "@shared": resolve(__dirname, "./shared"),
  },
  externals: {
      inline: [
        /packages\/lib/
      ],
  },
});

Additional context

Original issue in Nuxt repo:

https://github.com/nuxt/nuxt/issues/31616

[Gwynerva]

@pi0 The workaround you provided works!

But, it would be cool if you explain in details what type of "path" exactly should be in inline property. Are they JS import patterns or absolute file paths?

For example, I have package @erudit-js/bitran-elements. In dev monorepo it is located in /packages/bitran-elements directory. In production, it will be located in /node_modules/@erudit-js/bitran-elements directory.

What and why should be written in inline for Nitro to properly inline it in both situations? For now I use just /bitran-elements/ which 100% covers both situations but I would like to know why setting /@erudit-js\/bitran-elements/ is not working in monorepo.