NX Workspace

[webberwang]

Bundling

• Started with path alias, but this is still treated as 1 giant bundle

• Project references is the way to go, for incremental bundle, treated as individual bundle. This was added later on

• https://nx.dev/blog/managing-ts-packages-in-monorepos

• https://nx.dev/blog/new-nx-experience-for-typescript-monorepos

Module Resolution

• PNPM workspace integration with NX was done later on, which removed need for path alias
• Used pnpm package linking for module resolution
• Each app need to have package.json with devDependencies that reference local package per pnpm

---

For extending package imports, we use use package.json only it seems without modifying tsconfig.json

{
  "name": "@myorg/ui",
  "exports": {
    ".": {
      "types": "./src/index.ts",
      "import": "./src/index.ts",
      "default": "./src/index.ts"
    },
    "./some-path": {
      "types": "./src/some-path/index.ts",
      "import": "./src/some-path/index.ts",
      "default": "./src/some-path/index.ts"
    }
  }
}

• https://nx.dev/blog/managing-ts-packages-in-monorepos#using-relative-imports

---

We migrated over the project reference, but found

• https://nx.dev/blog/managing-ts-packages-in-monorepos#using-relative-imports

Modularity:
Each package's package.json defines its public API and dependencies, making the structure explicit and easy to understand. One important detail is that in our example the package.json directly exports TypeScript files, making the consumer responsible for transpilation and bundling. As a result, these libraries are primarily intended for local use within the monorepo workspace.

• https://nx.dev/concepts/typescript-project-linking

ESLint

