I'm now working on Turborepo docs 3 days a week, I'm making this one of my top priorities.

Since the docs and the examples recommend next-transpile-modules, I think it is important to check its implication when building apps. For instance, just tried to build an internal package on top of @emotion/server which is widely used for enabling styling SSR with Next.js and depending on whether this package is installed only at the internal package level, at the consuming next app level or at the root of a pnpm workspace, the server bundle is not consistent size-wise. I imagine this can also be the case with other third-party packages so it may be worth checking into this.

I imagine typeRoots being consulted during module resolution can have a positive effect on the first bullet of my original post.

Hey, Kyle, thanks for these notes. Really helpful!

TL;DR: We need to find a balance on creating examples that are a great start for understanding monorepos. Not too little, not too much. I personally think we're pretty close and we can continue to do better.

Direct answers to your questions at the bottom.

My initial reaction on these is that those of us on the Turborepo team want to be mindful of our role in the ecosystem today. Matt did an excellent job with his work on these and I spent the first couple weeks of my time here as Turbo DX working on the examples, too. Here are my thoughts (with emojis on where I personally think we stand right now, today):

• We do want to provide useful examples. ✅
• We do want the examples to help you feel the power of Turborepo right away. ✅
• We do want the Turbo community to enable folks to have a healthy working knowledge of monorepo tooling. We hope that, if someone has monorepo questions, they know they can visit the Turbo community and find answers. ❌
• We do want folks to know that Turborepo is framework/tooling agnostic. Bring turbo to your JavaScript/TypeScript monorepo and it will get faster. ✅
• We do want to have a set of examples that we can reasonably maintain over time. ✅

The last bullet point is really what makes expanding the examples tough - and leads me to the "don't" category:

• We don't want to be chasing intricacies of each individual tool. JavaScript ecosystem tooling very quickly adds up and, the deeper you go with one, the more you have to chase the intersection of all of the tools combined. The maintenance burden becomes exponential. ✅
• We don't want to re-document individual, non-Turborepo tools. We'd like to be active in helping the JavaScript community ensure the tools they build are great for monorepos - but we want to be users of those tools with the rest of the community rather than knowledge keepers. (Over time, we may find that Turborepo users want us to create tooling that overlaps with those other tools, as well.) ✅
• We don't want the examples to be a burden on our team that detracts from improving Turborepo. Every minute the core team has had to spend finicking with these examples is a minute lost towards making Turborepo awesome. (Certainly an investment in helping folks, though, not to be discounted.) ✅
• We don't want the examples to be confusing for beginners. ⚠️
• We don't want the examples/documentation to be missing answers to questions that the community is asking too often. ⚠️

There are probably more list items I can add to the above context but hopefully it paints a good enough picture of what we're looking for:

• The examples show you the very basics of Turborepo, monorepos, and overwhelmingly common ecosystem tools.
• By nature, the examples should leave some things unsaid.
• They showcase Turborepo's flexibility to work with the ecosystem and different ways you can use turbo for most common tasks.

Some additional useful context may be that I asked the Next.js team about their examples directory. To make a long story short, they've said it's too big. We're going to piggyback on that experience and try to keep things more lean here in Turbo.

Directly answering your questions to the best of my knowledge finally

• Path aliases: This is indeed a shortcoming of the transpilePackages strategy that you'll find in our examples. I personally haven't found a way of mitigating this that's totally bulletproof. It's largely a matter of tradeoffs, as you'll find folks discussing in the Discussion you've mentioned. Some folks may decide that path aliases make it worth bundlers parsing their code twice to produce a build. Some may not. However, this is something that does get asked about frequently and I'm hoping to have a better answer soon.
• Storybook: It makes the most sense to have Storybook be an application in your monorepo for demonstration purposes. In the event that you change Storybook-only source code, you would only want to miss cache for that application. If Storybook is lumped into the ui package, you would force the rest of the monorepo to miss cache (even though you only updated a Storybook story.) There are, of course, ways around this (namely, the inputs key in turbo.json) - but this gets too far into the weeds too quickly for a simple demonstration for beginners. If you're someone who is thinking about these tradeoffs already, you likely don't need our help as much as folks trying to get the basics. 😄
• pnpm: yarn v1/2 use * to refer to other workspaces and yarn 3+ and pnpm use workspace:*. This is in our documentation today (it may not have been when you asked the question).
• I have it on my todo list to write a circular imports document.

Thanks again for your thoughtfulness here, Kyle!