Debugging workspace packages

[Falven]

Verify canary release

• I verified that the issue exists in the latest Turborepo canary release.

Link to code that reproduces this issue

I have modified the "basic" turborepo starter example here to demonstrate the issue.

Which canary version will you have in your reproduction?

2.3.1

Enviroment information

CLI:
   Version: 2.3.1
   Path to executable: /Users/falven/Source/turborepo/examples/basic/node_modules/.pnpm/[email protected]/node_modules/turbo-darwin-arm64/bin/turbo
   Daemon status: Running
   Package manager: pnpm9

Platform:
   Architecture: aarch64
   Operating system: macos
   WSL: false
   Available memory (MB): 10547
   Available CPU cores: 12

Environment:
   CI: None
   Terminal (TERM): xterm-256color
   Terminal program (TERM_PROGRAM): vscode
   Terminal program version (TERM_PROGRAM_VERSION): 1.95.3
   Shell (SHELL): /bin/zsh
   stdin: false

Expected behavior

The official Turborepo recommendation is to use compiled workspace packages for internal packages. Debugging these compiled packages should require minimal effort. However, since the packages are bundled with your primary applications (e.g. Next.js), there is no documented guidance on how to properly set up debugging of these compiled workspace packages.

Actual behavior

Compiled workspace package source code breakpoints do not bind on default examples and with turborepo docs guidance.

To Reproduce

1. Clone the repository.
2. Open examples/basic/packages/lib/src/index.ts and set a breakpoint at line 2.
3. From the examples/basic directory, start the development server by running turbo dev.
4. Attach the debugger by selecting "Next.js: attach server-side" from the dropdown, then click the green "Play" button.
5. In your browser, navigate to http://localhost:3000/api/auth, or alternatively, run curl http://localhost:3000/api/auth -i from your shell of choice.
6. The breakpoint you set should be triggered, but it is not.

Additional context

I've found that adding "sourceRoot": "../../packages/lib/src" to the relevant workspace package's tsconfig.json will sometimes allow breakpoints to bind correctly. However, if you have multiple workspace packages, breakpoints may occasionally hit random lines in the dist (JS) files instead of the src (TS) files, even when the sources are fully built and up-to-date. I'm not sure why this occurs; I hope it's just a bug with the JavaScript Debugger plugin or something else that will resolve itself eventually. I am also unsure if setting sourceRoot like this affects anything else.

No response

[anthonyshew]

This sounds like something that would be nice to add, but I'm trying to figure out Turborepo's role here. This sounds more like something that lies at the intersection of VSCode, its built-in debugger, TypeScript, and how to use all of those in a monorepo.

[Falven]

This sounds like something that would be nice to add, but I'm trying to figure out Turborepo's role here. This sounds more like something that lies at the intersection of VSCode, its built-in debugger, TypeScript, and how to use all of those in a monorepo.

It feels like 90% of time in web development is spent wrangling configuration files, dealing with conflicting tsconfigs, ensuring linting rules are set up correctly, figuring out es modules vs commonjs, configuring bundlers, and in-general, fighting with tooling. From my perspective, one of Turborepo's core strengths is its ability to streamline these sorts of issues in a monorepo environment with minimal additional necessary tooling. By adopting a more opinionated approach and simplifying how these tools work together through transparent documentation and recommendations, Turborepo helps developers focus less on boilerplate configuration and more on building actual features. I understand that there's a balance of how much to include to keep things simple and maintain separation of concerns, but IMHO debugging is a core necessity of advanced development like that done in monorepos involving complex orchestration of multiple packages. Including this kind of documentation would reinforce the idea that Turborepo isn’t just another monorepo tool; it’s a framework designed to smooth out those rough edges so that teams can spend more time coding and less time fiddling with setup.