Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

TypeScript cannot find another package in the same npm workspace

ErrorError: Cannot find module '@my-org/shared'

Short answer

In an npm workspace a sibling package is found through a symlink in the root node_modules. TypeScript then reads that package's types from its build output. So the failure is a missing link, a package outside the workspaces list, or an output nobody built. Check each in that order.

  • Applies to npm 10, TypeScript 5.x, Node.js 22
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    See whether npm linked the sibling package into the root node_modules.

    ls -l node_modules/@my-org/
  2. 2Match what you see, then jump to its fix

    1. 1ls shows no symlink for the packageThe package is not listed in workspaces, or npm install was not rerunFix
    2. 2The symlink is there, but TS2307 remains and the package's dist folder is empty or missingThe sibling package has not been built, so its type output does not existFix
    3. 3tsc -b does not build the shared package, or reports files not matched by includeProject references are missing or the shared project is not compositeFix

What does the error look like?

  • Error: Cannot find module '@my-org/shared'
  • MODULE_NOT_FOUND

Cause 1 of 3

The package is not listed in workspaces, or npm install was not rerun

1Check

npm links only folders matched by the workspaces field in the root package.json, and only when install runs from the root.

grep -n "workspaces" -A4 package.json
cat packages/shared/package.json | grep '"name"'

2Fix

Add the folder to workspaces, make sure its package.json name matches what you import, and install from the root.

# root package.json
"workspaces": ["packages/*"]

npm install

3Verify

The package should now be a symlink pointing into packages/.

ls -l node_modules/@my-org/

Confirmed by docs.npmjs.com

Did this fix it?

Cause 2 of 3

The sibling package has not been built, so its type output does not exist

1Check

Importing from a referenced project loads its generated .d.ts output, not its source. Look for the output folder.

ls packages/shared/dist

2Fix

Build the shared package first, or build the whole graph in order with tsc --build.

npx tsc -b packages/app

3Verify

Run the type check again.

npx tsc -b --verbose packages/app

Confirmed by typescriptlang.org

Did this fix it?

Cause 3 of 3

Project references are missing or the shared project is not composite

1Check

A referenced project needs composite enabled, which also forces declaration output. Plain tsc does not build referenced projects.

grep -n "composite\|references" packages/*/tsconfig.json

2Fix

Enable composite in the shared project and list it under references in the consumer, then build with tsc -b.

// packages/shared/tsconfig.json
{ "compilerOptions": { "composite": true, "declaration": true, "outDir": "dist" }, "include": ["src"] }

// packages/app/tsconfig.json
{ "references": [{ "path": "../shared" }] }

3Verify

Build everything from the app project.

npx tsc -b packages/app

Confirmed by typescriptlang.org

Did this fix it?

How do I stop it coming back?

  • Run npm install at the repository root, never inside one package.
  • Make tsc --build the single build command in CI, so build order is never manual.
  • Keep the name field of each package equal to the import path used by its consumers.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

cdk synth says --app is required

--app is required either in command-line, in cdk.json or in ~/.cdk.json

The CDK CLI needs a command that runs your app and finds it in three places: the --app option, cdk.json in the project folder, or cdk.json in your home folder.

3 causes, each with a fix

Back end

Mocha or Node cannot find ts-node/register

Error: Cannot find module 'ts-node/register'

Node resolves ts-node/register from your project's node_modules, so the package must be installed there, next to typescript.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.