TypeScript "paths" in monorepo

[steveruizok]

Let's say I want to use typescript's "paths" to simplify my imports. I'll use the current starter project as an example, with the idea to use path aliases in the ui folder.

Here's the CodeSandbox showing the issue.

In the ui folder's .tsconfig, I'll add:

// ui/tsconfig.json

{
  "extends": "tsconfig/react-library.json",
  "include": ["."],
  "exclude": ["dist", "build", "node_modules"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~*": ["./*"]
    }
  }
}

Then I could import button like this:

// ui/components/ButtonB.tsx

import * as React from "react"
import { ButtonA } from "~components/ButtonA"
export const ButtonB = () => {
  return <ButtonA />
}

However, in the apps that consume this ui library (docs and web) the imports break as those projects don't understand the path alias:

// from docs/pages/index.tsx

../../packages/ui/components/ButtonB.tsx:4:0
Module not found: Can't resolve '~components/ButtonA'
  2 | 
  3 | import * as React from "react"
> 4 | import { ButtonA } from "~components/ButtonA"
  5 | export const ButtonB = () => {
  6 |   return <ButtonA />
  7 | }

Import trace for requested module:
../../packages/ui/components/index.ts
../../packages/ui/index.tsx
./pages/index.tsx

Any ideas?

One solution: build ui

By default, there's no build process or watcher on the ui package—it's just consumed directly by the docs and web apps. However, I could use tsup to build the package, which would and create a .d.ts file and resolve the path aliases. That works! CodeSandbox here.

Is there a more simple way?

[mfpopa]

To eliminate the build step, you need add the paths from ui/tsconfig.json in the tsconfig of docs and web projects like this:

{
  "extends": "tsconfig/nextjs.json",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"],
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "~*": ["../../packages/ui/src/*"]
    }
  }
}

Next.js is smart enough to pick up the paths automatically from the tsconfig.json file, just remember to restart the Next.js server after each change made to tsconfig.json.

Also make sure you have the main and types properties in the ui package set to the index.tsx file since you no longer have the build step to create the index.js in the dist folder.

You can also use the same path alias for the docs and web apps if you want. Just modify the ~ path alias to "~*": ["../../packages/ui/src/*", "./*"], then you can do imports like import { UserProfilePage } from '~pages/users' inside the apps.

[maipato10]

Forgive me for my ignorance.

It seems that a similar issue cropped up where, if using vite (kitchen sink example), the "extends": "tsconfig/vite.json" inside of the admin folder (tsconfig.json file) throws a typescript error that I can't seem to resolve. Even though I've looked around and even tried the with-vite specific example project (which throws the same error).

The specific error message is: Path to base configuration file to inherit from. Requires TypeScript version 2.1 or later. File 'tsconfig/vite.json' not found.ts

If possible I would love an explanation as to why this is an issue. Being quite new to messing around with configs overall.

After some digging around I noticed that the example works fine with npm. It seems pnpm, for some reason is running an older version of typescript.

I am having the same issue, was it resolved?

[daabe3]

Yes. See the last paragraph of my comment! I had to opt for npm to not have to deal with the issue. The reasoning being that as far as I've heard, npm is planning to implement a similar algorithm as pnpm in the future.

[bestickley]

You can also use the same path alias for the docs and web apps if you want

From original answer, I don't think that is true. You need unique tsconfig paths aliases for each project. See the second part of @mfpopa's answer below.

[T04435]

First of all THANKS @mfpopa

I have merged the paths config into the tsconfig/nextjs.json, to DRY it. So far so good.

  //... DEFAULT
  "baseUrl": ".",
  "paths": {
    "@ui/*": ["../../packages/ui/*"]
  }
    ```

[EfstathiadisD]

Guys. Question here. How is this a solution? In a Monorepo, we put baseUrl and paths in the root TSConfig. Why? Cause paths aren't merging their props. Meaning, if you have a key of paths in a project inside a monorepo it will override the root one.

Also, the concept of relative for inner imports and absolute path imports for outer ones is quite enforced in the community and tbh the correct one. Until TS decide to repair the decision they took early on re. this matter.

How is it acceptable to do this just for Next? It's been a Year since 13, we are now at 14, and this is still an issue and that is the solution? Just for Next? Even in traditional Webpack configs we never had to do this.

Is there another altenative? I don't mind having to maintain some code in more than one apps. Unless it impacts performance..Thank you!

[mfpopa]

For anyone working on CSR apps and use bundlers like webpack, vite, rollup, etc. make sure to configure them to understand the aliases.

Important note on vite and rollup. They do not accept an array of paths for each alias, so we are forced to use a unique alias for each path. Namely, if I use "@/*": ["./src/*"] inside my packages/ui/tsconfig.json package and then have "@/*": ["./src/*", "../../packages/ui/src/*"] inside apps/web/tsconfig.json, typescript will be happy, but vite/rollup will not because we cannot setup aliases that accept an array of paths. Neither of the two options below work.

resolve: {
    alias: [
      {
        find: '@',
        replacement: [path.resolve(__dirname, 'src'), path.resolve(__dirname, '../../packages/ui/src')], // replacement property expect a string, not array
      },
    ],
  },

// OR alias set as object
resolve: {
    alias: {
      '@': [path.resolve(__dirname, 'src'), path.resolve(__dirname, '../../packages/ui/src')],  // Error: Type 'string[]' is not assignable to type 'string'.
    },
  },

---

The only way to make this work is to have different internal aliases for each project. For example, I used @ui for ui package and @ for apps because they do not get imported into other projects (packages or apps).

// packages/ui/tsconfig.json
{
  "extends": "@config/tsconfig.react.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@ui/*": ["./src/*"] // no other project in the monorepo uses this alias
    }
  },
  "include": ["."]
}

// apps/web/tsconfig.json
{
  "extends": "@config/tsconfig.react.json",
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@ui/*": ["../../packages/ui/src/*"]
    }
  },
  "exclude": ["node_modules", "public"],
  "include": ["."]
}

// apps/web/vite.config.ts
// ... left out irrelevant part of the vite config
resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@ui': path.resolve(__dirname, '../../packages/ui/src'),
    },
  },

// apps/web/src/App.tsx
import { Button } from '@ui'; // import from ui package
import { AppLayout } from '@/layouts'; // internal import using alias for apps/web/src/layouts path

export function App() {
  return (
    <AppLayout>
      <h1>My Web App</h1>
      <Button onClick={() => alert('You clicked me!')}>Click Me</Button>
    </AppLayout>
  )
}

[lucaschultz]

This worked for me, thank you so much 👍

[jwenger100]

You rock, thank you for this. @mfpopa

[citypaul]

This feels like such an obvious solution, but I hadn't thought of it at all. Thanks for this, you're a life saver!

[mayvagio2016]

In my personal opinion, this solution is like anti-pattern in Monorepo. Instead of configs path aliases , we can use the ui repo as a dependency (e.g: pnpm add ui-repo --filter web from apps/web)

[npearson72]

Some of the proposed solutions will clearly work, but they feel dirty because they couple the packages with the apps in a way that exposes implementation details. Ideally the packages (and app for that matter) could be extracted and used as independent libraries. There's even an option for this in Turbo call prune. But dipping into knowledge of paths across package boundaries would make extraction messy.

Surely there must be a better way? Perhaps Turbo can introduce a middleware that analyzes these paths and generates a mapping that's tucked away somewhere much like the cache is.

[jmroon]

There's nothing stopping you from having your cake and eating it too. One app can use a lib through ts path aliases and another can import through pnpm workspace node_modules. If you just want to import a built lib, you can just have your libs package.json point to the lib's build dist/ output and pnpm will pick that up with workspaces.

[lveillard]

I have a similar case. Before turborepo it was enought to add

"baseUrl": "./src",

to tsconfig's compiler options and get rid of all the ../../../../something paths.
It does not seem to work like this with the monorepo.

[jmroon]

This isn't turbo. Not sure how Next works, but Vite can't do absolute path imports...only aliases work.

[Nikola-Milovic]

You can checkout my repo on how I approached this setup, not sure it's the best but it seems to work as one would expect. ( The repo is made to reproduce typing issue with tRPC not sure if thats related to the way monorepo handles code sharing)

The repository can be found here, there's a readme with brief overview of the directories

Feedback is welcome!

[lveillard]

Thanks for the example!
However, for some reason adding "@/*": ["./src/*"] is useless in my repo

[acnicolasdc]

same 👎

[un33k]

Simply add the paths to packages/tsconfig/base.json and they will become available everywhere else.

Here is how:
packages/tsconfig/base.json

{
  "$schema": "https://json.schemastore.org/tsconfig",
  "display": "Default",
  "compilerOptions": {
    "...": "other options",
    "baseUrl": ".",
    "paths": {
      "@web/ui": ["../ui/index.tsx"],
      "@docs/ui": ["../ui/index.tsx"]
    }
  },
  "exclude": ["node_modules"]
}

Usage:
apps/docs/pages/index.tsx

import { Button } from "@docs/ui";

apps/web/pages/index.tsx

import { Button } from "@web/ui";

Note: in this example both docs and web ui point to the same ui, but in real life scenario, you can have mobile-ui, web-ui etc.

Note: 'baseUrl' is required. This works great. Build and VsCode are booth happy.

[jmroon]

That's a good strategy if you don't want any aliases within your apps. Say you want a root @/ alias in your app, you can't do it using this implementation since extending tsconfig won't merge the paths, it will overwrite them.

As much as I wish it worked that way, I think the better approach is what @mfpopa posted. Since turbo doesn't have any kind of monorepo access management like NX does, this at least solidified the contract between apps and libs so as not to accidentally import from paths you shouldn't.

[airtonix]

this is how NX.dev will set things up for you by the way.

package.json
tsconfig.base.json
pkgs/
  ui/
    button/
      tsconfig.json
      tsconfig.spec.json
      tsconfig.lib.json
      project.json
      src/
        index.ts

pkgs/ui/button/tsconfig.json

{
  "extends": "../../../tsconfig.base.json",
  // ...
}

tsconfig.base.json

{
  "compilerOptions": {
    // ...
    paths: {
      "@the-monorepo/ui-button": [
        "./pkgs/ui/button/src/index.ts"
      ]
    }
    // ...
  }
}

funny to see that a proposed monorepo that claims to be better than all the rest still has many problems to solve.

[jmroon]

While I don't think this is on Turbo to fix, I do wonder why the official docs suggest importing packages through workspaces That had me thinking...do the caching mechanisms break for internal dependencies if you're importing through tsconfig paths? Say I have:

- apps
    - app1 -> depends on ui through tsconfig path import
- packages
    - ui -> internal dependency

If I make a change to app1, will it rerun tests from ui? I will verify once I get my repo set up correctly but I do wonder why tsconfig imports aren't the defacto recommendation when it results in a much better DX with HMR.

[un33k]

@jmroon In a mono-repo, paths is a must, if you have some buildable & publishable packages.

Here is an example to clarify this:

mono-repo called "foobar", with `@foobar` namespace
- package-one - no internal deps (& is publishable)
- package-two - depends on  package-one) (& is publishable)

Your own project in @foobar needs the two packages, and can import them directly.

// some/file.ts
import { one } from 'package-one';
import { two } from 'package-two';

Package two can also directly import from package one.

// package/package-two/two.ts
import { one } from 'package-one';

So far so good. But we mentioned that those two packages are buildable and publishable, which means they will be pushed to the public npmjs. (or a private version of it)

In that case, package-two depends on package-one, but they are no longer in the same repository (@foobar) on known paths.

Therefore, it would be great to export them such that importing is no longer based on a fix path. Grouping them under the same namespace is desirable as well.

// some/file.ts
import { one } from '@foobar/package-one';
import { two } from '@foobar/package-two';

So, package-two would reference package-one like this:

import { one } from '@foobar/package-one';

Right now, ui in turborepo is imported directly, and it would be nice to have it as @foobar/ui, by default so it is publishable and buildable with zero effort.

Here is a detailed example of an nx based mono-repo that has many publishable modules.

https://github.com/neekware/fullerstack#publishable-libraries

[jmroon]

NX is actually interesting in how it handles this. I think it uses its dependency graph internally to write out a publishable lib's package json dependencies. By default, they'll be listed as peerDependencies, but you can make them dependencies instead.

One downside I've found with NX is that a publishable lib can only depend on other publishable libs. If it depends on a purely internal lib that you don't wish to publish, the dependency wont get bundled with it:
nrwl/nx#4620

I do think NX simplifies this quite a bit. And I'll be honest, I'd probably just use NX, but as I tend to use Vue/Svelte more in my own projects, turbo fits my needs better as it is framework agnostic. But by being framework agnostic comes limitation in terms of building dependency graphs. It's hard to pick up dependencies in a package based monorepo tool when you're importing them directly and skipping package.json altogether.

I think pnpm in particular could fix this on their end. If workspace dependencies were symlinked to the actual dependency, we could just install the depencies through pnpm instead of relying on ts paths. But currently pnpm only copies the dependencies over to node_modules on install, which leads to a poor DX when using HMR bundlers.

Since pnpm/yarn/npm are unlikely to do this, I wonder if turbo could patch this somehow. We could have a monorepo definition in turbo.json that would list whether libs are buildable, publishable, or purely internal. And we could list how we wanted them imported into our apps (default i.e. copy to node_modules on install, symlinked to node_modules, or copy dist to node_modules on build).

[Chester97]

Just a quick question about doing imports such as:

{
  "baseUrl": ".",
  "compilerOptions": {
    "paths": {
      "@fe-components/atoms": ["../../packages/fe-components/components/atoms"],
    }
  },
  "extends": "tsconfig/nextjs.json",
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

Cause my import alias is pointing to fe-components packages outside of app module, while I can do the same in my component by putting only import {ANYTHING} from 'fe-components'. And this import is pointing to node_modules. So the question is - does it break any rule/good practice? Am I importing same component twice(first time because I already have it in node_modules, and second - cause i'm getting this by path in compiler options) ?

In my case I'm using turborepo where I have 1 nextjs app and 1 react package(design-system)

[neotan]

There is a trick that you may or may not have noticed. When you change tsconfig, it is not recognized by VS Code, and you have to restart TypeScript Server.

I was facing a similar case when I was working on merging 7 React apps into Turborepo monorepos, and was troubled by the fact that tsconfig/.eslintrc could not reflect in real-time when I made changes to them, so I built this small extension to monitor those config files and restart TypeScript / ESLint servers Automatically. Hope it helps.

https://marketplace.visualstudio.com/items?itemName=neotan.vscode-auto-restart-typescript-eslint-servers

[andresgutgon]

Maybe I'm doing something wrong but I don't have problems. This is my setup

Turbo + pnpm 7.x

apps/web (NextJS)
packages/ui (React components)

Inside UI i can self reference my own components

// packages/ui/src/Screens/Home/index.tsx
import Button from '@ui/src/ds/atoms/Button'
import View from '@ui/src/ds/atoms/View'

export default function Home () {
  return (
     <View><Button>Click</Button></View>
  )
}

Am I missing something?

I'm not building packages/ui I'm including as dependency of apps/web NextJS

👇 packages/ui/package.json

{
  "name": "@ui",
  "version": "0.0.0",
  "main": "./src/index.ts",
  "sideEffects": false,
  "scripts": {
    "lint": "eslint \"**/*.ts*\"",
    "lint:fix": "lint --fix",
    "check-types": "tsc --noEmit",
    "clean": "rm -rf .turbo && rm -rf node_modules && rm -rf dist"
  },
  "dependencies": {
    "nativewind": "^2.0.11",
    "solito": "3.0.0"
  },
  "peerDependencies": {
    "react": "^18.2.0"
  },
  "devDependencies": {
    "@types/react": "^18.0.26",
    "eslint": "^7.32.0",
    "eslint-config-custom": "workspace:*",
    "postcss": "^8.4.21",
    "react": "^18.2.0",
    "tailwind-config": "workspace:*",
    "tailwindcss": "^3.2.4",
    "tsconfig": "workspace:*",
    "typescript": "^4.9.4"
  }
}

