Add a debugging section in our docs

docs/pages/repo/docs/_meta.json

@@ -7,14 +7,14 @@
   "core-concepts": "Core Concepts",
   "reference": "API Reference",
   "ci": "CI Recipes",
+  "troubleshooting": "Troubleshooting",
   "handbook": "Monorepo Handbook",
   "changelog": {
     "title": "Changelog",
     "href": "https://github.com/vercel/turbo/releases",
     "newWindow": true
   },
   "upgrading-to-v1": "Upgrading to v1",
-  "troubleshooting": "Troubleshooting",
   "acknowledgements": "Acknowledgements",
   "faq": "FAQ"
 }

docs/pages/repo/docs/troubleshooting.mdx

@@ -5,37 +5,152 @@ description: This guide aims to help you debug issues with your Turborepo builds
 
 # Troubleshooting
 
-This guide aims to help you debug issues with your Turborepo builds and configuration.
+As with most tools, it can be frustrating to understand why Turborepo
+is not working the way you expect. This page covers some tools to debug when
+using the `turbo` CLI and some common problems you may encounter.
 
-## My dependency isn't being built correctly
+## Enable Verbose Logs
 
-- Are you properly bundling and transpiling the dependency before building the application?
-  - For example, libraries like `tsc`, `tsup`, `esbuild`, `babel`, and `swc` will convert newer JavaScript features back to “pure” JavaScript.
-  - If you are using Next.js, you might be using `transpilePackages`. Ensure you add the name of the dependency inside `next.config.js` ([example](https://github.com/vercel/turbo/blob/main/examples/basic/apps/docs/next.config.js#L1)).
-- Have you listed `files` in the dependency's `package.json` to point to the correct files?
+THe best debugging tool we have as developers are logs. You can turn up the log
+level with the [`--verbosity`][1] flag. Combined with [building from
+source][3], this can be a powerful and flexible way to see what's going on under
+the hood.
 
-## My types are not being found
+## Check your Configuration
 
-- Did you specify `types` or `typing` inside the dependency's `package.json` to point to the `.d.ts` file?
-- Have you altered or set custom `tsconfig.json` `paths`?
-  - Do they have the correct folder structure for your application?
-  - Are they properly configured for the meta framework, bundler, or transpilation tool?
+### Task Configuration
+
+You can [get started][7] with Turborepo with minimal configuration -- that's one
+of the things people love about Turborepo! But when you omit configuration,
+Turborepo internally falls back to smart defaults. Additionally, when using
+[Workspace Configurations][d-config-workspaces] in a monorepo, it can be
+confusing to understand how Turborepo interpreted your `turbo.json`. You can use
+the `--dry` or `--dry=json` to get a "resolved" task configuration for any task.
+For example:
+
+```bash
+turbo run build --dry=json
+```
+
+Look for a `resolvedTaskConfiguration` key in the output.
+
+### User Config
+
+When you link your repository to Vercel, Turborepo stores configuration in two places:
+
+- your Vercel team information is stored in `.turbo/config.json`. You can
+  inspect this file to see what else might be in there!
+- an authentication token is stored in
+  `~/Library/Application\ Support/turborepo/config.json`.
+
+## Inspect the Cache
+
+When turborepo runs a task that has configured `outputs`, it caches those
+outputs, along with the logs from that task in the `node_modules/.cache/turbo/`.
+These artifacts are compressed with `tar`, but you can uncompress and see what's
+in them.
+
+## Build from Source
+
+One of the advantages of JavaScript codebases are that you can open up
+`node_modules/` and edit the code you're running inline. This is not possible
+with `turbo`, because the runnable code is a compiled binary and you cannot edit
+it inline. But because the codebase is Open Source, you can always get
+the source code, modify it, and build it locally. The bulk of this
+documentation is available in the [Contributing Guide][4], but you can use those
+directions even if you aren't planning to make a contribution.
+
+1. Clone the git repo from [`vercel/turbo`][source]
+1. `cd cli`
+1. Make any changes (for example, add more logging)
+1. Run `make`
+1. From _your_ project, use `/:path/:to/:turbo/target/debug/turbo` instead of global
+   turbo or the version of `turbo` installed in your project.
+
+## Common Pitfalls
+
+### The `.turbo` directory
+
+One of the [core concepts][2] behind Turbo is that when a declared input
+changes, the cached outputs for that task are invalidated. As part of running any task,
+Turborepo creates the following directories:
+
+- A `.turbo` at the root of your repo
+- A `.turbo` directory in each workspace if your project is a monorepo (e.g. `apps/my-app/.turbo/`)
+- A `turbo` directory in `node_modules/.cache`
 
-## I'm not seeing any cache hits
+Because the first two directories are not git-ignored by default, you may see an
+issue where you run the same task twice and get a cache missing, even though you
+didn't change anything, because the generated `.turbo` directories are getting included as
+the task _inputs_, and invalidating cache. To avoid this problem, you can limit your
+[`inputs` configuration][r-inputs-config], or add `.turbo/` to your `.gitignore` file. We recommend
+the latter.
+
+## Common Questions
+
+### I'm not seeing any cache hits
 
 - Is any source code being generated during the build that isn't checked into git?
-  - This would change the fingerprint Turborepo uses to store build outputs.
-- Are [cache outputs correctly specified](/repo/docs/core-concepts/caching#configuring-cache-outputs) in your Turborepo [pipeline](/repo/docs/core-concepts/monorepos/running-tasks#defining-a-pipeline)?
-  - Pipeline settings are not inherited or merged, so they need to be re-specified in [workspace-specific tasks](/repo/docs/core-concepts/monorepos/running-tasks#specific-workspace-tasks) (e.g. `web#build` does **not** inherit pipeline settings from `build`).
-- [Are relevant inlined environment variables accounted for?](/repo/docs/core-concepts/caching#altering-caching-based-on-environment-variables)
-  - To verify, run `turbo` in verbose mode by adding `-vvv` to `turbo run <task>` and look at which environment variables are included in the hashes.
 
-## I'm seeing cache hits, but my build is broken
+  This would change the fingerprint Turborepo uses to store build outputs.
+
+- Are [cache outputs correctly specified][d-config-outputs] in your Turborepo [pipeline][d-def-pipeline]?
+
+  Pipeline settings are not inherited or merged, so they need to be
+  re-specified in [workspace-specific tasks][d-workspace-tasks] (e.g. `web#build` does
+  **not** inherit pipeline settings from `build`).
+
+- [Are relevant inlined environment variables accounted for?][12]
+
+  To verify, run `turbo` in verbose mode by adding `-vvv` to
+  `turbo run <task>` and look at which environment variables are included in
+  the hashes.
+
+### I'm seeing cache hits, but my build is broken
+
+- Are [cache outputs properly specified][d-config-outputs] in your Turborepo [pipeline][d-def-pipeline]?
+
+  Pipeline settings are not inherited or merged, so they need to be
+  re-specified in [workspace-specific tasks][d-workspace-tasks] (e.g. `web#build` does
+  **not** inherit pipeline settings from `build`).
+
+### My build is caching the wrong environment variables
 
-- Are [cache outputs properly specified](/repo/docs/core-concepts/caching#configuring-cache-outputs) in your Turborepo [pipeline](/repo/docs/core-concepts/monorepos/running-tasks#defining-a-pipeline)?
-  - Pipeline settings are not inherited or merged, so they need to be re-specified in [workspace-specific tasks](/repo/docs/core-concepts/monorepos/running-tasks#specific-workspace-tasks) (e.g. `web#build` does **not** inherit pipeline settings from `build`).
+- [Are relevant inlined environment variables accounted for?][12]
+  - To verify, [enable verbose logging][5], and look at which environment variables
+    are included in the hashes.
 
-## My build is caching the wrong environment variables
+## Common Monorepo Questions
+
+### My dependency isn't being built correctly
+
+- Are you properly bundling and transpiling the dependency before building the application?
+  - For example, libraries like `tsc`, `tsup`, `esbuild`, `babel`, and `swc`
+    will convert newer JavaScript features back to “pure” JavaScript.
+  - If you are using Next.js, you might be using `transpilePackages`. Ensure you
+    add the name of the dependency inside `next.config.js` ([example][17]).
+- Have you listed `files` in the dependency's `package.json` to point to the correct files?
+
+### My types are not being found
+
+- Did you specify `types` or `typing` inside the dependency's `package.json` to
+  point to the `.d.ts` file?
+- Have you altered or set custom `tsconfig.json` `paths`?
+  - Do they have the correct folder structure for your application?
+  - Are they properly configured for the meta framework, bundler, or transpilation tool?
 
-- [Are relevant inlined environment variables accounted for?](/repo/docs/core-concepts/caching#altering-caching-based-on-environment-variables)
-  - To verify, run `turbo` in verbose mode by adding `-vvv` to `turbo run <task>` and look at which environment variables are included in the hashes.
+[1]: /repo/docs/reference/command-line-reference#verbosity
+[2]: /repo/docs/core-concepts/caching
+[3]: #build-from-source
+[4]: https://github.com/vercel/turbo/blob/main/CONTRIBUTING.md
+[5]: #enable-verbose-logs
+[7]: /repo/docs/getting-started
+[9]: /repo/docs/reference/command-line-reference#turbo-link
+[12]: /repo/docs/core-concepts/caching#altering-caching-based-on-environment-variables
+[17]: https://github.com/vercel/turbo/blob/main/examples/basic/apps/docs/next.config.js#L1
+[d-workspace-tasks]: /repo/docs/core-concepts/monorepos/running-tasks#specific-workspace-tasks
+[d-config-workspaces]: /repo/docs/core-concepts/monorepos/configuring-workspaces
+[d-config-outputs]: /repo/docs/core-concepts/caching#configuring-cache-outputs
+[d-def-pipeline]: /repo/docs/core-concepts/monorepos/running-tasks#defining-a-pipeline
+[source]: https://github.com/vercel/turbo
+[r-inputs-config]: /repo/docs/reference/configuration#inputs