Understanding why foo is mapped to foo/src in the nextjs branch

[PaulRBerg]

I was looking at the nextjs branch, specifically at the tsconfig.json file in packages/nextjs:

ts-monorepo/packages/nextjs/tsconfig.json

Lines 11 to 14 in 0ad8608

	"paths": {
	"foo": ["foo/src"],
	"components": ["components/src"]
	},

And I'm trying to understand why you have remapped foo to foo/src, and components to components/src. Shouldn't these packages be built and loaded from dist? Or did you have to do this because Next.js doesn't support TypeScript project references?

I also don't understand how the external dependencies of foo and components are resolved when building the Next.js app. Does this rely upon node_modules being hoisted at the root?

Side note: would you like to enable GitHub Discussions in this repository? I would have created a discussion instead of a repo.

[NiGhTTraX]

@PaulRBerg the nextjs branch is quite old , the latest NextJS example is under apps/nextjs.

Every example in apps/* uses path aliases to load dependencies from the monorepo source code, instead of from build artifacts, both when building and when running e.g. dev servers. This doesn't rely on node_modules symlinks, but on TypeScript's resolution mechanisms, and makes "Go to definition" work as expected.

Examples in packages/* do use node_modules symlinks to build artifacts, but only when building. See also https://github.com/NiGhTTraX/ts-monorepo/tree/1ee87c100a3bd65ebae4eb000c76354532f70c09#packages-vs-apps.

[PaulRBerg]

Super clear answer, thanks, Andrei!

Two follow-up questions:

1. Why not import the built packages even in the apps? Especially when those packages are meant to be published, wouldn't it be better to use the actual, published code in the app build, too?
2. Shouldn't the Next.js integration be updated to use externalDir instead of that custom Webpack override?

[NiGhTTraX]

1. For most setups I would recommend using the source code (via path aliases) so you can get hot reloads when making changes to dependencies. Using the build output would require building the dependencies and then restarting NextJS to see the changes. I would only recommend doing that if you want different compiler settings for each, since with the path aliases approach everything will be compiled with the NextJS tsconfig. If you have e.g. mismatching strict configs, or types that you don't want polluting other projects, then different builds are the way to go (at the cost of degrading DX).
2. That feature is still experimental and, under the hood, does exactly what the README example shows. I still document it in the next.config.js though.

[PaulRBerg]

That makes complete sense for development modes (hot reloading and so on), but I don't follow why the DX would be degraded in any way whatsoever for production builds? I could just rely on Lerna to build all other packages topologically.

Especially when the deployment pipeline is on a CI/CD platform, the topological builds are abstracted away.

[PaulRBerg]

I think I have found one reason myself: importing the built packages in the apps does not work if one of the packages uses its own paths. For those paths to work in dist, the package itself has to be compiled with smth like resolve-tspaths or typescript-transform-paths.

[NiGhTTraX]

I don't follow why the DX would be degraded in any way whatsoever for production builds

It wouldn't if you mixed both approaches. You can use path aliases in development and build from artifacts, and this would be beneficial in case you have many apps that depend on common packages and you don't want to compile the common packages every time. Compiling in topological order (with lerna, pnpm, yarn etc.) would speed things up, but it's worth comparing the improvements to the potential cost of having 2 build process (1 for local dev, 1 for building/deploying). Things could get out of sync and cause subtle problems. There's no right answer here though and you can start with 1 approach and then migrate to the other as circumstances dictate.

importing the built packages in the apps does not work if one of the packages uses its own paths

It should work if things are built in topological order and the package manager sets up the proper node_modules symlinks.

Deleting this path alias that's used to resolve @nighttrax/foo from cra/app.tsx and running the root build script builds everything correctly.

If you run ./node_modules/.bin/tsc --traceResolution --noEmit in examples/cra you can see the resolution mechanism in action when it loads @components which depends on @foo:

`@components` is resolved before via a path alias (omitted here), and `@foo` is resolved via `node_modules`.

======== Resolving module '@nighttrax/foo' from '/ts-monorepo/packages/components/src/button.tsx'. ========
...
Found 'package.json' at '/ts-monorepo/packages/components/node_modules/@nighttrax/foo/package.json'.
...
'package.json' has 'types' field 'dist/index' that references '/ts-monorepo/packages/components/node_modules/@nighttrax/foo/dist/index'.
...
Loading module as file / folder, candidate module location '/ts-monorepo/packages/components/node_modules/@nighttrax/foo/dist/index', target file type 'TypeScript'.
...
File '/ts-monorepo/packages/components/node_modules/@nighttrax/foo/dist/index.d.ts' exist - use it as a name resolution result.
Resolving real path for '/ts-monorepo/packages/components/node_modules/@nighttrax/foo/dist/index.d.ts', result '/ts-monorepo/packages/foo/dist/index.d.ts'.
======== Module name '@nighttrax/foo' was successfully resolved to '/ts-monorepo/packages/foo/dist/index.d.ts' with Package ID '@nighttrax/foo/dist/index.d.ts@1.0.0'. ========

[PaulRBerg]

Thanks for sharing your knowledge, ser.

Paul: importing the built packages in the apps does not work if one of the packages uses its own paths

Andrei: It should work if things are built in topological order and the package manager sets up the proper node_modules symlinks.
...
Deleting this path alias that's used to resolve @nighttrax/foo from cra/app.tsx

That's right, but I was referring to a different (hypothetical) scenario, one in which @foo would have its own path aliases and its tsconfig.json file would contain smth like this:

{
  "extends": "../../tsconfig.json",
  "compilerOptions": {
      "baseUrl": ".",
      "paths": {
           "~/foo/*": ["./src/*"]
       }
  }
}

Of course, this is overkill for your template, but I have a monorepo with a shared components package that uses a self-referential path like this.

--traceResolution

Sick! TIL

[NiGhTTraX]

Yes, internal aliasing will not produce usable build artifacts without an additional transformer. Even consuming it via another package/app that uses path aliases requires hoisting the internal aliases to that package.

[PaulRBerg]

Even consuming it via another package/app that uses path aliases requires hoisting the internal aliases to that package

Indeed. Just learned that the hard way today 😄

[PaulRBerg]

Circling back on this:

it's worth comparing the improvements to the potential cost of having 2 build process (1 for local dev, 1 for building/deploying) ... There's no right answer here though

There might actually be an objectively right answer for Next.js, and that is to do what you suggested, i.e. use only one TSConfig file for both building and deploying.

Next.js doesn't accept custom TSConfig file names - it defaults to tsconfig.json, and it doesn't let you change it.

[NiGhTTraX]

That's unfortunate, but thanks for sharing! You could hack around it by mutating the webpack config and removing config.resolve.plugins[0] (which is the path aliases plugin) if you're creating a production build.