[andresgutgon]

Ok, not working enterely

pnpm turbo build is working in my machine

But for some reason is not working in CI (GitHub actions)

[Nikola-Milovic]

This is the comment I wrote to someone that had similar issues as I.

You can use this package on all of your monorepos libraries that your app depends on npmjs.com/package/next-transpile-modules, after that each app/ package has to have a unique name @yourcompany/serviceA, after that you register those names into tsconfigs paths, so you cannot have @/: ./src/ for everything but instead each service has to be prefixed with @company/serviceA/: './src/'. To get path aliases to work for the packages for the nextjs app, you need to have relative paths in your tsconfig `@company/shared-package: '../../packages/shared-package'

There probably is a better way, but I had this going and it was working.

You can check out t3-app and see how they handle pnpm monorepos with NextJS

[andresgutgon]

I think I solved by including the path of my ui package in my nextjs package

apps/web/tsconfig.json (nextJS app)

  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@ui/*": ["../../packages/ui/*"]
    }
  }

[yazinsai]

My solution is simply to stop using ~ entirely, and reference the workspace name instead:

// ui/components/ButtonB.tsx
import * as React from "react"
import { ButtonA } from "ui/components/ButtonA" // <-- `ui` instead of `~components`
export const ButtonB = () => {
  return <ButtonA />
}

References don't break, since they are global, so you can do this:

// docs/pages/index.tsx
import { ButtonA } from "ui/components/ButtonA" // works as expected

---

I wish this worked out of the box, but it doesn't. You just need to declare the workspace name in every tsconfig.json for each package/app:

ui/tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "ui/*": ["src/*"]
    }
  },
}

[yang4515]

Unlike TS configuration, Vite's configuration does not include "/*". This syntax error wasted my entire afternoon. If you are using Vite and encounter errors, you may want to check if there's a mistake in Vite's configuration.
tsconfig.json:

{
  "compilerOptions": {
    "paths": {
      "@ui/*": ["../../packages/ui/src/*"]
    }
  }
}

vite.config.js:

{
resolve: {
    alias: {
      '@ui': path.resolve(__dirname, '../../packages/ui/src'),
    }
  }
}

[cwist2]

Is there a possibility to have an hotreload ?

[xmlking]

I am using vite-tsconfig-paths vite plugin in apps\<xyz> module as workaround, along with local path alias in packages/ui/tsconfig.json:

"paths": {
	"$ui/components": ["./components"],
	"$ui/components/*": ["./components/*"],
	"$ui/utils": ["./utils"],
	"$ui/utils/*": ["./utils/*"]
}

packages/ui/components/table/table-head.svelte

<script lang="ts">
	import { cn } from '$ui/utils';
</script>

apps/console/vite.config.ts

import tsconfigPaths from 'vite-tsconfig-paths';
export default defineConfig({
	plugins: [sveltekit(), sconfigPaths({ ignoreConfigErrors: true })],
...

https://github.com/xmlking/spectacular/blob/main/apps/console/vite.config.ts

[emfrick]

I'm sorry to bring up an old issue, but I'm trying to figure out how to hot-load new components from my ui library. I setup a StackBlitz project here.

Simple changes seem to work fine when I run pnpm dev, but when I add a new component to my packages/ui/components folder, as soon as I export that new component in my index.ts file, I get an error that the component could not be found.

packages/ui/src/index.ts

import "./index.css"

export * from "./components/Button" <-- changes to this file trigger HMR as expected
export * from "./components/Foo" <-- this newly added component triggers the error

Error:

[plugin:vite:import-analysis] Failed to resolve import "./components/Foo" from "../../packages/ui/src/index.ts". Does the file exist?
/home/emfrick/turborepo-with-vite-react-tailwind/packages/ui/src/index.ts:4:14
1  |  import "./index.css";
2  |  export * from "./components/Button";
3  |  export * from "./components/Foo";
   |                 ^
4  |

Is this expected behavior? Do I need to restart Vite each time I add a new component?