diff --git a/docs/pages/repo/docs/_meta.json b/docs/pages/repo/docs/_meta.json index 954e459131706..750a466c09a77 100644 --- a/docs/pages/repo/docs/_meta.json +++ b/docs/pages/repo/docs/_meta.json @@ -7,6 +7,7 @@ "core-concepts": "Core Concepts", "reference": "API Reference", "ci": "CI Recipes", + "troubleshooting": "Troubleshooting", "handbook": "Monorepo Handbook", "changelog": { "title": "Changelog", @@ -14,7 +15,6 @@ "newWindow": true }, "upgrading-to-v1": "Upgrading to v1", - "troubleshooting": "Troubleshooting", "acknowledgements": "Acknowledgements", "faq": "FAQ" } diff --git a/docs/pages/repo/docs/troubleshooting.mdx b/docs/pages/repo/docs/troubleshooting.mdx index 7fd0be12fc296..6cefa8ff68b9d 100644 --- a/docs/pages/repo/docs/troubleshooting.mdx +++ b/docs/pages/repo/docs/troubleshooting.mdx @@ -5,37 +5,154 @@ 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` + +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, add `.turbo` to your +`.gitignore` file. Alternatively, you can also limit your [`inputs` configuration][r-inputs-config] +so that `.turbo` is not included in the cache inputs. + +## Common Questions -## I'm not seeing any cache hits +### 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 ` 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 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 [cache outputs correctly specified][d-config-outputs] in your Turborepo [pipeline][d-def-pipeline]? -## My build is caching the wrong environment variables + 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] + + [Enable verbose mode][5] to see 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 relevant inlined environment variables accounted for?][12] + + [Enable verbose mode][5] to see which environment variables are included in the hashes. + +## 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 ` 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