apps/web/tsconfig.json contains a references array, so TypeScript treats it as a “solution‑style” file whose main job is to point at sub‑projects (tsconfig.lib.json, tsconfig.spec.json, …).
• At the same time it still has an include list with **/*.tsx, so TypeScript also sees it as a real source project.
• When a file (e.g. app/(dashboard)/(authenticated)/admin/default.tsx) is seen in both the root project and one of the referenced projects, the compiler deduplicates it and keeps it only in the referenced project.
Result: the Program built from tsconfig.json no longer contains that file, so TypeScript‑ESLint throws
“TSConfig does not include this file”.
This behaviour is documented in the TypeScript repo; the common fix is to empty out include/files in the solution config so it’s only an aggregator

    "project": ["apps/web/tsconfig(.*)?.json"] needs to be         "project": ["apps/web/tsconfig(.*).json"], so we don't match the solution-style file tsconfig.json, since it has references

ESM

After a few days of research I was able to understand a little more about the difference between module and moduleResolution in tsconfig settings. It seems that even putting moduleResolution: "node" the typescript understands it as if it were CommonJS. To be interpreted as ESM moduleResolution has to be set to "NodeNext" in typescript versions 4.5 onwards. So to convert my whole project to ESM I defined "type": "module" in the package.json file as well. A better explanation:

client server schema

I just ran into the same error and think I know what's going on. If you have a server action or a server component that imports a zod schema from a file that is a marked as a client component or client entry point, it will throw an error. If you move the schema declaration to a seperate file that only runs on the server, or make the file containing the schema a server component it should fix it. You should then be able to import the schema and use it from a client or server component.

I'm running into lots of problem like this when working with server components and passing data to client components. Particularly with tanstack table and their create column helper.

typecheck

• This actually generates the tsbuildinfo file, it runs tsc noEmit to check for type
• This is perfect when another tool (Vite + esbuild, SWC, Babel, etc.) will handle transpiling, and you only want static type safety.

buildLibsFromSource

For nextjs dev it's better to have turbopack compile everything, it's quite fast. The issue we're having now is production build on CI, it's quite slow.

If we turn buildLibsFromSource off, then have vite build the libs, it will be much faster

---

If we want to use buildable libs, the entire import chain need to be buildable as well.

---

Old way

  "main": "./dist/index.js",
  "module": "./dist/index.js",
  "types": "./dist/index.d.ts"

Preferred way to use exports, more encapsulation

---

• tsc with allowJs reports TS9005 error for anonymous constructor functions microsoft/TypeScript#55172
• need to turn allowJs off
• declarationMap on will trigger more errors, but needed for buildable libs
• Note that the above will only work when not generating declaration maps. If you need to generate declarations (for example for a library) then it is a bit more tedious, but still possible:
• https://mobx-keystone.js.org/class-models/#factory-pattern--generics

No —declaration maps ("declaration": true + "declarationMap": true) and type-inference can live together.
What breaks is not “inference in general,” but exporting a value whose inferred public type leaks private, non-exported stuff.

---

• The next issue we're facing now is that even though we're building the libraries correctly, the IDE will pick up the dist files during development.
• We have TypeScript references set up, and they are using package.json to pick up the files, and it's currently picking up the dist files since we are using buildables.
• But using dist in development will not allow us to pick up the source files, which is where conditional exports come in.

---

When do we typecheck, it builds the tsbuildinfo which is placed according to rootDir. We cannot specify both rootDir and rootDirs in base.

when you don't set rootDir, the compiler infers it, rootDir = the longest common directory that is a prefix of every source file the compiler will emit for this program. So the shortest path in files. Since we added vite.config.ts, it removed src as the rootDir.

---

• customConditions is a tsc compile concept, while package.json exports is a bundler
• Because every library is only used inside the same pnpm workspace, emitting dist is optional. Stick with non-buildable libs for the quick inner-loop, enable buildable (and call nx build) only where a pre-compiled JS bundle or CI speed-up really pays off.
• Issue is we can't bundle lib with use server and use client, even the import preserveDirectives from 'rollup-preserve-directives' fails when an import chain has both directives, they are both added
• apparently if we have outDir in lib specified, the next bundler will lok there to load files
• The packages are linked via pnpm workspace, could this let next builder load from dist

---

• Issue with bundle is that we can't compile to single file, need to preserve module
• Rollup react component for next.js project rollup/rollup#5100

---

• package.json # exports doesn’t influence how TypeScript picks up a library that is marked "composite": true
• "composite": true + "outDir": "./dist"
• buildLibsFromSource stops Nx from running extra build tasks; it does not override the TypeScript project-reference contract that a composite library advertises.
• "exports": { ".": { "default": "./src/index.ts" } } is honored only at runtime (by Node ≥ 12, bundlers, and webpack when it resolves your import).
  The TypeScript compiler never consults that field when the library is referenced through a project-reference.

---

• If we have references it will trigger composite build and read from dist
• Vite outpath goes in dist, so we should change our vite config around that

---

• when building lib, getting error of missing d.ts in outDir
• but outDir out-tsc is used by tsc, in our case has noEmit, so no files will be generated here. our vite is the one producing the d.ts, but it uses a separate outdir

---

pnpm workspace linking

• Be careful of workspace linking, the pnpm-workspace.yaml had incorrect syntax for exclusion, used excludes key instead of !

• This looked under dist as a workspace and pnpm install used the dist files to link as pnpm workspace

• If we want to remove project.json, the output will go to dist folder

• which means the exports field will need to change (may be able to change with inferred config path)

• inferred js not working if isValidPackageJsonBuildConfig not true, meaning package.json can't reference any dist path

---

To use inferred, @nx/js/typescript creates build, but we want @nx/js:tsc if we want to copy assets, so we add to targets build in package.json. Then we set some defaults for targetDefaults

• custom conditions also need to be added to eslint plugin for import/resolver, otherwise it will use dist folder

---

Even though the package.json exports map has a development condition pointing to src, the TypeScript project reference mechanism, especially with composite: true, often relies on the outDir specified in the referenced project's tsconfig. It uses the tsBuildInfoFile to track the relationship between source and output files. The error arises because the build info likely indicates that dist/index.d.ts should correspond to src/index.ts, but it's either missing or older than the source.

What’s going on internally
1. composite: true implicitly turns on declaration: true and makes the compiler treat the declarations as the public contract of the project. 
2. When the resolver sees moduleResolution: nodenext/bundler, it does load the exports map but it first checks whether it is looking for “the emitted declarations of a composite project”. If so, it jumps straight to and ignores the rest of the conditions.
3. customConditions is therefore skipped; the development branch is never evaluated.

composite: true tells TypeScript that this project’s declarations (.d.ts in outDir) are the public API

• So moving outDir outside makes ide read from source files instead of outDir, but during tsc build it still needs it

---

Solution style tsconfig.json should not include lib, since lib is used for build only. only reference dev should we use for ide

[webberwang]

tsconfig path	extends	main role in the stack	key compilerOptions set here
tsconfig.base.json	–	Repo-wide defaults (never emits JS)	target, module, moduleResolution, strict, skipLibCheck, noEmit, lib, allowSyntheticDefaultImports, esModuleInterop, forceConsistentCasingInFileNames
tsconfig.build.base.json	./tsconfig.base.json	Common build flags for every library / app build	composite, incremental, declaration, declarationMap, sourceMap
libs/core/tsconfig.json	../../tsconfig.base.json	Solution-style file opened by the IDE; only lists references	disableReferencedProjectLoad, noEmit
libs/core/tsconfig.lib.json	../../tsconfig.build.base.json	Build config for the library (nx build / tsc --build)	outDir, rootDir, include, references
libs/core/tsconfig.dev.json	./tsconfig.lib.json	Dev-only type-checking (same rules as build, but never emits)	noEmit, incremental: false
libs/core/tsconfig.spec.json	./tsconfig.lib.json	Unit-test config (not referenced by solution to keep IDE fast)	noEmit, types, exclude

option	put it in…	why
target: "es2021"	tsconfig.base.json	Your whole workspace should compile to the same ECMAScript version. Keep it once at the root so every config inherits it.
types: ["node"]	tsconfig.build.base.json (or in a lib)	Build outputs often rely on Node globals (Buffer, process). If every package is server-side, set it in the build preset; otherwise keep it only in libraries that touch Node APIs.
declaration: true	tsconfig.build.base.json	Part of the “emit” tool-chain; the IDE doesn’t need it, but every tsc --build should produce .d.ts.
strict (or the granular flags below)	tsconfig.base.json	Lint-level rules that apply everywhere belong at the repo root so they’re enforced consistently.
strictNullChecks, noImplicitAny, strictBindCallApply, noFallthroughCasesInSwitch, noImplicitOverride, noPropertyAccessFromIndexSignature, noImplicitReturns, forceConsistentCasingInFileNames	tsconfig.base.json	All of these are already enabled automatically when you set "strict": true, except noFallthroughCasesInSwitch and noImplicitReturns—add those two explicitly next to strict if you want them.

---

Example contents

// tsconfig.base.json
{
"compilerOptions": {
"target": "ES2022",
"module": "ESNext",
"moduleResolution": "Node16",
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true,
"allowSyntheticDefaultImports": true,
"esModuleInterop": true,
"lib": ["ES2022", "DOM"],
"noEmit": true
}
}

// tsconfig.build.base.json
{
"extends": "./tsconfig.base.json",
"compilerOptions": {
"composite": true,
"incremental": true,
"declaration": true,
"declarationMap": true,
"sourceMap": true
}
}

// libs/core/tsconfig.json (solution file)
{
"extends": "../../tsconfig.base.json",
"compilerOptions": {
"disableReferencedProjectLoad": true,
"noEmit": true
},
"files": [],
"references": [{ "path": "./tsconfig.dev.json" }]
}

// libs/core/tsconfig.lib.json
{
"extends": "../../tsconfig.build.base.json",
"compilerOptions": {
"outDir": "../../dist/libs/core",
"rootDir": "./src"
},
"include": ["src/**/*"],
"references": [{ "path": "./tsconfig.dev.json" }]
}

// libs/core/tsconfig.dev.json
{
"extends": "./tsconfig.lib.json",
"compilerOptions": {
"noEmit": true,
"incremental": false
}
}

// libs/core/tsconfig.spec.json
{
"extends": "./tsconfig.lib.json",
"compilerOptions": {
"noEmit": true,
"types": ["jest", "node"]
},
"exclude": ["dist", "**/*.d.ts"]
}

Tips if save-time re-checking still feels slow
1. Keep tests in their own project (tsconfig.spec.json) and don’t reference it from the dev config.
2. Turn on incremental build metadata in large packages:

---

• For eslint, the projectService: true does work with solution style, but the tsconfig.dev.json need to have allowJs and include js. For build we don't do js but dev should have it