From a2f8df3b14979f74c03a79b2ffaf081739837899 Mon Sep 17 00:00:00 2001 From: 简律纯 Date: Wed, 3 May 2023 01:09:49 +0800 Subject: --- docs/components/ExamplesArea.tsx | 2 +- docs/components/ExtraContent.tsx | 2 +- docs/components/Footer.tsx | 10 +- docs/components/HydroRollTRPGFeatures.tsx | 106 +++ docs/components/HydroRollTRPGQuickstart.tsx | 28 + docs/components/Navigation.tsx | 4 +- docs/components/QuickStart.tsx | 16 +- docs/components/RemoteCacheCounter.tsx | 2 +- docs/components/SiteSwitcher.tsx | 16 +- docs/components/Social.tsx | 2 +- docs/components/TurbopackFeatures.tsx | 106 --- docs/components/TurbopackQuickstart.tsx | 28 - docs/components/pages/AI-home/AIFeatures.tsx | 15 + docs/components/pages/AI-home/AIHero.tsx | 114 ++++ docs/components/pages/AI-home/AILetter.tsx | 118 ++++ docs/components/pages/AI-home/index.tsx | 22 + docs/components/pages/confirm.tsx | 2 +- docs/components/pages/landing/HydroRollAI.tsx | 27 + docs/components/pages/landing/HydroRollTRPG.tsx | 27 + docs/components/pages/landing/Turbopack.tsx | 27 - docs/components/pages/landing/Turborepo.tsx | 27 - docs/components/pages/landing/index.tsx | 18 +- .../pages/pack-home/PackBenchmarksGraph.tsx | 8 +- .../pages/pack-home/PackBenchmarksPicker.tsx | 2 +- docs/components/pages/pack-home/PackFeatures.tsx | 2 +- docs/components/pages/pack-home/PackHero.tsx | 16 +- docs/components/pages/pack-home/PackLetter.tsx | 6 +- docs/components/pages/pack-home/index.tsx | 2 +- docs/components/pages/repo-home/RepoFeatures.tsx | 15 - docs/components/pages/repo-home/RepoHero.tsx | 114 ---- docs/components/pages/repo-home/RepoLetter.tsx | 118 ---- docs/components/pages/repo-home/index.tsx | 22 - docs/components/pages/showcase.tsx | 8 +- docs/next.config.js | 156 +---- docs/package.json | 2 +- docs/pages/AI/_meta.json | 15 + docs/pages/AI/docs/_meta.json | 15 + docs/pages/AI/docs/acknowledgements.mdx | 45 ++ docs/pages/AI/docs/faq.mdx | 51 ++ docs/pages/AI/docs/getting-started/_meta.json | 6 + .../AI/docs/getting-started/add-to-project.mdx | 147 +++++ docs/pages/AI/docs/getting-started/create-new.mdx | 527 +++++++++++++++ .../AI/docs/getting-started/existing-monorepo.mdx | 231 +++++++ .../pages/AI/docs/getting-started/from-example.mdx | 49 ++ docs/pages/AI/docs/index.mdx | 73 +++ docs/pages/AI/docs/installing.mdx | 85 +++ docs/pages/AI/docs/troubleshooting.mdx | 172 +++++ docs/pages/AI/index.mdx | 7 + docs/pages/TRPG/_meta.json | 15 + docs/pages/TRPG/docs/_meta.json | 6 + docs/pages/TRPG/docs/core-concepts.mdx | 64 ++ docs/pages/TRPG/docs/features.mdx | 22 + docs/pages/TRPG/docs/index.mdx | 61 ++ docs/pages/TRPG/docs/why-trpg.mdx | 62 ++ docs/pages/TRPG/index.mdx | 8 + docs/pages/_meta.json | 4 +- docs/pages/api/og.tsx | 14 +- docs/pages/blog/_meta.json | 2 +- docs/pages/blog/hydroroll-0-1-3.mdx | 4 +- docs/pages/pack/_meta.json | 15 - docs/pages/pack/docs/_meta.json | 10 - docs/pages/pack/docs/advanced/profiling.mdx | 74 --- docs/pages/pack/docs/benchmarks.mdx | 174 ----- .../pack/docs/comparisons/BenchmarksCallout.tsx | 14 - docs/pages/pack/docs/comparisons/_meta.json | 4 - docs/pages/pack/docs/comparisons/vite.mdx | 67 -- docs/pages/pack/docs/comparisons/webpack.mdx | 66 -- docs/pages/pack/docs/core-concepts.mdx | 64 -- docs/pages/pack/docs/features.mdx | 22 - docs/pages/pack/docs/features/_meta.json | 11 - docs/pages/pack/docs/features/css.mdx | 80 --- .../pack/docs/features/customizing-turbopack.mdx | 112 ---- docs/pages/pack/docs/features/dev-server.mdx | 17 - .../pack/docs/features/environment-variables.mdx | 29 - docs/pages/pack/docs/features/frameworks.mdx | 45 -- docs/pages/pack/docs/features/imports.mdx | 47 -- docs/pages/pack/docs/features/javascript.mdx | 39 -- docs/pages/pack/docs/features/static-assets.mdx | 47 -- docs/pages/pack/docs/features/typescript.mdx | 40 -- docs/pages/pack/docs/index.mdx | 61 -- docs/pages/pack/docs/migrating-from-webpack.mdx | 34 - docs/pages/pack/docs/roadmap.mdx | 33 - docs/pages/pack/docs/why-turbopack.mdx | 62 -- docs/pages/pack/index.mdx | 8 - docs/pages/repo/_meta.json | 15 - docs/pages/repo/docs/_meta.json | 20 - docs/pages/repo/docs/acknowledgements.mdx | 45 -- docs/pages/repo/docs/ci.mdx | 13 - docs/pages/repo/docs/ci/_meta.json | 6 - docs/pages/repo/docs/ci/circleci.mdx | 145 ----- docs/pages/repo/docs/ci/github-actions.mdx | 231 ------- docs/pages/repo/docs/ci/gitlabci.mdx | 136 ---- docs/pages/repo/docs/ci/travisci.mdx | 122 ---- docs/pages/repo/docs/core-concepts/_meta.json | 8 - docs/pages/repo/docs/core-concepts/caching.mdx | 460 ------------- docs/pages/repo/docs/core-concepts/monorepos.mdx | 23 - .../repo/docs/core-concepts/monorepos/_meta.json | 5 - .../monorepos/configuring-workspaces.mdx | 267 -------- .../docs/core-concepts/monorepos/filtering.mdx | 208 ------ .../docs/core-concepts/monorepos/running-tasks.mdx | 315 --------- .../core-concepts/monorepos/skipping-tasks.mdx | 66 -- .../repo/docs/core-concepts/remote-caching.mdx | 112 ---- docs/pages/repo/docs/core-concepts/scopes.mdx | 50 -- docs/pages/repo/docs/faq.mdx | 51 -- docs/pages/repo/docs/getting-started/_meta.json | 6 - .../repo/docs/getting-started/add-to-project.mdx | 147 ----- .../pages/repo/docs/getting-started/create-new.mdx | 527 --------------- .../docs/getting-started/existing-monorepo.mdx | 231 ------- .../repo/docs/getting-started/from-example.mdx | 49 -- docs/pages/repo/docs/handbook.mdx | 25 - docs/pages/repo/docs/handbook/_meta.json | 15 - .../pages/repo/docs/handbook/building-your-app.mdx | 76 --- .../repo/docs/handbook/deploying-with-docker.mdx | 184 ------ docs/pages/repo/docs/handbook/dev.mdx | 205 ------ .../repo/docs/handbook/environment-variables.mdx | 54 -- docs/pages/repo/docs/handbook/linting.mdx | 50 -- docs/pages/repo/docs/handbook/linting/_meta.json | 4 - docs/pages/repo/docs/handbook/linting/eslint.mdx | 124 ---- .../repo/docs/handbook/linting/typescript.mdx | 129 ---- .../repo/docs/handbook/migrating-to-a-monorepo.mdx | 77 --- .../repo/docs/handbook/package-installation.mdx | 157 ----- .../repo/docs/handbook/publishing-packages.mdx | 15 - .../docs/handbook/publishing-packages/_meta.json | 4 - .../docs/handbook/publishing-packages/bundling.mdx | 130 ---- .../versioning-and-publishing.mdx | 57 -- docs/pages/repo/docs/handbook/sharing-code.mdx | 71 -- .../repo/docs/handbook/sharing-code/_meta.json | 3 - .../handbook/sharing-code/internal-packages.mdx | 237 ------- docs/pages/repo/docs/handbook/testing.mdx | 109 ---- docs/pages/repo/docs/handbook/tools/_meta.json | 4 - docs/pages/repo/docs/handbook/tools/prisma.mdx | 207 ------ docs/pages/repo/docs/handbook/tools/storybook.mdx | 223 ------- docs/pages/repo/docs/handbook/troubleshooting.mdx | 31 - .../repo/docs/handbook/what-is-a-monorepo.mdx | 85 --- docs/pages/repo/docs/handbook/workspaces.mdx | 168 ----- docs/pages/repo/docs/index.mdx | 73 --- docs/pages/repo/docs/installing.mdx | 85 --- docs/pages/repo/docs/reference/_meta.json | 5 - docs/pages/repo/docs/reference/codemods.mdx | 278 -------- .../repo/docs/reference/command-line-reference.mdx | 713 --------------------- docs/pages/repo/docs/reference/configuration.mdx | 405 ------------ docs/pages/repo/docs/troubleshooting.mdx | 172 ----- docs/pages/repo/docs/upgrading-to-v1.mdx | 78 --- docs/pages/repo/index.mdx | 7 - docs/pages/showcase.mdx | 2 +- docs/pages/terms.mdx | 2 +- .../public/images/docs/AI/jared-signature-dark.svg | 21 + .../images/docs/AI/jared-signature-light.svg | 12 + .../images/docs/AI/repo-hero-circles-dark.svg | 17 + .../images/docs/AI/repo-hero-circles-light.svg | 14 + docs/public/images/docs/AI/repo-hero-logo-dark.svg | 32 + .../public/images/docs/AI/repo-hero-logo-light.svg | 21 + docs/public/images/docs/TRPG/instruments-dark.png | Bin 0 -> 390185 bytes docs/public/images/docs/TRPG/instruments-light.png | Bin 0 -> 419437 bytes .../images/docs/TRPG/tobias-signature-dark.svg | 26 + .../images/docs/TRPG/tobias-signature-light.svg | 26 + .../images/docs/TRPG/turbo-benchmark-icon-dark.svg | 15 + .../docs/TRPG/turbo-benchmark-icon-light.svg | 15 + .../images/docs/TRPG/turbo-engine-first-run.png | Bin 0 -> 648402 bytes .../images/docs/TRPG/turbo-engine-second-run.png | Bin 0 -> 626325 bytes .../docs/TRPG/turbopack-hero-hexagons-dark.svg | 25 + .../docs/TRPG/turbopack-hero-hexagons-light.svg | 13 + .../images/docs/TRPG/turbopack-hero-logo-dark.svg | 45 ++ .../images/docs/TRPG/turbopack-hero-logo-light.svg | 37 ++ docs/public/images/docs/pack/instruments-dark.png | Bin 390185 -> 0 bytes docs/public/images/docs/pack/instruments-light.png | Bin 419437 -> 0 bytes .../images/docs/pack/tobias-signature-dark.svg | 26 - .../images/docs/pack/tobias-signature-light.svg | 26 - .../images/docs/pack/turbo-benchmark-icon-dark.svg | 15 - .../docs/pack/turbo-benchmark-icon-light.svg | 15 - .../images/docs/pack/turbo-engine-first-run.png | Bin 648402 -> 0 bytes .../images/docs/pack/turbo-engine-second-run.png | Bin 626325 -> 0 bytes .../docs/pack/turbopack-hero-hexagons-dark.svg | 25 - .../docs/pack/turbopack-hero-hexagons-light.svg | 13 - .../images/docs/pack/turbopack-hero-logo-dark.svg | 45 -- .../images/docs/pack/turbopack-hero-logo-light.svg | 37 -- .../images/docs/repo/jared-signature-dark.svg | 21 - .../images/docs/repo/jared-signature-light.svg | 12 - .../images/docs/repo/repo-hero-circles-dark.svg | 17 - .../images/docs/repo/repo-hero-circles-light.svg | 14 - .../images/docs/repo/repo-hero-logo-dark.svg | 32 - .../images/docs/repo/repo-hero-logo-light.svg | 21 - docs/sentry.properties | 5 +- 183 files changed, 2518 insertions(+), 9697 deletions(-) create mode 100644 docs/components/HydroRollTRPGFeatures.tsx create mode 100644 docs/components/HydroRollTRPGQuickstart.tsx delete mode 100644 docs/components/TurbopackFeatures.tsx delete mode 100644 docs/components/TurbopackQuickstart.tsx create mode 100644 docs/components/pages/AI-home/AIFeatures.tsx create mode 100644 docs/components/pages/AI-home/AIHero.tsx create mode 100644 docs/components/pages/AI-home/AILetter.tsx create mode 100644 docs/components/pages/AI-home/index.tsx create mode 100644 docs/components/pages/landing/HydroRollAI.tsx create mode 100644 docs/components/pages/landing/HydroRollTRPG.tsx delete mode 100644 docs/components/pages/landing/Turbopack.tsx delete mode 100644 docs/components/pages/landing/Turborepo.tsx delete mode 100644 docs/components/pages/repo-home/RepoFeatures.tsx delete mode 100644 docs/components/pages/repo-home/RepoHero.tsx delete mode 100644 docs/components/pages/repo-home/RepoLetter.tsx delete mode 100644 docs/components/pages/repo-home/index.tsx create mode 100644 docs/pages/AI/_meta.json create mode 100644 docs/pages/AI/docs/_meta.json create mode 100644 docs/pages/AI/docs/acknowledgements.mdx create mode 100644 docs/pages/AI/docs/faq.mdx create mode 100644 docs/pages/AI/docs/getting-started/_meta.json create mode 100644 docs/pages/AI/docs/getting-started/add-to-project.mdx create mode 100644 docs/pages/AI/docs/getting-started/create-new.mdx create mode 100644 docs/pages/AI/docs/getting-started/existing-monorepo.mdx create mode 100644 docs/pages/AI/docs/getting-started/from-example.mdx create mode 100644 docs/pages/AI/docs/index.mdx create mode 100644 docs/pages/AI/docs/installing.mdx create mode 100644 docs/pages/AI/docs/troubleshooting.mdx create mode 100644 docs/pages/AI/index.mdx create mode 100644 docs/pages/TRPG/_meta.json create mode 100644 docs/pages/TRPG/docs/_meta.json create mode 100644 docs/pages/TRPG/docs/core-concepts.mdx create mode 100644 docs/pages/TRPG/docs/features.mdx create mode 100644 docs/pages/TRPG/docs/index.mdx create mode 100644 docs/pages/TRPG/docs/why-trpg.mdx create mode 100644 docs/pages/TRPG/index.mdx delete mode 100644 docs/pages/pack/_meta.json delete mode 100644 docs/pages/pack/docs/_meta.json delete mode 100644 docs/pages/pack/docs/advanced/profiling.mdx delete mode 100644 docs/pages/pack/docs/benchmarks.mdx delete mode 100644 docs/pages/pack/docs/comparisons/BenchmarksCallout.tsx delete mode 100644 docs/pages/pack/docs/comparisons/_meta.json delete mode 100644 docs/pages/pack/docs/comparisons/vite.mdx delete mode 100644 docs/pages/pack/docs/comparisons/webpack.mdx delete mode 100644 docs/pages/pack/docs/core-concepts.mdx delete mode 100644 docs/pages/pack/docs/features.mdx delete mode 100644 docs/pages/pack/docs/features/_meta.json delete mode 100644 docs/pages/pack/docs/features/css.mdx delete mode 100644 docs/pages/pack/docs/features/customizing-turbopack.mdx delete mode 100644 docs/pages/pack/docs/features/dev-server.mdx delete mode 100644 docs/pages/pack/docs/features/environment-variables.mdx delete mode 100644 docs/pages/pack/docs/features/frameworks.mdx delete mode 100644 docs/pages/pack/docs/features/imports.mdx delete mode 100644 docs/pages/pack/docs/features/javascript.mdx delete mode 100644 docs/pages/pack/docs/features/static-assets.mdx delete mode 100644 docs/pages/pack/docs/features/typescript.mdx delete mode 100644 docs/pages/pack/docs/index.mdx delete mode 100644 docs/pages/pack/docs/migrating-from-webpack.mdx delete mode 100644 docs/pages/pack/docs/roadmap.mdx delete mode 100644 docs/pages/pack/docs/why-turbopack.mdx delete mode 100644 docs/pages/pack/index.mdx delete mode 100644 docs/pages/repo/_meta.json delete mode 100644 docs/pages/repo/docs/_meta.json delete mode 100644 docs/pages/repo/docs/acknowledgements.mdx delete mode 100644 docs/pages/repo/docs/ci.mdx delete mode 100644 docs/pages/repo/docs/ci/_meta.json delete mode 100644 docs/pages/repo/docs/ci/circleci.mdx delete mode 100644 docs/pages/repo/docs/ci/github-actions.mdx delete mode 100644 docs/pages/repo/docs/ci/gitlabci.mdx delete mode 100644 docs/pages/repo/docs/ci/travisci.mdx delete mode 100644 docs/pages/repo/docs/core-concepts/_meta.json delete mode 100644 docs/pages/repo/docs/core-concepts/caching.mdx delete mode 100644 docs/pages/repo/docs/core-concepts/monorepos.mdx delete mode 100644 docs/pages/repo/docs/core-concepts/monorepos/_meta.json delete mode 100644 docs/pages/repo/docs/core-concepts/monorepos/configuring-workspaces.mdx delete mode 100644 docs/pages/repo/docs/core-concepts/monorepos/filtering.mdx delete mode 100644 docs/pages/repo/docs/core-concepts/monorepos/running-tasks.mdx delete mode 100644 docs/pages/repo/docs/core-concepts/monorepos/skipping-tasks.mdx delete mode 100644 docs/pages/repo/docs/core-concepts/remote-caching.mdx delete mode 100644 docs/pages/repo/docs/core-concepts/scopes.mdx delete mode 100644 docs/pages/repo/docs/faq.mdx delete mode 100644 docs/pages/repo/docs/getting-started/_meta.json delete mode 100644 docs/pages/repo/docs/getting-started/add-to-project.mdx delete mode 100644 docs/pages/repo/docs/getting-started/create-new.mdx delete mode 100644 docs/pages/repo/docs/getting-started/existing-monorepo.mdx delete mode 100644 docs/pages/repo/docs/getting-started/from-example.mdx delete mode 100644 docs/pages/repo/docs/handbook.mdx delete mode 100644 docs/pages/repo/docs/handbook/_meta.json delete mode 100644 docs/pages/repo/docs/handbook/building-your-app.mdx delete mode 100644 docs/pages/repo/docs/handbook/deploying-with-docker.mdx delete mode 100644 docs/pages/repo/docs/handbook/dev.mdx delete mode 100644 docs/pages/repo/docs/handbook/environment-variables.mdx delete mode 100644 docs/pages/repo/docs/handbook/linting.mdx delete mode 100644 docs/pages/repo/docs/handbook/linting/_meta.json delete mode 100644 docs/pages/repo/docs/handbook/linting/eslint.mdx delete mode 100644 docs/pages/repo/docs/handbook/linting/typescript.mdx delete mode 100644 docs/pages/repo/docs/handbook/migrating-to-a-monorepo.mdx delete mode 100644 docs/pages/repo/docs/handbook/package-installation.mdx delete mode 100644 docs/pages/repo/docs/handbook/publishing-packages.mdx delete mode 100644 docs/pages/repo/docs/handbook/publishing-packages/_meta.json delete mode 100644 docs/pages/repo/docs/handbook/publishing-packages/bundling.mdx delete mode 100644 docs/pages/repo/docs/handbook/publishing-packages/versioning-and-publishing.mdx delete mode 100644 docs/pages/repo/docs/handbook/sharing-code.mdx delete mode 100644 docs/pages/repo/docs/handbook/sharing-code/_meta.json delete mode 100644 docs/pages/repo/docs/handbook/sharing-code/internal-packages.mdx delete mode 100644 docs/pages/repo/docs/handbook/testing.mdx delete mode 100644 docs/pages/repo/docs/handbook/tools/_meta.json delete mode 100644 docs/pages/repo/docs/handbook/tools/prisma.mdx delete mode 100644 docs/pages/repo/docs/handbook/tools/storybook.mdx delete mode 100644 docs/pages/repo/docs/handbook/troubleshooting.mdx delete mode 100644 docs/pages/repo/docs/handbook/what-is-a-monorepo.mdx delete mode 100644 docs/pages/repo/docs/handbook/workspaces.mdx delete mode 100644 docs/pages/repo/docs/index.mdx delete mode 100644 docs/pages/repo/docs/installing.mdx delete mode 100644 docs/pages/repo/docs/reference/_meta.json delete mode 100644 docs/pages/repo/docs/reference/codemods.mdx delete mode 100644 docs/pages/repo/docs/reference/command-line-reference.mdx delete mode 100644 docs/pages/repo/docs/reference/configuration.mdx delete mode 100644 docs/pages/repo/docs/troubleshooting.mdx delete mode 100644 docs/pages/repo/docs/upgrading-to-v1.mdx delete mode 100644 docs/pages/repo/index.mdx create mode 100644 docs/public/images/docs/AI/jared-signature-dark.svg create mode 100644 docs/public/images/docs/AI/jared-signature-light.svg create mode 100644 docs/public/images/docs/AI/repo-hero-circles-dark.svg create mode 100644 docs/public/images/docs/AI/repo-hero-circles-light.svg create mode 100644 docs/public/images/docs/AI/repo-hero-logo-dark.svg create mode 100644 docs/public/images/docs/AI/repo-hero-logo-light.svg create mode 100644 docs/public/images/docs/TRPG/instruments-dark.png create mode 100644 docs/public/images/docs/TRPG/instruments-light.png create mode 100644 docs/public/images/docs/TRPG/tobias-signature-dark.svg create mode 100644 docs/public/images/docs/TRPG/tobias-signature-light.svg create mode 100644 docs/public/images/docs/TRPG/turbo-benchmark-icon-dark.svg create mode 100644 docs/public/images/docs/TRPG/turbo-benchmark-icon-light.svg create mode 100644 docs/public/images/docs/TRPG/turbo-engine-first-run.png create mode 100644 docs/public/images/docs/TRPG/turbo-engine-second-run.png create mode 100644 docs/public/images/docs/TRPG/turbopack-hero-hexagons-dark.svg create mode 100644 docs/public/images/docs/TRPG/turbopack-hero-hexagons-light.svg create mode 100644 docs/public/images/docs/TRPG/turbopack-hero-logo-dark.svg create mode 100644 docs/public/images/docs/TRPG/turbopack-hero-logo-light.svg delete mode 100644 docs/public/images/docs/pack/instruments-dark.png delete mode 100644 docs/public/images/docs/pack/instruments-light.png delete mode 100644 docs/public/images/docs/pack/tobias-signature-dark.svg delete mode 100644 docs/public/images/docs/pack/tobias-signature-light.svg delete mode 100644 docs/public/images/docs/pack/turbo-benchmark-icon-dark.svg delete mode 100644 docs/public/images/docs/pack/turbo-benchmark-icon-light.svg delete mode 100644 docs/public/images/docs/pack/turbo-engine-first-run.png delete mode 100644 docs/public/images/docs/pack/turbo-engine-second-run.png delete mode 100644 docs/public/images/docs/pack/turbopack-hero-hexagons-dark.svg delete mode 100644 docs/public/images/docs/pack/turbopack-hero-hexagons-light.svg delete mode 100644 docs/public/images/docs/pack/turbopack-hero-logo-dark.svg delete mode 100644 docs/public/images/docs/pack/turbopack-hero-logo-light.svg delete mode 100644 docs/public/images/docs/repo/jared-signature-dark.svg delete mode 100644 docs/public/images/docs/repo/jared-signature-light.svg delete mode 100644 docs/public/images/docs/repo/repo-hero-circles-dark.svg delete mode 100644 docs/public/images/docs/repo/repo-hero-circles-light.svg delete mode 100644 docs/public/images/docs/repo/repo-hero-logo-dark.svg delete mode 100644 docs/public/images/docs/repo/repo-hero-logo-light.svg (limited to 'docs') diff --git a/docs/components/ExamplesArea.tsx b/docs/components/ExamplesArea.tsx index 8b38263..c4c7060 100644 --- a/docs/components/ExamplesArea.tsx +++ b/docs/components/ExamplesArea.tsx @@ -22,7 +22,7 @@ export const ExamplesArea = ({ name, }} target="_blank" - href={`https://github.com/vercel/turbo/tree/main/examples/${slug}`} + href={`https://github.com/retrofor/HydroRoll/tree/main/examples/${slug}`} /> ))} diff --git a/docs/components/ExtraContent.tsx b/docs/components/ExtraContent.tsx index f489e36..93567ce 100644 --- a/docs/components/ExtraContent.tsx +++ b/docs/components/ExtraContent.tsx @@ -4,7 +4,7 @@ import { useTurboSite } from "./SiteSwitcher"; export default function ExtraContent() { const site = useTurboSite(); - if (site === "repo") { + if (site === "AI") { return ; } } diff --git a/docs/components/Footer.tsx b/docs/components/Footer.tsx index c39225c..4cb2089 100644 --- a/docs/components/Footer.tsx +++ b/docs/components/Footer.tsx @@ -33,16 +33,16 @@ const navigation = { { name: "Releases", href: "https://github.com/retrofor/HydroRoll/releases" }, ], repo: [ - { name: "Documentation", href: "/repo/docs" }, + { name: "Documentation", href: "/AI/docs" }, { name: "API Reference", - href: "/repo/docs/reference/command-line-reference", + href: "/AI/docs/reference/command-line-reference", }, - { name: "FAQ", href: "/repo/docs/faq" }, + { name: "FAQ", href: "/AI/docs/faq" }, ], pack: [ - { name: "Documentation", href: "/pack/docs" }, - { name: "Features", href: "/pack/docs/features" }, + { name: "Documentation", href: "/TRPG/docs" }, + { name: "Features", href: "/TRPG/docs/features" }, ], support: [ { diff --git a/docs/components/HydroRollTRPGFeatures.tsx b/docs/components/HydroRollTRPGFeatures.tsx new file mode 100644 index 0000000..c470df7 --- /dev/null +++ b/docs/components/HydroRollTRPGFeatures.tsx @@ -0,0 +1,106 @@ +import { + AdjustmentsIcon, + ArchiveIcon, + DesktopComputerIcon, + DownloadIcon, + ServerIcon, +} from "@heroicons/react/outline"; +import { DetailedFeatureLink } from "./Feature"; +import { CSSIcon, JSIcon, TSIcon } from "./Icons"; + +export const HydroRollTRPGFeatures = () => { + return ( +
+ + + Supports TypeScript out of the box, including resolving{" "} + paths and baseUrl. + + ), + name: "TypeScript", + }} + href="/TRPG/docs/features/typescript" + > + + Supports require, import, dynamic + imports and more. + + ), + name: "Imports", + }} + href="/TRPG/docs/features/imports" + > + + + Supports Global CSS, CSS Modules, postcss-nested and{" "} + @import. + + ), + name: "CSS", + }} + href="/TRPG/docs/features/css" + > + + + Supports the /public directory, JSON imports, and + importing assets via ESM. + + ), + name: "Static Assets", + }} + href="/TRPG/docs/features/static-assets" + > + + Supports environment variables via .env,{" "} + .env.local, and more. + + ), + name: "Environment Variables", + }} + href="/TRPG/docs/features/environment-variables" + > +
+ ); +}; diff --git a/docs/components/HydroRollTRPGQuickstart.tsx b/docs/components/HydroRollTRPGQuickstart.tsx new file mode 100644 index 0000000..2e17d41 --- /dev/null +++ b/docs/components/HydroRollTRPGQuickstart.tsx @@ -0,0 +1,28 @@ +import { + LightBulbIcon, + QuestionMarkCircleIcon, +} from "@heroicons/react/outline"; +import { DetailedFeatureLink } from "./Feature"; + +export const HydroRollTRPGQuickstartArea = () => { + return ( +
+ + +
+ ); +}; diff --git a/docs/components/Navigation.tsx b/docs/components/Navigation.tsx index d72b714..b446d4c 100644 --- a/docs/components/Navigation.tsx +++ b/docs/components/Navigation.tsx @@ -28,7 +28,7 @@ function Navigation(props) { // https://github.com/shuding/nextra/issues/1028 route: "enterprise", href: `https://vercel.com/${ - site === "repo" ? "solutions/turborepo" : "contact/sales" + site === "AI" ? "solutions/HydroRollAI" : "contact/sales" }?utm_source=turbo.build&utm_medium=referral&utm_campaign=header-enterpriseLink`, id: "contextual-enterprise", key: "contextual-enterprise", @@ -37,7 +37,7 @@ function Navigation(props) { // remove the top level repo and pack links const headerItems = props.items.filter((item) => { - return item.name !== "repo" && item.name !== "pack"; + return item.name !== "AI" && item.name !== "TRPG"; }); // items last to override the default diff --git a/docs/components/QuickStart.tsx b/docs/components/QuickStart.tsx index 040871e..113ba4f 100644 --- a/docs/components/QuickStart.tsx +++ b/docs/components/QuickStart.tsx @@ -20,7 +20,7 @@ export const QuickStartArea = () => { description: `Add Turborepo to any JavaScript or TypeScript project in minutes.`, name: "Add to existing project", }} - href="/repo/docs/getting-started/add-to-project" + href="/AI/docs/getting-started/add-to-project" > { description: `Build a brand-new monorepo with shared packages powered by Turborepo.`, name: "Create a new monorepo", }} - href="/repo/docs/getting-started/create-new" + href="/AI/docs/getting-started/create-new" > { description: `Incrementally add Turborepo to your existing monorepo codebase.`, name: "Add to existing monorepo", }} - href="/repo/docs/getting-started/existing-monorepo" + href="/AI/docs/getting-started/existing-monorepo" > ); @@ -49,9 +49,9 @@ export const MonoreposArea = () => { feature={{ Icon: LightBulbIcon, description: `Understand why monorepos don't scale - and why Turborepo is the solution.`, - name: "Why Turborepo?", + name: "Why AI?", }} - href="/repo/docs/core-concepts/monorepos" + href="/AI/docs/core-concepts/monorepos" > { description: `Learn the basics of monorepos before you dive in to Turborepo.`, name: "Read the Monorepo Handbook", }} - href="/docs/handbook" + href="/AI/handbook" > ); @@ -74,7 +74,7 @@ export const LearnMoreArea = () => { description: `Turborepo remembers the output of any task you run - and can skip work that's already been done.`, name: "Never do the same work twice", }} - href="/repo/docs/core-concepts/caching" + href="/AI/docs/core-concepts/caching" /> { description: `The way you run your tasks is probably not optimized. Turborepo speeds them up with smart scheduling, minimising idle CPU's.`, name: "Maximum Multitasking", }} - href="/repo/docs/core-concepts/monorepos/running-tasks" + href="/AI/docs/core-concepts/monorepos/running-tasks" > ); diff --git a/docs/components/RemoteCacheCounter.tsx b/docs/components/RemoteCacheCounter.tsx index ef4dc6e..7281887 100644 --- a/docs/components/RemoteCacheCounter.tsx +++ b/docs/components/RemoteCacheCounter.tsx @@ -29,7 +29,7 @@ export default function RemoteCacheCounter() { return (
diff --git a/docs/components/SiteSwitcher.tsx b/docs/components/SiteSwitcher.tsx index e5d58d2..6f6ba15 100644 --- a/docs/components/SiteSwitcher.tsx +++ b/docs/components/SiteSwitcher.tsx @@ -2,17 +2,17 @@ import cn from "classnames"; import { useRouter } from "next/router"; import Link from "next/link"; -export type TurboSite = "pack" | "repo"; +export type TurboSite = "TRPG" | "AI"; export function useTurboSite(): TurboSite | undefined { const { pathname } = useRouter(); - if (pathname.startsWith("/repo")) { - return "repo"; + if (pathname.startsWith("/AI")) { + return "AI"; } - if (pathname.startsWith("/pack")) { - return "pack"; + if (pathname.startsWith("/TRPG")) { + return "TRPG"; } return undefined; @@ -45,7 +45,7 @@ function SiteSwitcher() { "indeterminate:after:hidden", { "after:hidden": !site, - "after:translate-x-[46px]": site === "pack", + "after:translate-x-[46px]": site === "TRPG", } )} /> @@ -56,8 +56,8 @@ function SiteSwitcher() { { "hover:text-black dark:hover:text-white": site } )} > - - + +
); diff --git a/docs/components/Social.tsx b/docs/components/Social.tsx index df632f3..44e2cc2 100644 --- a/docs/components/Social.tsx +++ b/docs/components/Social.tsx @@ -20,7 +20,7 @@ function Discord() { diff --git a/docs/components/TurbopackFeatures.tsx b/docs/components/TurbopackFeatures.tsx deleted file mode 100644 index 5570a52..0000000 --- a/docs/components/TurbopackFeatures.tsx +++ /dev/null @@ -1,106 +0,0 @@ -import { - AdjustmentsIcon, - ArchiveIcon, - DesktopComputerIcon, - DownloadIcon, - ServerIcon, -} from "@heroicons/react/outline"; -import { DetailedFeatureLink } from "./Feature"; -import { CSSIcon, JSIcon, TSIcon } from "./Icons"; - -export const TurbopackFeatures = () => { - return ( -
- - - Supports TypeScript out of the box, including resolving{" "} - paths and baseUrl. - - ), - name: "TypeScript", - }} - href="/pack/docs/features/typescript" - > - - Supports require, import, dynamic - imports and more. - - ), - name: "Imports", - }} - href="/pack/docs/features/imports" - > - - - Supports Global CSS, CSS Modules, postcss-nested and{" "} - @import. - - ), - name: "CSS", - }} - href="/pack/docs/features/css" - > - - - Supports the /public directory, JSON imports, and - importing assets via ESM. - - ), - name: "Static Assets", - }} - href="/pack/docs/features/static-assets" - > - - Supports environment variables via .env,{" "} - .env.local, and more. - - ), - name: "Environment Variables", - }} - href="/pack/docs/features/environment-variables" - > -
- ); -}; diff --git a/docs/components/TurbopackQuickstart.tsx b/docs/components/TurbopackQuickstart.tsx deleted file mode 100644 index 695a947..0000000 --- a/docs/components/TurbopackQuickstart.tsx +++ /dev/null @@ -1,28 +0,0 @@ -import { - LightBulbIcon, - QuestionMarkCircleIcon, -} from "@heroicons/react/outline"; -import { DetailedFeatureLink } from "./Feature"; - -export const TurbopackQuickstartArea = () => { - return ( -
- - -
- ); -}; diff --git a/docs/components/pages/AI-home/AIFeatures.tsx b/docs/components/pages/AI-home/AIFeatures.tsx new file mode 100644 index 0000000..466c0ae --- /dev/null +++ b/docs/components/pages/AI-home/AIFeatures.tsx @@ -0,0 +1,15 @@ +import { REPO_HOME_FEATURES } from "../../../content/features"; +import { FadeIn } from "../home-shared/FadeIn"; +import { FeaturesBento } from "../home-shared/FeaturesBento"; + +export function AIFeatures() { + return ( + + + + ); +} diff --git a/docs/components/pages/AI-home/AIHero.tsx b/docs/components/pages/AI-home/AIHero.tsx new file mode 100644 index 0000000..5636cc2 --- /dev/null +++ b/docs/components/pages/AI-home/AIHero.tsx @@ -0,0 +1,114 @@ +import cn from "classnames"; +import Image from "next/image"; +import Link from "next/link"; +import gradients from "../home-shared/gradients.module.css"; +import { HeroText, SectionSubtext } from "../home-shared/Headings"; +import { Gradient } from "../home-shared/Gradient"; +import { FadeIn } from "../home-shared/FadeIn"; +import { CTAButton } from "../home-shared/CTAButton"; +import RepoLogo from "../../logos/RepoLogo"; + +export function AIHero() { + return ( + <> + + +
+ {/* TODO: On dark mode, there should be a "breathing" gradient inside the inner circle */} + AI + AI +
+
+ +
+ +
+ + +
+ + +
+ + + The build system that makes ship happen + + Turborepo is a high-performance build system for JavaScript and + TypeScript codebases. + + + +
+ + + Get Started + + + + + GitHub + + +
+

License: MPL-2.0

+ + +
+ + + + ); +} diff --git a/docs/components/pages/AI-home/AILetter.tsx b/docs/components/pages/AI-home/AILetter.tsx new file mode 100644 index 0000000..a92f9dd --- /dev/null +++ b/docs/components/pages/AI-home/AILetter.tsx @@ -0,0 +1,118 @@ +import { HeroText } from "../home-shared/Headings"; +import Image from "next/image"; +import cn from "classnames"; +import gradients from "../home-shared/gradients.module.css"; +import { FadeIn } from "../home-shared/FadeIn"; +import { CTAButton } from "../home-shared/CTAButton"; +import Link from "next/link"; +import { Gradient } from "../home-shared/Gradient"; + +export function AILetter() { + return ( +
+ + + Scaling your Codebase +
+ shouldn't be so difficult + + +
+ +

+ The bigger your project grows, the slower it gets. Tasks like + linting, testing, and building begin to take enormous amounts of + time. +

+
+

+ If you're serving multiple applications, you might reach for a + monorepo. They're incredible for productivity, especially on + the frontend, but the tooling can be a nightmare. There's a lot + of stuff to do (and things to mess up). Nothing “just + works.” It's become completely normal to waste entire + days or weeks on plumbing—tweaking configs, writing one-off scripts, + and stitching stuff together. +

+
+

We need something else.

+

+

+ A fresh take on the whole setup. Designed to glue everything + together. A toolchain that works for you and not against you. With + sensible defaults, but even better escape hatches. Built with the + same techniques used by the big guys, but in a way that doesn't + require PhD to learn or a staff to maintain. +

+
+

With Turborepo, we're doing just that.

+
+

+ We're building a build system that can keep up with your team. + You'll see your CI get faster, duplicated work get cut, and + your NPM scripts get simpler. You'll get a world-class + development environment, without the maintenance burden. +

+ + + + + +
+ Image of Jared Palmer +
+
+ Jared Palmer's hand written signature + Jared Palmer's hand written signature +
+

Jared Palmer

+

Founder of Turborepo

+
+
+ +
+ +
+ + + Start Building + + +
+ + +
+ ); +} diff --git a/docs/components/pages/AI-home/index.tsx b/docs/components/pages/AI-home/index.tsx new file mode 100644 index 0000000..b65040c --- /dev/null +++ b/docs/components/pages/AI-home/index.tsx @@ -0,0 +1,22 @@ +import { AIHero } from "./AIHero"; +import { AIFeatures } from "./AIFeatures"; +import { AILetter } from "./AILetter"; +import { GradientSectionBorder } from "../home-shared/GradientSectionBorder"; +import { LandingPageGlobalStyles } from "../home-shared/GlobalStyles"; + +export default function HydroRollAIHome() { + return ( + <> + +
+ + + + + + + +
+ + ); +} diff --git a/docs/components/pages/confirm.tsx b/docs/components/pages/confirm.tsx index b9295cf..ae54cd0 100644 --- a/docs/components/pages/confirm.tsx +++ b/docs/components/pages/confirm.tsx @@ -23,7 +23,7 @@ export default function Confirm() {

Thanks,
- The Turbo Team + The HydroRoll'水系 Team.

diff --git a/docs/components/pages/landing/HydroRollAI.tsx b/docs/components/pages/landing/HydroRollAI.tsx new file mode 100644 index 0000000..d299fed --- /dev/null +++ b/docs/components/pages/landing/HydroRollAI.tsx @@ -0,0 +1,27 @@ +import Image from "next/image"; + +export function HydroRollAI() { + return ( +
+
+
+ HydroRollAI Logo +
+
+ HydroRollAI Logo +
+
+ ); +} diff --git a/docs/components/pages/landing/HydroRollTRPG.tsx b/docs/components/pages/landing/HydroRollTRPG.tsx new file mode 100644 index 0000000..27cd838 --- /dev/null +++ b/docs/components/pages/landing/HydroRollTRPG.tsx @@ -0,0 +1,27 @@ +import Image from "next/image"; + +export function HydroRollTRPG() { + return ( +
+
+
+ +
+
+ +
+
+ ); +} diff --git a/docs/components/pages/landing/Turbopack.tsx b/docs/components/pages/landing/Turbopack.tsx deleted file mode 100644 index 1db1076..0000000 --- a/docs/components/pages/landing/Turbopack.tsx +++ /dev/null @@ -1,27 +0,0 @@ -import Image from "next/image"; - -export function Turbopack() { - return ( -
-
-
- -
-
- -
-
- ); -} diff --git a/docs/components/pages/landing/Turborepo.tsx b/docs/components/pages/landing/Turborepo.tsx deleted file mode 100644 index 022f37f..0000000 --- a/docs/components/pages/landing/Turborepo.tsx +++ /dev/null @@ -1,27 +0,0 @@ -import Image from "next/image"; - -export function Turborepo() { - return ( -
-
-
- Turborepo Logo -
-
- Turborepo Logo -
-
- ); -} diff --git a/docs/components/pages/landing/index.tsx b/docs/components/pages/landing/index.tsx index deb63f3..239d696 100644 --- a/docs/components/pages/landing/index.tsx +++ b/docs/components/pages/landing/index.tsx @@ -6,8 +6,8 @@ import { motion } from "framer-motion"; import { Clients } from "../../clients/Clients"; import { Marquee } from "../../clients/Marquee"; import { TurboheroBackground } from "./TurboHeroBackground"; -import { Turborepo } from "./Turborepo"; -import { Turbopack } from "./Turbopack"; +import { HydroRollAI } from "./HydroRollAI"; +import { HydroRollTRPG } from "./HydroRollTRPG"; import { FadeIn } from "../home-shared/FadeIn"; import { LandingPageGlobalStyles } from "../home-shared/GlobalStyles"; import styles from "./index.module.css"; @@ -116,9 +116,9 @@ function SiteCards() {
@@ -130,10 +130,10 @@ function SiteCards() {
diff --git a/docs/components/pages/pack-home/PackBenchmarksGraph.tsx b/docs/components/pages/pack-home/PackBenchmarksGraph.tsx index a4792b8..f3107b0 100644 --- a/docs/components/pages/pack-home/PackBenchmarksGraph.tsx +++ b/docs/components/pages/pack-home/PackBenchmarksGraph.tsx @@ -230,15 +230,15 @@ const GraphTimer = ({ {turbo && (
Turbopack Turbopack React Components diff --git a/docs/components/pages/pack-home/PackFeatures.tsx b/docs/components/pages/pack-home/PackFeatures.tsx index b668153..40fda95 100644 --- a/docs/components/pages/pack-home/PackFeatures.tsx +++ b/docs/components/pages/pack-home/PackFeatures.tsx @@ -4,7 +4,7 @@ import { FeaturesBento } from "../home-shared/FeaturesBento"; export function PackFeatures() { return ( diff --git a/docs/components/pages/pack-home/PackHero.tsx b/docs/components/pages/pack-home/PackHero.tsx index eb5b348..9def8df 100644 --- a/docs/components/pages/pack-home/PackHero.tsx +++ b/docs/components/pages/pack-home/PackHero.tsx @@ -20,15 +20,15 @@ export function PackHero() {
Turbopack Turbopack
- + Get Started @@ -97,7 +97,7 @@ export function PackHero() { GitHub diff --git a/docs/components/pages/pack-home/PackLetter.tsx b/docs/components/pages/pack-home/PackLetter.tsx index d4b0f2f..46477d7 100644 --- a/docs/components/pages/pack-home/PackLetter.tsx +++ b/docs/components/pages/pack-home/PackLetter.tsx @@ -73,7 +73,7 @@ export function PackLetter() {
Tobias Koppers hand written signature Tobias Koppers hand written signature
- + Start Building diff --git a/docs/components/pages/pack-home/index.tsx b/docs/components/pages/pack-home/index.tsx index db73b25..d08443b 100644 --- a/docs/components/pages/pack-home/index.tsx +++ b/docs/components/pages/pack-home/index.tsx @@ -5,7 +5,7 @@ import { PackFeatures } from "./PackFeatures"; import { GradientSectionBorder } from "../home-shared/GradientSectionBorder"; import { LandingPageGlobalStyles } from "../home-shared/GlobalStyles"; -export default function Home() { +export default function HydroRollTRPGHome() { return ( <> diff --git a/docs/components/pages/repo-home/RepoFeatures.tsx b/docs/components/pages/repo-home/RepoFeatures.tsx deleted file mode 100644 index 4499725..0000000 --- a/docs/components/pages/repo-home/RepoFeatures.tsx +++ /dev/null @@ -1,15 +0,0 @@ -import { REPO_HOME_FEATURES } from "../../../content/features"; -import { FadeIn } from "../home-shared/FadeIn"; -import { FeaturesBento } from "../home-shared/FeaturesBento"; - -export function RepoFeatures() { - return ( - - - - ); -} diff --git a/docs/components/pages/repo-home/RepoHero.tsx b/docs/components/pages/repo-home/RepoHero.tsx deleted file mode 100644 index a63777a..0000000 --- a/docs/components/pages/repo-home/RepoHero.tsx +++ /dev/null @@ -1,114 +0,0 @@ -import cn from "classnames"; -import Image from "next/image"; -import Link from "next/link"; -import gradients from "../home-shared/gradients.module.css"; -import { HeroText, SectionSubtext } from "../home-shared/Headings"; -import { Gradient } from "../home-shared/Gradient"; -import { FadeIn } from "../home-shared/FadeIn"; -import { CTAButton } from "../home-shared/CTAButton"; -import RepoLogo from "../../logos/RepoLogo"; - -export function RepoHero() { - return ( - <> - - -
- {/* TODO: On dark mode, there should be a "breathing" gradient inside the inner circle */} - Turborepo - Turborepo -
-
- -
- -
- - -
- - -
- - - The build system that makes ship happen - - Turborepo is a high-performance build system for JavaScript and - TypeScript codebases. - - - - -

License: MPL-2.0

- - -
- - - - ); -} diff --git a/docs/components/pages/repo-home/RepoLetter.tsx b/docs/components/pages/repo-home/RepoLetter.tsx deleted file mode 100644 index 7093a3a..0000000 --- a/docs/components/pages/repo-home/RepoLetter.tsx +++ /dev/null @@ -1,118 +0,0 @@ -import { HeroText } from "../home-shared/Headings"; -import Image from "next/image"; -import cn from "classnames"; -import gradients from "../home-shared/gradients.module.css"; -import { FadeIn } from "../home-shared/FadeIn"; -import { CTAButton } from "../home-shared/CTAButton"; -import Link from "next/link"; -import { Gradient } from "../home-shared/Gradient"; - -export function RepoLetter() { - return ( -
- - - Scaling your Codebase -
- shouldn't be so difficult - - -
- -

- The bigger your project grows, the slower it gets. Tasks like - linting, testing, and building begin to take enormous amounts of - time. -

-
-

- If you're serving multiple applications, you might reach for a - monorepo. They're incredible for productivity, especially on - the frontend, but the tooling can be a nightmare. There's a lot - of stuff to do (and things to mess up). Nothing “just - works.” It's become completely normal to waste entire - days or weeks on plumbing—tweaking configs, writing one-off scripts, - and stitching stuff together. -

-
-

We need something else.

-

-

- A fresh take on the whole setup. Designed to glue everything - together. A toolchain that works for you and not against you. With - sensible defaults, but even better escape hatches. Built with the - same techniques used by the big guys, but in a way that doesn't - require PhD to learn or a staff to maintain. -

-
-

With Turborepo, we're doing just that.

-
-

- We're building a build system that can keep up with your team. - You'll see your CI get faster, duplicated work get cut, and - your NPM scripts get simpler. You'll get a world-class - development environment, without the maintenance burden. -

- - - - - -
- Image of Jared Palmer -
-
- Jared Palmer's hand written signature - Jared Palmer's hand written signature -
-

Jared Palmer

-

Founder of Turborepo

-
-
- -
- -
- - - Start Building - - -
- - -
- ); -} diff --git a/docs/components/pages/repo-home/index.tsx b/docs/components/pages/repo-home/index.tsx deleted file mode 100644 index 992a614..0000000 --- a/docs/components/pages/repo-home/index.tsx +++ /dev/null @@ -1,22 +0,0 @@ -import { RepoHero } from "./RepoHero"; -import { RepoFeatures } from "./RepoFeatures"; -import { RepoLetter } from "./RepoLetter"; -import { GradientSectionBorder } from "../home-shared/GradientSectionBorder"; -import { LandingPageGlobalStyles } from "../home-shared/GlobalStyles"; - -export default function Home() { - return ( - <> - -
- - - - - - - -
- - ); -} diff --git a/docs/components/pages/showcase.tsx b/docs/components/pages/showcase.tsx index 62c8f50..922f943 100644 --- a/docs/components/pages/showcase.tsx +++ b/docs/components/pages/showcase.tsx @@ -11,7 +11,7 @@ export default function Showcase() { Showcase

- Who's using Turbo? + Wut about plugins?

Turbo is the one of the fastest growing toolchains in the frontend @@ -28,16 +28,16 @@ export default function Showcase() {

- Are you using Turbo? + Are you using HydroRoll?
diff --git a/docs/next.config.js b/docs/next.config.js index 653658f..d92dbc6 100644 --- a/docs/next.config.js +++ b/docs/next.config.js @@ -12,43 +12,11 @@ const sentryWebpackPluginOptions = { const OLD_TURBOREPO_ROUTES = [ "/docs", - "/docs/ci/circleci", - "/docs/ci/github-actions", - "/docs/ci/gitlabci", - "/docs/ci/travisci", - "/docs/core-concepts/caching", - "/docs/core-concepts/remote-caching", - "/docs/core-concepts/scopes", - "/docs/core-concepts/monorepos/filtering", - "/docs/core-concepts/monorepos/running-tasks", "/docs/getting-started/create-new", "/docs/getting-started/existing-monorepo", - "/docs/handbook", - "/docs/handbook/building-your-app", - "/docs/handbook/deploying-with-docker", - "/docs/handbook/dev", - "/docs/handbook/linting", - "/docs/handbook/migrating-to-a-monorepo", - "/docs/handbook/package-installation", - "/docs/handbook/publishing-packages", - "/docs/handbook/sharing-code", - "/docs/handbook/testing", - "/docs/handbook/troubleshooting", - "/docs/handbook/what-is-a-monorepo", - "/docs/handbook/workspaces", - "/docs/handbook/linting/eslint", - "/docs/handbook/linting/typescript", - "/docs/handbook/publishing-packages/bundling", - "/docs/handbook/publishing-packages/versioning-and-publishing", - "/docs/handbook/sharing-code/internal-packages", - "/docs/reference/codemods", - "/docs/reference/command-line-reference", - "/docs/reference/configuration", "/docs/acknowledgements", - "/docs/ci", "/docs/faq", "/docs/troubleshooting", - "/docs/upgrading-to-v1", ]; const nextConfig = withNextra({ @@ -86,52 +54,12 @@ const nextConfig = withNextra({ return [ ...OLD_TURBOREPO_ROUTES.map((route) => ({ source: route, - destination: `/repo${route}`, + destination: `/AI${route}`, permanent: true, })), { source: "/docs/getting-started", - destination: "/repo/docs", - permanent: true, - }, - { - source: "/usage", - destination: "/repo/docs/reference/command-line-reference", - permanent: true, - }, - { - source: "/docs/core-concepts/running-tasks", - destination: "/repo/docs/core-concepts/monorepos/running-tasks", - permanent: true, - }, - { - source: "/docs/core-concepts/why-turborepo", - destination: "/repo/docs/core-concepts/monorepos", - permanent: true, - }, - { - source: "/docs/core-concepts/filtering", - destination: "/repo/docs/core-concepts/monorepos/filtering", - permanent: true, - }, - { - source: "/docs/guides/workspaces", - destination: "/repo/docs/handbook/workspaces", - permanent: true, - }, - { - source: "/docs/core-concepts/workspaces", - destination: "/repo/docs/handbook/workspaces", - permanent: true, - }, - { - source: "/docs/core-concepts/pipelines", - destination: "/repo/docs/core-concepts/monorepos/running-tasks", - permanent: true, - }, - { - source: "/docs/guides/migrate-from-lerna", - destination: "/repo/docs/handbook/migrating-to-a-monorepo", + destination: "/AI/docs", permanent: true, }, { @@ -144,84 +72,10 @@ const nextConfig = withNextra({ permanent: true, destination: "https://github.com/retrofor/HydroRoll/releases", }, - { - source: "/docs/guides/complimentary-tools", - permanent: true, - destination: "/repo/docs/handbook", - }, - { - source: "/docs/guides/monorepo-tools", - permanent: true, - destination: "/repo/docs/handbook", - }, - { - source: "/docs/glossary", - permanent: true, - destination: "/repo/docs/handbook", - }, - { - source: "/docs/guides/continuous-integration", - permanent: true, - destination: "/repo/docs/ci", - }, - { - source: "/repo/docs/handbook/prisma", - permanent: true, - destination: "/repo/docs/handbook/tools/prisma", - }, - { - source: "/pack/docs/comparisons/turbopack-vs-vite", - permanent: true, - destination: "/pack/docs/comparisons/vite", - }, - { - source: "/pack/docs/comparisons/turbopack-vs-webpack", - permanent: true, - destination: "/pack/docs/comparisons/webpack", - }, - { - // Accidentally created, eventually removable. See below. - source: "/repo/docs/core-concepts/running-tasks", - destination: "/repo/docs/core-concepts/monorepos/running-tasks", - permanent: true, - }, - { - // Accidentally created, eventually removable. See below. - source: "/repo/docs/core-concepts/why-turborepo", - destination: "/repo/docs/core-concepts/monorepos", - permanent: true, - }, - { - // Accidentally created, eventually removable. See below. - source: "/repo/docs/core-concepts/filtering", - destination: "/repo/docs/core-concepts/monorepos/filtering", - permanent: true, - }, - { - // Accidentally created, eventually removable. See below. - source: "/repo/docs/core-concepts/pipelines", - destination: "/repo/docs/core-concepts/monorepos/running-tasks", - permanent: true, - }, - { - // This rule accidentally created a bunch of URLs. - // - // They've _never_ resolved, so _eventually_ we should be able to remove the - // redirects we added above to fix them. - source: "/docs/features/:path*", - permanent: true, - destination: "/repo/docs/core-concepts/:path*", - }, - { - // Accidentally created, eventually removable. See below. - source: "/repo/docs/getting-started", - destination: "/repo/docs", - permanent: true, - }, { // Accidentally created, eventually removable. See below. - source: "/repo/docs/guides/workspaces", - destination: "/repo/docs/handbook/workspaces", + source: "/AI/docs/getting-started", + destination: "/AI/docs", permanent: true, }, { @@ -231,7 +85,7 @@ const nextConfig = withNextra({ // redirects we added above to fix them. source: "/docs/:path*", permanent: true, - destination: "/repo/docs/:path*", + destination: "/AI/docs/:path*", }, ]; }, diff --git a/docs/package.json b/docs/package.json index 4abfc5c..3a0af2b 100644 --- a/docs/package.json +++ b/docs/package.json @@ -11,7 +11,7 @@ "rss": "node scripts/generate-rss.js", "schema": "turbo-types-generate ./public/schema.json" }, - "author": "Jared Palmer", + "author": "简律纯", "license": "MPL-2.0", "dependencies": { "@headlessui/react": "^1.7.3", diff --git a/docs/pages/AI/_meta.json b/docs/pages/AI/_meta.json new file mode 100644 index 0000000..4941080 --- /dev/null +++ b/docs/pages/AI/_meta.json @@ -0,0 +1,15 @@ +{ + "index": { + "type": "page", + "display": "hidden", + "theme": { + "layout": "raw", + "sidebar": false, + "toc": true + } + }, + "docs": { + "title": "Docs", + "display": "children" + } +} diff --git a/docs/pages/AI/docs/_meta.json b/docs/pages/AI/docs/_meta.json new file mode 100644 index 0000000..939e2df --- /dev/null +++ b/docs/pages/AI/docs/_meta.json @@ -0,0 +1,15 @@ +{ + "index": { + "title": "Quickstart" + }, + "installing": "Installing AI", + "getting-started": "Getting Started", + "troubleshooting": "Troubleshooting", + "changelog": { + "title": "Changelog", + "href": "https://github.com/retrofor/HydroRoll/releases", + "newWindow": true + }, + "acknowledgements": "Acknowledgements", + "faq": "FAQ" +} diff --git a/docs/pages/AI/docs/acknowledgements.mdx b/docs/pages/AI/docs/acknowledgements.mdx new file mode 100644 index 0000000..50a5c46 --- /dev/null +++ b/docs/pages/AI/docs/acknowledgements.mdx @@ -0,0 +1,45 @@ +--- +title: Acknowledgements and Prior Art +description: Thank you to all these developers, build systems, and monorepo tools for their support and assistance. +--- + +# Acknowledgements + +Turborepo was originally created by [Jared Palmer](https://twitter.com/jaredpalmer) as a closed-source enterprise software offering. In late 2021, [Vercel acquired Turborepo](https://vercel.com/blog/vercel-acquires-turborepo) and open sourced the codebase. + +Today, Turborepo has dedicated full-time team working on it as well as a growing list of [open source contributors](https://github.com/vercel/turbo/graphs/contributors). + +## Inspiration / Prior Art + +At [Vercel](https://vercel.com/), we believe deeply in the open source movement and in the power of open collaboration. To that end, it's important to provide meaningful attribution to the projects and people that inspire(d) us and our work. + +We'd like to make a special shoutout to other build systems, monorepo tools, and prior art: + +- Bazel - https://bazel.build +- Buck - https://buck.build +- Please - https://please.build +- Pants - https://www.pantsbuild.org +- Scoot - https://github.com/twitter/scoot +- TSDX - https://tsdx.io +- Lerna - https://lerna.js.org +- Lage - https://microsoft.github.io/lage +- Backfill - https://github.com/microsoft/backfill +- Bolt - https://github.com/boltpkg/bolt +- Rush - https://rushjs.io +- Preconstruct - https://preconstruct.tools +- Nx - https://nx.dev +- Yarn - https://yarnpkg.com +- npm - https://www.npmjs.com +- pnpm - https://pnpm.js.org + +Throughout the documentation, wherever applicable, we also provide inline callouts and links to the projects and people that have inspired us. + +## Additional Thanks + +Additionally, we're grateful to: + +- [Rick Button](https://twitter.com/rickbutton) for donating the `turbo` package name on npm +- [Iheanyi Ekechukwu](https://twitter.com/kwuchu) for helping Jared pick up Golang during the Pandemic! +- [Kenneth Chau](https://twitter.com/kenneth_chau) for Lage's Scope and Pipeline API and docs +- [Miguel Oller](https://mobile.twitter.com/ollermi) and [MakeSwift.com](https://www.makeswift.com/) for piloting Turborepo +- [Eric Koslow](https://twitter.com/ekosz1), [Jack Hanford](https://twitter.com/jackhanford), and [Lattice.com](https://lattice.com/) for piloting Turborepo diff --git a/docs/pages/AI/docs/faq.mdx b/docs/pages/AI/docs/faq.mdx new file mode 100644 index 0000000..6039dae --- /dev/null +++ b/docs/pages/AI/docs/faq.mdx @@ -0,0 +1,51 @@ +--- +title: Frequently Asked Questions +description: Frequently asked questions about AI. +--- + +import Callout from '../../../components/Callout' + +# Frequently Asked Questions + +## Should I install AI globally? + +You have two options when working with AI: + +1. Install it globally, via `npm install --global turbo` +2. Install a local version in your project + +We recommend installing the `turbo` CLI globally. This gives you a smooth, ergonomic experience for running tasks. + +## Do I have to use Remote Caching to use AI? + +No. [Remote Caching](/AI/docs/core-concepts/remote-caching) is optional. However, you'll find it very useful to speed up development on a team, speed up builds inside of Docker, and also save space on your own machine. + +## Does AI / Remote Caching store my source code? + +No. AI does not store source code. Without [Remote Caching](/AI/docs/core-concepts/remote-caching), no code ever leaves your machine—it will only cache artifacts to local disk. + +With AI's Remote Caching, you are responsible for configuring cache behavior and should only set up AI to cache compiled artifacts. Please be aware that AI treats all logs as artifacts and so these _will_ be stored along with other cache artifacts. + +## Do I have to use Vercel to use AI? + +No. AI is an open-source project and is not tied to any specific hosting provider or Remote Cache provider. The default Remote Cache provider is Vercel, should you opt-in to enable it. However, you can use any other provider you like if they support the same API. Several open-source community Remote Caches are compatible with AI. + +## Can I use AI with a different Remote Cache provider other than Vercel? + +Yes. As long as the [Remote Cache](/AI/docs/core-concepts/remote-caching) provider you choose supports the same API, you can use AI with it. + +## Does AI collect any personally identifiable information? + +Due to the nature of AI's functionality, no personal information is gathered when the open source binary is run locally. All cached artifacts are stored on your machine by default. Further, no log in information or contact details are collected by the `turbo` CLI, so AI will never have access to any personally identifiable information. Thus, for any data privacy questions and concerns please refer to [AI's Privacy Policy](/privacy). + +## Does AI collect any personally identifiable information when using Remote Caching? + +When [Remote Caching](/AI/docs/core-concepts/remote-caching) is enabled, by default AI will utilize your Vercel account to cache artifacts in the cloud. Thus, for any data privacy questions and concerns, please refer to [AI's Privacy Policy](/privacy) and [Vercel's Privacy Policy](https://vercel.com/legal/privacy-policy). If you use a different Remote Cache provider, please refer to the provider's privacy policy. + +## How can I retain Fast Refresh in my AI when using multiple Next.js applications? + +[Fast Refresh](https://nextjs.org/docs/basic-features/fast-refresh) gives you instantaneous feedback on edits made to your React components in Next.js applications. + +If your AI has multiple Next.js applications, you can use `transpilePackages` inside `next.config.js` to ensure that imports across workspaces will work with Fast Refresh when changes are made. AI will effectively watch for any edits and the rebuild when saving. You can get started from [this example](https://github.com/vercel/turbo/tree/main/examples/basic) which is set up to handle Fast Refresh. + +If you are using a Next.js version below 13, you will want to use [`next-transpile-modules`](https://www.npmjs.com/package/next-transpile-modules) for the same Fast Refresh behavior. diff --git a/docs/pages/AI/docs/getting-started/_meta.json b/docs/pages/AI/docs/getting-started/_meta.json new file mode 100644 index 0000000..2ed5b29 --- /dev/null +++ b/docs/pages/AI/docs/getting-started/_meta.json @@ -0,0 +1,6 @@ +{ + "add-to-project": "Add to Existing Project", + "from-example": "Start from an Example", + "create-new": "Create a New Monorepo", + "existing-monorepo": "Add to Existing Monorepo" +} diff --git a/docs/pages/AI/docs/getting-started/add-to-project.mdx b/docs/pages/AI/docs/getting-started/add-to-project.mdx new file mode 100644 index 0000000..7f7ecec --- /dev/null +++ b/docs/pages/AI/docs/getting-started/add-to-project.mdx @@ -0,0 +1,147 @@ +import { Tabs, Tab } from '../../../../components/Tabs' + +# Add Turborepo to your existing project + +Turborepo can be used in **any project** to speed up the execution of scripts in your `package.json`. + +After you install `turbo`, you'll be able to run all your `package.json` tasks from `turbo` instead of your package manager. + +By configuring your `turbo.json` correctly, you'll notice how [caching](/AI/docs/core-concepts/caching) helps your tasks run a lot faster. + +## Quickstart + +0. **If you don't have one already, create a new application:** + + + +```bash +npx create-next-app@latest +``` + + +```bash +npm create vite@latest +``` + + + +1. **Install `turbo` globally:** + + + + ```bash + npm install turbo --global + ``` + + + ```bash + yarn global add turbo + ``` + + + ```bash + pnpm add turbo --global + ``` + + + +For more details about installation, see [Installing Turborepo](../installing) + +2. **Add a `turbo.json` file at the base of your new repository:** + +For more information on configuring your `turbo.json`, see the [Configuration Options](/AI/docs/reference/configuration) documentation. + + + +```json filename="turbo.json" +{ + "$schema": "https://turbo.build/schema.json", + "pipeline": { + "build": { + "outputs": [".next/**", "!.next/cache/**"] + }, + "lint": {} + } +} +``` + + +```json filename="turbo.json" +{ + "$schema": "https://turbo.build/schema.json", + "pipeline": { + "build": { + "outputs": ["dist/**"] + }, + "lint": {} + } +} +``` + +Some Vite starters ship with a `package.json` that looks like this: + +```json filename="package.json" +{ + "scripts": { + "build": "tsc && vite build" + } +} +``` + +We recommend splitting these into a `lint` and `build` script. + +```json filename="package.json" +{ + "scripts": { + "build": "vite build", + "lint": "tsc" + } +} +``` + +This means that Turbo can schedule them separately. + + + + +3. **Edit `.gitignore`** + +Add `.turbo` to your `.gitignore` file. The CLI uses these folders for logs and certain task outputs. + +```diff ++ .turbo +``` + +4. **Try running `build` and `lint` with `turbo`:** + +```bash +turbo build lint +``` + +This runs `build` and `lint` at the same time. + +5. **Without making any changes to the code, try running `build` and `lint` again:** + +```bash +turbo build lint +``` + +You should see terminal output like this: + +``` + Tasks: 2 successful, 2 total +Cached: 2 cached, 2 total + Time: 185ms >>> FULL TURBO +``` + +Congratulations - **you just completed a build and lint in under 200ms**. + +To learn how this is possible, check out our [core concepts docs](/AI/docs/core-concepts/caching). + +6. **Try running `dev` with `turbo`:** + +```bash +turbo dev +``` + +You'll notice that your `dev` script starts up. You can use `turbo` to run any script in your `package.json`. diff --git a/docs/pages/AI/docs/getting-started/create-new.mdx b/docs/pages/AI/docs/getting-started/create-new.mdx new file mode 100644 index 0000000..aa16eb4 --- /dev/null +++ b/docs/pages/AI/docs/getting-started/create-new.mdx @@ -0,0 +1,527 @@ +--- +title: Getting Started with AI +description: Create your first monorepo or add AI to an existing project. +--- + +import Callout from "../../../../components/Callout"; +import { Tabs, Tab } from "../../../../components/Tabs"; + +# Creating a new monorepo + + + This guide uses a global installation of `turbo`. Follow the [installation guide](../installing) + to get this setup. Alternatively, you can use your package manager to run a locally installed `turbo` + in the commands below. + + +## Quickstart + +To create a new monorepo, use our [`create-turbo`](https://www.npmjs.com/package/create-turbo) npm package: + + + + ```sh + npx create-turbo@latest + ``` + + + ```sh + yarn dlx create-turbo@latest + ``` + + + ```sh + pnpm dlx create-turbo@latest + ``` + + + +You can also clone a AI starter repository to get a head start on your monorepo. To see AI examples and starters, see the [AI examples directory on GitHub](https://github.com/vercel/turbo/tree/main/examples). + +## Full tutorial + +This tutorial will walk you through setting up a basic example. By the end, you'll feel confident with using `turbo`, and know all the basic functionality. + + + +During this tutorial, some lines of code are omitted from the code samples. For instance, when showing a `package.json` we won't show _all_ of the keys - only the ones that matter. + + + +### 1. Running `create-turbo` + +First, run: + + + + ```sh + npx create-turbo@latest + ``` + + + ```sh + yarn dlx create-turbo@latest + ``` + + + ```sh + pnpm dlx create-turbo@latest + ``` + + + +This installs the [`create-turbo`](https://www.npmjs.com/package/create-turbo) CLI, and runs it. You'll be asked several questions: + +#### Where would you like to create your AI? + +Choose anywhere you like. The default is `./my-AI`. + +#### Which package manager do you want to use? + +AI doesn't handle installing packages, so you'll need to choose either: + +- [npm](https://www.npmjs.com//) +- [pnpm](https://pnpm.io/) +- [yarn](https://yarnpkg.com/) + +If you're not sure, we recommend choosing `pnpm`. If you don't have it installed, cancel `create-turbo` (via `ctrl-C`) and take a look at the [installation instructions](https://pnpm.io/installation). + +#### Installation + +Once you've picked a package manager, `create-turbo` will create a bunch of new files inside the folder name you picked. It'll also install all the dependencies that come with the `basic` example by default. + +### 2. Exploring your new repo + +You might have noticed something in the terminal. `create-turbo` gave you a description of all of the things it was adding. + +``` +>>> Creating a new AI with the following: + + - apps/web: Next.js with TypeScript + - apps/docs: Next.js with TypeScript + - packages/ui: Shared React component library + - packages/eslint-config-custom: Shared configuration (ESLint) + - packages/tsconfig: Shared TypeScript `tsconfig.json` +``` + +Each of these is a _workspace_ - a folder containing a `package.json`. Each workspace can declare its own dependencies, run its own scripts, and export code for other workspaces to use. + +Open the root folder - `./my-AI` - in your favourite code editor. + +#### Understanding `packages/ui` + +First, open `./packages/ui/package.json`. You'll notice that the package's name is `"name": "ui"` - right at the top of the file. + +Next, open `./apps/web/package.json`. You'll notice that this package's name is `"name": "web"`. But also - take a look in its dependencies. + +You'll see that `"web"` depends on a package called `"ui"`. If you're using `pnpm`, you'll see it's declared like this: + + + + ```json filename="apps/web/package.json" + { + "dependencies": { + "ui": "*" + } + } + ``` + + + ```json filename="apps/web/package.json" + { + "dependencies": { + "ui": "*" + } + } + ``` + + + ```json filename="apps/web/package.json" + { + "dependencies": { + "ui": "workspace:*" + } + } + ``` + + + +This means that our **web app depends on our local `ui` package**. + +If you look inside `apps/docs/package.json`, you'll see the same thing. Both `web` and `docs` depend on `ui` - a shared component library. + +This pattern of sharing code across applications is extremely common in monorepos - and means that multiple apps can share a single design system. + +#### Understanding imports and exports + +Take a look inside `./apps/docs/pages/index.tsx`. Both `docs` and `web` are [Next.js](https://nextjs.org/) applications, and they both use the `ui` library in a similar way: + +```tsx filename="apps/docs/pages/index.tsx" +import { Button } from "ui"; +// ^^^^^^ ^^ + +export default function Docs() { + return ( +
+

Docs

+
+ ); +} +``` + +They're importing `Button` directly from a dependency called `ui`! How does that work? Where is `Button` coming from? + +Open `packages/ui/package.json`. You'll notice these two attributes: + +```json filename="packages/ui/package.json" +{ + "main": "./index.tsx", + "types": "./index.tsx" +} +``` + +When workspaces import from `ui`, `main` tells them where to access the code they're importing. `types` tells them where the TypeScript types are located. + +So, let's look inside `packages/ui/index.tsx`: + +```tsx filename="packages/ui/index.tsx" +import * as React from "react"; +export * from "./Button"; +``` + +Everything inside this file will be able to be used by workspaces that depend on `ui`. + +`index.tsx` is exporting everything from a file called `./Button`, so let's go there: + +```tsx filename="packages/ui/Button.tsx" +import * as React from "react"; + +export const Button = () => { + return ; +}; +``` + +We've found our button! Any changes we make in this file will be shared across `web` and `docs`. Pretty cool! + + + +Try experimenting with exporting a different function from this file. Perhaps `add(a, b)` for adding two numbers together. + +This can then be imported by `web` and `docs`. + + + +#### Understanding `tsconfig` + +We have two more workspaces to look at, `tsconfig` and `eslint-config-custom`. Each of these allow for shared configuration across the monorepo. Let's look in `tsconfig`: + +```json filename="packages/tsconfig/package.json" +{ + "name": "tsconfig", + "files": ["base.json", "nextjs.json", "react-library.json"] +} +``` + +Here, we specify three files to be exported, inside `files`. Packages which depend on `tsconfig` can then import them directly. + +For instance, `packages/ui` depends on `tsconfig`: + + + + ```json filename="packages/ui/package.json" + { + "devDependencies": { + "tsconfig": "*" + } + } + ``` + + + ```json filename="packages/ui/package.json" + { + "devDependencies": { + "tsconfig": "*" + } + } + ``` + + + ```json filename="packages/ui/package.json" + { + "devDependencies": { + "tsconfig": "workspace:*" + } + } + ``` + + + +And inside its `tsconfig.json` file, it imports it using `extends`: + +```json filename="packages/ui/tsconfig.json" +{ + "extends": "tsconfig/react-library.json" +} +``` + +This pattern allows for a monorepo to share a single `tsconfig.json` across all its workspaces, reducing code duplication. + +#### Understanding `eslint-config-custom` + +Our final workspace is `eslint-config-custom`. + +You'll notice that this is named slightly differently to the other workspaces. It's not as concise as `ui` or `tsconfig`. Let's take a look inside `.eslintrc.js` in the root of the monorepo to figure out why. + +```ts filename=".eslintrc.js" +module.exports = { + // This tells ESLint to load the config from the workspace `eslint-config-custom` + extends: ["custom"], +}; +``` + +[ESLint](https://eslint.org/) resolves configuration files by looking for workspaces with the name `eslint-config-*`. This lets us write `extends: ['custom']` and have ESLint find our local workspace. + +But why is this in the root of the monorepo? + +The way ESLint finds its configuration file is by looking at the closest `.eslintrc.js`. If it can't find one in the current directory, it'll look in the directory above until it finds one. + +So that means that if we're working on code inside `packages/ui` (which doesn't have a `.eslintrc.js`) it'll refer to the _root_ instead. + +Apps that _do_ have an `.eslintrc.js` can refer to `custom` in the same way. For instance, in `docs`: + +```ts filename="apps/docs/.eslintrc.js" +module.exports = { + root: true, + extends: ["custom"], +}; +``` + +Just like `tsconfig`, `eslint-config-custom` lets us share ESLint configs across our entire monorepo, keeping things consistent no matter what project you're working on. + +#### Summary + +It's important to understand the dependencies between these workspaces. Let's map them out: + +- `web` - depends on `ui`, `tsconfig` and `eslint-config-custom` +- `docs` - depends on `ui`, `tsconfig` and `eslint-config-custom` +- `ui` - depends on `tsconfig` and `eslint-config-custom` +- `tsconfig` - no dependencies +- `eslint-config-custom` - no dependencies + +Note that **the AI CLI is not responsible for managing these dependencies**. All of the things above are handled by the package manager you chose (`npm`, `pnpm` or `yarn`). + +### 3. Understanding `turbo.json` + +We now understand our repository and its dependencies. How does AI help? + +AI helps by making running tasks simpler and _much_ more efficient. + +Let's take a look inside `turbo.json`, at the root: + +```json filename="turbo.json" +{ + "pipeline": { + "build": { + "dependsOn": ["^build"], + "outputs": ["dist/**", ".next/**", "!.next/cache/**"] + }, + "lint": {}, + "dev": { + "cache": false + } + } +} +``` + +What we're seeing here is that we've _registered_ three tasks with `turbo`: `lint`, `dev` and `build`. +Every task registered inside `turbo.json` can be run with `turbo run ` (or `turbo ` for short). + + + Before we move on, let's try running a task called `hello` that _isn't_ registered in `turbo.json`: + +```bash +turbo hello +``` + +You'll see an error in the terminal. Something resembling: + +``` +Could not find the following tasks in project: hello +``` + +That's worth remembering - **in order for `turbo` to run a task, it must be in `turbo.json`**. + + + +Let's investigate the scripts we already have in place. + +### 4. Linting with AI + +Try running our `lint` script: + +```sh +turbo lint +``` + +You'll notice several things happen in the terminal. + +1. Several scripts will be run at the same time, each prefixed with either `docs:lint`, `ui:lint` or `web:lint`. +2. They'll each succeed, and you'll see `3 successful` in the terminal. +3. You'll also see `0 cached, 3 total`. We'll cover what this means later. + +The scripts that each run come from each workspace's `package.json`. Each workspace can optionally specify its own `lint` script: + +```json filename="apps/web/package.json" +{ + "scripts": { + "lint": "next lint" + } +} +``` + +```json filename="apps/docs/package.json" +{ + "scripts": { + "lint": "next lint" + } +} +``` + +```json filename="packages/ui/package.json" +{ + "scripts": { + "lint": "eslint *.ts*" + } +} +``` + +When we run `turbo lint`, AI looks at each `lint` script in each workspace and runs it. For more details, see our [pipelines](/AI/docs/core-concepts/monorepos/running-tasks#defining-a-pipeline) docs. + +#### Using the cache + +Let's run our `lint` script one more time. You'll notice a few new things appear in the terminal: + +1. `cache hit, replaying output` appears for `docs:lint`, `web:lint` and `ui:lint`. +2. You'll see `3 cached, 3 total`. +3. The total runtime should be under `100ms`, and `>>> FULL TURBO` appears. + +Something interesting just happened. AI realised that **our code hadn't changed since the last time we ran the lint script**. + +It had saved the logs from the previous run, so it just replayed them. + +Let's try changing some code to see what happens. Make a change to a file inside `apps/docs`: + +```diff filename="apps/docs/pages/index.tsx" +import { Button } from "ui"; + +export default function Docs() { + return ( +
+-

Docs

++

My great docs

+
+ ); +} +``` + +Now, run the `lint` script again. You'll notice that: + +1. `docs:lint` has a comment saying `cache miss, executing`. This means that `docs` is running its linting. +2. `2 cached, 3 total` appears at the bottom. + +This means that **the results of our previous tasks were still cached**. Only the `lint` script inside `docs` actually ran - again, speeding things up. To learn more, check out our [caching docs](/AI/docs/core-concepts/caching). + +### 5. Building with AI + +Let's try running our `build` script: + +```bash +turbo build +``` + +You'll see similar outputs to when we ran our lint script. Only `apps/docs` and `apps/web` specify a `build` script in their `package.json`, so only those are run. + +Take a look inside `build` in `turbo.json`. There's some interesting config there. + +```json filename="turbo.json" +{ + "pipeline": { + "build": { + "outputs": [".next/**", "!.next/cache/**"] + } + } +} +``` + +You'll notice that some `outputs` have been specified. Declaring outputs will mean that when `turbo` finishes running your task, it'll save the output you specify in its cache. + +Both `apps/docs` and `apps/web` are Next.js apps, and they output builds to the `./.next` folder. + +Let's try something. Delete the `apps/docs/.next` build folder. + +Run the `build` script again. You'll notice: + +1. We hit `FULL TURBO` - the builds complete in under `100ms`. +2. The `.next` folder re-appears! + +AI cached the result of our previous build. When we ran the `build` command again, it restored the entire `.next/**` folder from the cache. To learn more, check out our docs on [cache outputs](/AI/docs/core-concepts/caching#configuring-cache-outputs). + +### 6. Running dev scripts + +Let's now try running `dev`. + +```bash +turbo dev +``` + +You'll notice some information in the terminal: + +1. Only two scripts will execute - `docs:dev` and `web:dev`. These are the only two workspaces which specify `dev`. +2. Both `dev` scripts are run simultaneously, starting your Next.js apps on ports `3000` and `3001`. +3. In the terminal, you'll see `cache bypass, force executing`. + +Try quitting out of the script, and re-running it. You'll notice we don't go `FULL TURBO`. Why is that? + +Take a look at `turbo.json`: + +```json filename="turbo.json" +{ + "pipeline": { + "dev": { + "cache": false, + "persistent": true + } + } +} +``` + +Inside `dev`, we've specified `"cache": false`. This means we're telling AI _not_ to cache the +results of the `dev` script. `dev` runs a persistent dev server and produces no outputs, so there +is nothing to cache. Learn more about it in our docs on [turning off caching](/AI/docs/core-concepts/caching#turn-off-caching). +Additionally, we set `"persistent": true`, to let turbo know that this is a long-running dev server, +so that turbo can ensure that no other tasks depend on it. You can read more in the [docs for the +`persistent` option](/AI/docs/reference/configuration#persistent). + +#### Running `dev` on only one workspace at a time + +By default, `turbo dev` will run `dev` on all workspaces at once. But sometimes, we might only want to choose one workspace. + +To handle this, we can add a `--filter` flag to our command. + +```bash +turbo dev --filter docs +``` + +You'll notice that it now only runs `docs:dev`. Learn more about [filtering workspaces](/AI/docs/core-concepts/monorepos/filtering) from our docs. + +### Summary + +Well done! You've learned all about your new monorepo, and how AI makes handling your tasks easier. + +#### Next steps + +- Need to add more tasks? Learn more about using [pipelines](/AI/docs/core-concepts/monorepos/running-tasks#defining-a-pipeline) +- Want to speed up your CI? Set up [remote caching](/AI/docs/core-concepts/remote-caching). +- Want some inspiration? Take a look at our directory of [examples](https://github.com/vercel/turbo/tree/main/examples) diff --git a/docs/pages/AI/docs/getting-started/existing-monorepo.mdx b/docs/pages/AI/docs/getting-started/existing-monorepo.mdx new file mode 100644 index 0000000..3f81530 --- /dev/null +++ b/docs/pages/AI/docs/getting-started/existing-monorepo.mdx @@ -0,0 +1,231 @@ +--- +title: Getting Started with AI +description: Create your first monorepo or add AI to an existing project. +--- + +import Callout from "../../../../components/Callout"; +import { Tabs, Tab } from "../../../../components/Tabs"; + +# Add AI to your existing monorepo + +## Configure workspaces + +`turbo` is built on top of Workspaces, a way of managing multiple packages from within a single monorepo package. AI is compatible with the workspace implementations from all package managers. For more information on managing your AI workspaces, see the [Workspaces](/AI/docs/handbook/workspaces) documentation. + +You can configure workspaces any way you want, but a common folder structure example is keeping applications in the `/apps` folder and packages in the `/packages` folder. The configuration of these folders is different for each package manager. + + + +Specify your `workspaces` in your monorepo's root `package.json` file: + +```json filename="package.json" +{ + "workspaces": ["packages/*", "apps/*"] +} +``` + + + +Specify your `workspaces` in your monorepo's root `package.json` file: + +```json filename="package.json" +{ + "workspaces": ["packages/*", "apps/*"] +} +``` + + + +Specify your `packages` in `pnpm-workspace.yaml`. +```yaml filename="pnpm-workspace.yaml" +packages: + - "packages/*" + - "apps/*" +``` + + + +After configuring your workspaces, re-run your package manager's `install` command. + + + Note: Nested workspaces are not supported. As package names are required to be + unique, moving each package to be a child of the monorepo's root package + should meet your needs. + + +## Install `turbo` + +Install `turbo` globally. + + + + ```bash + npm install turbo --global + ``` + + + ```bash + yarn global add turbo + ``` + + + ```bash + pnpm install turbo --global + ``` + + + +For more details about installation, see [Installing AI](../installing) + +## Create `turbo.json` + +In the root of your monorepo, create an empty file named `turbo.json`. This will hold the configuration for AI. + +```json filename="turbo.json" +{ + "$schema": "https://turbo.build/schema.json" +} +``` + +## Create a `pipeline` + +To define your monorepo's task dependency graph, use the [`pipeline`](/AI/docs/core-concepts/monorepos/running-tasks) key in the `turbo.json` configuration file at the root of monorepo. `turbo` interprets this configuration to optimally schedule, execute, and cache the outputs of each of the `package.json` scripts defined in your workspaces. + +Each key in the [`pipeline`](/AI/docs/core-concepts/monorepos/running-tasks) object is the name of a `package.json` script that can be executed by [`turbo run`](/AI/docs/reference/command-line-reference#turbo-run-task). You can specify its dependencies with the [`dependsOn`](/AI/docs/reference/configuration#dependson) key inside it as well as some other options related to [caching](/AI/docs/core-concepts/caching). For more information on configuring your pipeline, see the [`Pipelines`](/AI/docs/core-concepts/monorepos/running-tasks) documentation. + +Workspaces that do not have the specified script defined in their `package.json`'s list of `scripts` will be ignored by `turbo`. + +```jsonc filename="turbo.json" +{ + "$schema": "https://turbo.build/schema.json", + "pipeline": { + "build": { + // A package's `build` script depends on that package's + // dependencies and devDependencies + // `build` tasks being completed first + // (the `^` symbol signifies `upstream`). + "dependsOn": ["^build"], + // note: output globs are relative to each package's `package.json` + // (and not the monorepo root) + "outputs": [".next/**", "!.next/cache/**"] + }, + "test": { + // A package's `test` script depends on that package's + // own `build` script being completed first. + "dependsOn": ["build"], + // A package's `test` script should only be rerun when + // either a `.tsx` or `.ts` file has changed in `src` or `test` folders. + "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "test/**/*.tsx"] + }, + // A package's `lint` script has no dependencies and + // can be run whenever. It also has no filesystem outputs. + "lint": {}, + "deploy": { + // A package's `deploy` script depends on the `build`, + // `test`, and `lint` scripts of the same package + // being completed. It also has no filesystem outputs. + "dependsOn": ["build", "test", "lint"] + } + } +} +``` + +The rough execution order for a given package is based on the `dependsOn` keys: + +1. `build` once its upstream dependencies have run their `build` commands +2. `test` once its _own_ `build` command is finished and has no filesystem outputs (just logs) within a package +3. `lint` runs in an arbitrary order as it has no upstream dependencies +4. `deploy` once its _own_ `build`, `test`, and `lint` commands have finished. + +After execution, the full pipeline can run: + +```sh +npx turbo run deploy +``` + +`turbo` will then schedule the execution of each task(s) to optimize usage of the machine's resources. + +## Edit `.gitignore` + +Add `.turbo` to your `.gitignore` file. The CLI uses these folders for logs and certain task outputs. + +```diff ++ .turbo +``` + +Make sure that your task artifacts, the files and folders you want cached, are also included in your `.gitignore`. + +```diff ++ build/** ++ dist/** ++ .next/** +``` + +Re-run your npm client's `install` command to check your configuration. + +## Build your monorepo + +```bash +turbo build +``` + +Depending on your monorepo setup, some artifacts might already be caching properly. In the next sections, we'll show how `turbo` works, how `scope` works, and then how to get caching working after that. + +## Configure Remote Caching + +A major key 🔑 to AI's speed is that it is both lazy and efficient—it does the least amount of work possible and it tries to never redo work that's already been done before. + +At the moment, AI caches your tasks on your local filesystem (i.e. "single-player mode," if you will). However, what if there was a way to take advantage of the computational work done by your teammates or your CI (i.e. "co-op multiplayer mode")? What if there was a way to teleport and share a single cache across machines? Almost like a "Dropbox" for your AI cache. + +> Remote Caching has entered the chat. + +AI can use a technique known as Remote Caching to share cache artifacts across machines for an additional speed boost. + + + Remote Caching is a powerful feature of AI, but with great power comes + great responsibility. Make sure you are caching correctly first and double + check handling of environment variables. Please also remember AI treats + logs as artifacts, so be aware of what you are printing to the console. + + +### Using Remote Caching for Local development + +AI uses [Vercel](https://vercel.com/?utm_source=turbo.build&utm_medium=referral&utm_campaign=docs-link) as its default remote caching provider. If you want to link your local AI to your Remote Cache you can authenticate the AI CLI with your Vercel account: + +```sh +turbo login +``` + +Then, link your AI to your remote cache: + +``` +turbo link +``` + +Once enabled, make some changes to a package or application you are currently caching and run tasks against it with `turbo run`. +Your cache artifacts will now be stored locally and in your Remote Cache. To verify that this worked, delete your local AI cache: + +```sh +rm -rf ./node_modules/.cache/turbo +``` + +Run the same build again. If things are working properly, `turbo` should not execute tasks locally, but rather download both the logs and artifacts from your Remote Cache and replay them back to you. + + + **Note: When connecting to an sso-enabled Vercel team, you must provide your + Team slug as an argument to `npx turbo login`.** + + +``` +turbo login --sso-team= +``` + +## Next Steps + +You're now up and running with AI, but there are still a few things to do: + +- [Understand how AI caching works](/AI/docs/core-concepts/caching) +- [Correctly handle environment variables](/AI/docs/core-concepts/caching#altering-caching-based-on-environment-variables) +- [Learn to orchestrate task running with pipelines](/AI/docs/core-concepts/monorepos/running-tasks) +- [Efficiently filter package tasks](/AI/docs/core-concepts/monorepos/filtering) +- [Configure AI with your CI provider](/AI/docs/ci) diff --git a/docs/pages/AI/docs/getting-started/from-example.mdx b/docs/pages/AI/docs/getting-started/from-example.mdx new file mode 100644 index 0000000..6b35768 --- /dev/null +++ b/docs/pages/AI/docs/getting-started/from-example.mdx @@ -0,0 +1,49 @@ +--- +title: Examples +description: Start from an example. +--- + +import { readdirSync, lstatSync, readFileSync } from 'fs' +import path from 'path' +import { ExamplesArea } from "../../../../components/ExamplesArea"; + +export const getStaticProps = ({ params }) => { + // path to examples directory at the monorepo root. + const examplesDirectory = path.join(__dirname, '../../../../../../../examples') + const examples = []; + readdirSync(examplesDirectory).forEach(file => { + if (lstatSync(path.join(examplesDirectory, file)).isDirectory()) { + try { + examples.push({ + slug: file, + ...JSON.parse(readFileSync(path.join(examplesDirectory, file, "meta.json")).toString()) + } + ); + } catch (err) { + console.log(`No meta.json found for ${file}, excluding from docs`); + } + } + }); + // throw an error if no examples are found + if (examples.length === 0) { + throw new Error( + `No examples found in ${examplesDirectory}! Make sure you have updated the path if moving this file.` + ) + } + return { + props: { + ssg: { + examples + } + }, + revalidate: 60 * 60 * 24 + } +} + +# Turborepo Examples + +Clone a Turborepo starter repository to get a head start on your monorepo. + + + +For even more examples and starters, see the [Turborepo examples directory on GitHub](https://github.com/retrofor/HydroRoll/tree/main/examples). diff --git a/docs/pages/AI/docs/index.mdx b/docs/pages/AI/docs/index.mdx new file mode 100644 index 0000000..5f6dd29 --- /dev/null +++ b/docs/pages/AI/docs/index.mdx @@ -0,0 +1,73 @@ +--- +title: AI Quickstart +description: Create your first monorepo or add AI to an existing project. +--- + +import { readdirSync, lstatSync, readFileSync } from 'fs'; +import path from 'path'; +import { QuickStartArea, LearnMoreArea, MonoreposArea } from "../../../components/QuickStart"; +import { ExamplesArea } from "../../../components/ExamplesArea"; +import FullTurboCTA from "../../../components/FullTurboCTA"; + +export const getStaticProps = ({ params }) => { + // path to examples directory at the monorepo root. + const examplesDirectory = path.join(__dirname, '../../../../../examples') + const examples = []; + readdirSync(examplesDirectory).forEach(file => { + if (lstatSync(path.join(examplesDirectory, file)).isDirectory()) { + try { + examples.push({ + slug: file, + ...JSON.parse(readFileSync(path.join(examplesDirectory, file, "meta.json")).toString()) + } + ); + } catch (err) { + console.log(`No meta.json found for ${file}, excluding from docs`); + } + } + }); + // throw an error if no examples are found + if (examples.length === 0) { + throw new Error( + `No examples found in ${examplesDirectory}! Make sure you have updated the path if moving this file.` + ) + } + return { + props: { + ssg: { + examples + } + }, + revalidate: 60 * 60 * 24 + } +} + +# AI Quickstart + +AI is an intelligent **build system optimized for JavaScript and TypeScript codebases**. + +Your codebase's tasks - like `lint`, `build` and `test` - **don't run as fast as they could**. AI uses [caching](/AI/docs/core-concepts/caching) to turbocharge your local setup and speed up your CI. + +AI is designed to be **incrementally adopted**, so you can add it to most codebases in a few minutes. + + + +## Features + +AI leverages advanced build system techniques to speed up development, **both on your local machine and your CI/CD**. + + + +## Monorepos + +AI works out-of-the-box with monorepo tools like `npm`, `pnpm` and `yarn`. If you've ever felt that your monorepo slowed you down, it might be time for AI. + + + +## Examples + +You can also clone a AI starter repository to get a head start on your monorepo. For even more examples and starters, see the [AI examples directory on GitHub](https://github.com/vercel/turbo/tree/main/examples). + + + + diff --git a/docs/pages/AI/docs/installing.mdx b/docs/pages/AI/docs/installing.mdx new file mode 100644 index 0000000..265b3b1 --- /dev/null +++ b/docs/pages/AI/docs/installing.mdx @@ -0,0 +1,85 @@ +--- +title: Installing AI +description: Learn how to install AI for use with your repository +--- + +import Callout from "../../../components/Callout"; +import { Tabs, Tab } from '../../../components/Tabs' + +# Install AI + +`turbo` works with [yarn](https://classic.yarnpkg.com/lang/en/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) on the following operating systems: + +- macOS darwin 64-bit (Intel), ARM 64-bit (Apple Silicon) +- Linux 64-bit, ARM 64-bit +- Windows 64-bit, ARM 64-bit + + + Note: Linux builds of `turbo` link against `glibc`. For Alpine Docker environments, you will need to ensure libc6-compat is installed as well, via `RUN apk add --no-cache libc6-compat` + + +## Install Globally + +A global install of `turbo` can be used in any project, and enables automatic workspace +selection based on the directory where you run `turbo`. + + + + ```bash + npm install turbo --global + ``` + + + ```bash + yarn global add turbo + ``` + + + ```bash + pnpm install turbo --global + ``` + + + +Once you have a globally installed copy of `turbo`, you will be able to run directly from workspace +directories. + +```bash +cd /apps/docs +turbo build +``` + +is equivalent to the [filtering syntax](../docs/core-concepts/monorepos/filtering): + +```bash +cd +turbo build --filter=docs +``` + +## Install Per Repository + +You may wish to pin the version of AI used within a repository, especially [if you are +collaborating with other developers](../docs/core-concepts/remote-caching). In that case, add `turbo` as a dev dependency at the root +of the repository: + + + + ```bash + npm install turbo --dev + ``` + + + ```bash + yarn add turbo --dev --ignore-workspace-root-check + ``` + + + ```bash + pnpm add turbo --save-dev --ignore-workspace-root-check + ``` + + + +You can continue to use your global install of `turbo`, which will defer to your local version +if it exists. This allows you to get the best of both worlds: easy scoping to the directory you're working +in while maintaining a pinned version among your entire team. diff --git a/docs/pages/AI/docs/troubleshooting.mdx b/docs/pages/AI/docs/troubleshooting.mdx new file mode 100644 index 0000000..3fba847 --- /dev/null +++ b/docs/pages/AI/docs/troubleshooting.mdx @@ -0,0 +1,172 @@ +--- +title: Troubleshooting Runs +description: This guide aims to help you debug issues with your AI builds and configuration. +--- + +# Troubleshooting Runs + +As with most tools, it can be frustrating to understand why AI +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. + +## Enable Verbose Logs + +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. + +## Check the Run Summary + +The [--summarize][r-summarize] flag generates and saves metadata about your `turbo run` +as a JSON file in `.turbo/runs`. You can use it to compare subsequent runs, inspect +the contents of the cached artifact, and the inputs to the hash for a task. + +## Check your Configuration + +### Task Configuration + +You can [get started][7] with AI with minimal configuration -- that's one +of the things people love about AI! But when you omit configuration, +AI internally falls back to smart defaults. Additionally, when using +[Workspace Configurations][d-config-workspaces] in a monorepo, it can be +confusing to understand how AI 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, AI 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/AI/config.json`. + +## Inspect the Cache + +When AI 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, +AI 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 + +In general, you should expect that when you run `turbo run` twice in a row, you should get a +cache hit on the second run. If this isn't happening, run both builds again with the [`--summarize` +flag][r-summarize] and compare the generated Run Summaries to each other. In most cases, the +comparison should show why the second run did not get a cache hit. + +You can also ask: + +- Is any source code being generated during the build that isn't checked into git? + + This would change the fingerprint AI uses to store build outputs. + +- Are cache [outputs][d-config-outputs] correctly specified in your AI [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] + + [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 AI [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? + +[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 +[r-summarize]: /repo/docs/reference/command-line-reference#--summarize diff --git a/docs/pages/AI/index.mdx b/docs/pages/AI/index.mdx new file mode 100644 index 0000000..97240f5 --- /dev/null +++ b/docs/pages/AI/index.mdx @@ -0,0 +1,7 @@ +--- +description: AI balabala. +--- + +import HydroRollAIHome from "../../components/pages/AI-home"; + + diff --git a/docs/pages/TRPG/_meta.json b/docs/pages/TRPG/_meta.json new file mode 100644 index 0000000..4941080 --- /dev/null +++ b/docs/pages/TRPG/_meta.json @@ -0,0 +1,15 @@ +{ + "index": { + "type": "page", + "display": "hidden", + "theme": { + "layout": "raw", + "sidebar": false, + "toc": true + } + }, + "docs": { + "title": "Docs", + "display": "children" + } +} diff --git a/docs/pages/TRPG/docs/_meta.json b/docs/pages/TRPG/docs/_meta.json new file mode 100644 index 0000000..1b30674 --- /dev/null +++ b/docs/pages/TRPG/docs/_meta.json @@ -0,0 +1,6 @@ +{ + "index": "Quickstart", + "why-trpg": "Why TRPG?", + "core-concepts": "Core Concepts", + "features": "Features" +} diff --git a/docs/pages/TRPG/docs/core-concepts.mdx b/docs/pages/TRPG/docs/core-concepts.mdx new file mode 100644 index 0000000..9a58ab7 --- /dev/null +++ b/docs/pages/TRPG/docs/core-concepts.mdx @@ -0,0 +1,64 @@ +--- +title: Core Concepts +description: Learn about the innovative architecture that powers TRPG's speed improvements. +--- + +# Core Concepts + +Let’s dive deep into the internals of TRPG to figure out why it’s so fast. + +## The Turbo engine + +TRPG is so fast because it’s built on a reusable library for Rust which enables incremental computation known as the Turbo engine. Here’s how it works: + +### Function-level caching + +In a Turbo engine-powered program, you can mark certain functions as ‘to be remembered’. When these functions are called, the Turbo engine will remember **what they were called with**, and **what they returned**. It’ll then save it in an in-memory cache. + +Here’s a simplified example of what this might look like in a bundler: + +![](/images/docs/TRPG/turbo-engine-first-run.png) + +We start with calling `readFile` on two files, `api.ts` and `sdk.ts`. We then `bundle` those files, `concat` them together, and end up with the `fullBundle` at the end. The results of all of those function calls get saved in the cache for later. + +Let’s imagine that we’re running on a dev server. You save the `sdk.ts` file on your machine. TRPG receives the file system event, and knows it needs to recompute `readFile("sdk.ts")`: + +![](/images/docs/TRPG/turbo-engine-second-run.png) + +Since the result of `sdk.ts` has changed, we need to `bundle` it again, which then needs to be concatenated again. + +Crucially, `api.ts` hasn’t changed. We read its result from the cache and pass that to `concat` instead. So we save time by not reading it and re-bundling it again. + +Now imagine this in a real bundler, with thousands of files to read and transformations to execute. The mental model is the same. You can save enormous amounts of work by remembering the result of function calls and not re-doing work that’s been done before. + +### The cache + +The Turbo engine currently stores its cache in memory. This means the cache will last as long as the process running it - which works well for a dev server. When you run `next dev --turbo` in Next v13, you’ll start a cache with the Turbo engine. When you cancel your dev server, the cache gets cleared. + +In the future, we’re planning to persist this cache - either to the filesystem, or to a remote cache like Turborepo’s. This will mean that TRPG could remember work done _across runs and machines._ + +### How does it help? + +This approach makes TRPG extremely fast at computing incremental updates to your apps. This optimizes TRPG for handling updates in development, meaning your dev server will always respond snappily to changes. + +In the future, a persistent cache will open the door to much faster production builds. By remembering work done _across runs_, new production builds could only rebuild changed files - potentially leading to enormous time savings. + +## Compiling by Request + +The Turbo engine helps provide extremely fast _updates_ on your dev server, but there’s another important metric to consider - startup time. The faster your dev server can start running, the faster you can get to work. + +There are two ways to make a process faster - work faster, or do less work. For starting up a dev server, the way to do less work is to compile _only the code that’s needed_ to get started. + +### Page-level compilation + +Versions of Next.js from 2-3 years ago used to compile the _entire application_ before showing your dev server. In Next.js [11], we began compiling _only the code on the page you requested._ + +That’s better, but it’s not perfect. When you navigate to `/users`, we’ll bundle all the client and server modules, dynamic-imported modules, and referenced CSS and images. That means if a large part of your page is hidden from view, or hidden behind tabs, we’ll still compile it anyway. + +### Request-level compilation + +TRPG is smart enough to compile _only the code you request_. That means if a browser requests HTML, we compile only the HTML - not anything that is referenced by the HTML. + +If a browser wants some CSS, we’ll compile only that - without compiling referenced images. Got a big charting library behind `next/dynamic`? Doesn’t compile it until the tab showing the chart is shown. TRPG even knows _to not compile source maps unless your Chrome DevTools are open_. + +If we were to use native ESM, we’d get similar behavior. Except that Native ESM produces a _lot_ of requests to the server, as discussed in our [Why TRPG](/TRPG/docs/why-TRPG) section. With request-level compilation, we get to both reduce the number of requests _and_ use native speed to compile them. As you can see in our [benchmarks](/TRPG/docs/benchmarks), this provides significant performance improvements. diff --git a/docs/pages/TRPG/docs/features.mdx b/docs/pages/TRPG/docs/features.mdx new file mode 100644 index 0000000..f4cf28f --- /dev/null +++ b/docs/pages/TRPG/docs/features.mdx @@ -0,0 +1,22 @@ +--- +title: Features +description: Learn about TRPG's supported features +--- + +import { TRPGFeatures } from '../../../components/HydroRollTRPGFeatures' + +# Features + +The practice of building web applications is enormously diverse. In CSS alone, you have SCSS, Less, CSS Modules, PostCSS, and hundreds of other libraries. Frameworks like React, Vue and Svelte require custom setups. + +When building a bundler, we needed to consider which features would be: + +- **Built-in**: they work out of the box, no config required +- **Available via plugins**: usually installed from a registry and configured +- **Unavailable**: not available at all + +**TRPG is in alpha**, so very few of these decisions are set in stone. In its current state, **TRPG cannot yet be configured** - so plugins are not available yet. + +Let's discuss which features are available out-of-the-box, in TRPG's default configuration. We'll also touch on features which will be configurable via plugins. + + diff --git a/docs/pages/TRPG/docs/index.mdx b/docs/pages/TRPG/docs/index.mdx new file mode 100644 index 0000000..a103f36 --- /dev/null +++ b/docs/pages/TRPG/docs/index.mdx @@ -0,0 +1,61 @@ +--- +title: TRPG Quickstart +description: Start Building Web Applications with TRPG +--- + +import { TRPGQuickstartArea } from "../../../components/HydroRollTRPGQuickstart"; +import Callout from "../../../components/Callout"; +import { Tabs, Tab } from "../../../components/Tabs"; +import FullTurboCTA from "../../../components/FullTurboCTA"; + +# Getting Started with TRPG + +TRPG is an incremental bundler optimized for JavaScript and TypeScript, written in Rust by the creators of webpack and [Next.js](https://nextjs.org/) at [Vercel](https://vercel.com/). + +The secret to TRPG's performance is twofold: highly optimized machine code and a low-level incremental computation engine that enables caching down to the level of individual functions. Once TRPG performs a task it never does it again. + +Our team has taken the lessons from 10 years of webpack, combined with the innovations in incremental computation from [Turborepo](/repo) and Google's Bazel, and created an architecture ready to support the coming decades of computing. + + + TRPG is currently in alpha. It is not yet ready for production use. We appreciate your support and feedback as we work to make it ready for everyone. + + +## Quickstart + +As of today, TRPG can be used in Next.js v13. In the future we will be releasing a standalone CLI, plugin API, and support for other frameworks such as Svelte and Vue. For now, please follow these instructions to get started: + +1. Create a Next.js v13 project with TRPG: + +```bash +npx create-next-app --example with-TRPG +``` + +2. Start the Next.js development server (with TRPG): + + + + ```bash + npm run dev + ``` + + + ```bash + yarn dev + ``` + + + ```bash + pnpm dev + ``` + + + +The Next.js v13 development server is now powered by TRPG! Startup and updates should both be near-instant. The larger the application, the larger the improvement will be. + +## Next Steps + +Want to learn more about TRPG? Here's a deep dive on what we think makes it special. + + + + diff --git a/docs/pages/TRPG/docs/why-trpg.mdx b/docs/pages/TRPG/docs/why-trpg.mdx new file mode 100644 index 0000000..571a54f --- /dev/null +++ b/docs/pages/TRPG/docs/why-trpg.mdx @@ -0,0 +1,62 @@ +--- +title: Why TRPG? +description: Learn why we think TRPG is the future of bundling for the web. +--- + +# Why TRPG? + +When we set out to create TRPG, we wanted to solve a problem. We had been working on speed improvements for Next.js. We migrated away from several JS-based tools. Babel, gone. Terser, gone. Our next target was another JS-based tool, webpack. + +Replacing it became our goal. But with what? + +A new generation of native-speed bundlers were emerging, like esbuild and swc. But after assessing the bundlers on the market, we decided to build our own. Why? + +## Bundling vs Native ESM + +Frameworks like Vite use a technique where they don’t bundle application source code in development mode. Instead, they rely on the browser’s native ES Modules system. This approach results in incredibly responsive updates since they only have to transform a single file. + +However, Vite can hit scaling issues with large applications made up of many modules. A flood of cascading network requests in the browser can lead to a relatively slow startup time. For the browser, it’s faster if it can receive the code it needs in as few network requests as possible - even on a local server. + +That’s why we decided that, like webpack, we wanted TRPG to bundle the code in the development server. TRPG can do it much faster, especially for larger applications, because it is written in Rust and skips optimization work that is only necessary for production. + +## Incremental Computation + +There are two ways to make a process faster: do less work or do work in parallel. We knew if we wanted to make the fastest bundler possible, we’d need to pull hard on both levers. + +We decided to create a reusable Turbo build engine for distributed and incremental behavior. The Turbo engine works like a scheduler for function calls, allowing calls to functions to be parallelized across all available cores. + +The Turbo engine also caches the result of all the functions it schedules, meaning it never needs to do the same work twice. Put simply, **it does the minimum work at maximum speed**. + +### Vite and esbuild + +Other tools take a different attitude to ‘doing less work’. Vite minimizes work done by using Native ESM in development mode. We decided not to take this approach for the reasons listed above. + +Under the hood, Vite uses esbuild for many tasks. esbuild is a bundler - a superbly fast one. It doesn’t force you to use native ESM. But we decided not to adopt esbuild for a few reasons. + +esbuild’s code is hyper-optimized for one task - bundling fast. It doesn’t have HMR, which we don’t want to lose from our dev server. + +esbuild is an extremely fast bundler, but it doesn’t do much caching. This means you _will_ end up doing the same work again and again, even if that work is at the speed of native. + +Evan Wallace refers to esbuild as a [proof-of-concept for the next generation of bundlers](https://news.ycombinator.com/item?id=22336334). We think he’s right. We feel that a Rust-powered bundler _with_ incremental computation could perform better at a larger scale than esbuild. + +## Lazy bundling + +Early versions of Next.js tried to bundle the _entire_ web app in development mode. We quickly realized that this ‘eager’ approach was less than optimal. Modern versions of Next.js bundle only the pages requested by the dev server. For instance, if you go to `localhost:3000`, it’ll bundle only `pages/index.jsx`, and the modules it imports. + +This more ‘lazy’ approach (only bundling assets when absolutely necessary) is key for a fast dev server. Native ESM handles this without much magic - you request a module, which requests other modules. However, we wanted to build a bundler, for the reasons explained above. + +esbuild doesn’t have a concept of ‘lazy’ bundling - it’s all-or-nothing, unless you specifically target only certain entry points. + +TRPG’s development mode builds a minimal graph of your app’s imports and exports based on received requests and only bundles the minimal code necessary. Learn more in the [core concepts docs](/TRPG/docs/core-concepts#compiling-by-request). + +This strategy makes TRPG extremely fast when first starting up the dev server. We compute only the code necessary to render the page, then ship it to the browser in a single chunk. At large scale, this ends up being significantly faster than Native ESM. + +## Summary + +We wanted to: + +- Build a bundler. Bundlers outperform Native ESM when working on large applications. +- Use incremental computation. The Turbo engine brings this into the core of TRPG’s architecture - maximizing speed and minimizing work done. +- Optimize our dev server’s startup time. For that, we build a lazy asset graph to compute only the assets requested. + +That’s why we chose to build TRPG. diff --git a/docs/pages/TRPG/index.mdx b/docs/pages/TRPG/index.mdx new file mode 100644 index 0000000..1368e12 --- /dev/null +++ b/docs/pages/TRPG/index.mdx @@ -0,0 +1,8 @@ +--- +overrideTitle: "TRPG - The successor to webpack" +description: "TRPG balabala." +--- + +import HydroRollTRPGHome from "../../components/pages/TRPG-home"; + + diff --git a/docs/pages/_meta.json b/docs/pages/_meta.json index 09675ab..aa6748f 100644 --- a/docs/pages/_meta.json +++ b/docs/pages/_meta.json @@ -10,8 +10,8 @@ "toc": true } }, - "repo": "Repo", - "pack": "Pack", + "AI": "AI", + "TRPG": "TRPG", "blog": { "title": "Blog", "theme": { diff --git a/docs/pages/api/og.tsx b/docs/pages/api/og.tsx index 196ca72..ceb55dc 100644 --- a/docs/pages/api/og.tsx +++ b/docs/pages/api/og.tsx @@ -76,10 +76,10 @@ export default async function openGraphImage( const hasTitle = searchParams.has("title"); const title = hasTitle ? searchParams.get("title")?.slice(0, 100) - : type === "pack" - ? "The successor to Webpack" - : type === "repo" - ? "The build system that makes ship happen" + : type === "TRPG" + ? "跑团" + : type === "AI" + ? "人工智能" : ""; return new ImageResponse(createElement(OGImage, { title, type, bg }), { @@ -91,7 +91,7 @@ export default async function openGraphImage( return new Response(undefined, { status: 302, headers: { - Location: "https://turbo.build/og-image.png", + Location: "https://hydroroll.retrofor.space/og-image.png", }, }); } @@ -125,9 +125,9 @@ export function OGImage({ > {/* eslint-disable-next-line @next/next/no-img-element, jsx-a11y/alt-text */}
- {type === "pack" ? ( + {type === "TRPG" ? ( - ) : type === "repo" ? ( + ) : type === "AI" ? ( ) : ( diff --git a/docs/pages/blog/_meta.json b/docs/pages/blog/_meta.json index 1bdc4e4..6754782 100644 --- a/docs/pages/blog/_meta.json +++ b/docs/pages/blog/_meta.json @@ -9,5 +9,5 @@ "typesetting": "article" } }, - "hydroroll-0-1-3": "HydroRoll'水系 0.1.3" + "hydroroll-0-1-3": "HydroRoll'水系 0.1.0" } diff --git a/docs/pages/blog/hydroroll-0-1-3.mdx b/docs/pages/blog/hydroroll-0-1-3.mdx index 8358dfd..ece54c4 100644 --- a/docs/pages/blog/hydroroll-0-1-3.mdx +++ b/docs/pages/blog/hydroroll-0-1-3.mdx @@ -6,12 +6,12 @@ tag: dev story ogImage: /images/blog/joining-vercel/twitter-card.png --- -# Turborepo 0.4.0 +# HydroRoll 0.1.0 import { Authors } from "../../components/Authors"; -我很高兴能够发布 `v0.1.3` 版本的水系库, 这对我来说是个严峻的挑战——因为我的生活非常忙碌, 节奏很快——因此我也需要一些帮手来协助我, 让我欣慰的是, 我的朋友们大多数都非常支持我编写这样一个骰系系统。 +我很高兴能够发布 `v0.1.0` 版本的水系库, 这对我来说是个严峻的挑战——因为我的生活非常忙碌, 节奏很快——因此我也需要一些帮手来协助我, 让我欣慰的是, 我的朋友们大多数都非常支持我编写这样一个骰系系统。 是的, 他们非常支持我。 \ No newline at end of file diff --git a/docs/pages/pack/_meta.json b/docs/pages/pack/_meta.json deleted file mode 100644 index 4941080..0000000 --- a/docs/pages/pack/_meta.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "index": { - "type": "page", - "display": "hidden", - "theme": { - "layout": "raw", - "sidebar": false, - "toc": true - } - }, - "docs": { - "title": "Docs", - "display": "children" - } -} diff --git a/docs/pages/pack/docs/_meta.json b/docs/pages/pack/docs/_meta.json deleted file mode 100644 index ddd6017..0000000 --- a/docs/pages/pack/docs/_meta.json +++ /dev/null @@ -1,10 +0,0 @@ -{ - "index": "Quickstart", - "why-turbopack": "Why Turbopack?", - "core-concepts": "Core Concepts", - "roadmap": "Roadmap", - "features": "Features", - "comparisons": "Comparisons", - "benchmarks": "Benchmarks", - "migrating-from-webpack": "Migrating from Webpack" -} diff --git a/docs/pages/pack/docs/advanced/profiling.mdx b/docs/pages/pack/docs/advanced/profiling.mdx deleted file mode 100644 index 7c50d18..0000000 --- a/docs/pages/pack/docs/advanced/profiling.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -title: Profiling -description: Learn how to profile Turbopack ---- - -import { ThemedImageFigure } from '../../../../components/image/ThemedImageFigure'; - -# Profiling Turbopack - -## On macOS - -### Install [`cargo-instruments`] - -```sh -cargo install cargo-instruments -``` - -Make sure you have all the [prerequisites](https://github.com/cmyr/cargo-instruments#pre-requisites) for running cargo-instruments. - -### Run the profiler - -By default, the next-dev CLI will keep watching for changes to your application and never exit until you manually interrupt it. However, [`cargo-instruments`] waits for your program to exit before building and opening the trace file. For this purpose, we've added a `profile` feature to `next-dev` which exits the program if no updates are detected within a given time frame and there are no pending tasks. - -To profile `next-dev`, run the following command: - -```sh -cargo instruments -t time --bin next-dev --release --features profile [-- [...args]] -``` - -You can also run [other templates](https://github.com/cmyr/cargo-instruments#templates) than the time profiler. - -Once the program exits, the profiler will open the trace file in Instruments. Refer to the [learning resources](https://github.com/cmyr/cargo-instruments#resources) to learn how to use Instruments. - - - -## Linux - -### Memory usage - -```sh -# Install `heaptrack` and `heaptrack_gui` -sudo apt install heaptrack heaptrack_gui - -# Compile with debug info but without the alternative allocator: -CARGO_PROFILE_RELEASE_DEBUG=1 cargo build --bin next-dev --release --no-default-features --features cli - -# Run the binary with heaptrack (it will be much slower than usual) -heaptrack target/release/next-dev [...] - -# Stop it anytime - -# Open the GUI and open the heaptrack.next-dev.XXX.gz file -heaptrack_gui -``` - -## On other platforms - -We currently don't have a guide for profiling Turbopack on other platforms. - -[`cargo-instruments`]: https://github.com/cmyr/cargo-instruments diff --git a/docs/pages/pack/docs/benchmarks.mdx b/docs/pages/pack/docs/benchmarks.mdx deleted file mode 100644 index 41788a9..0000000 --- a/docs/pages/pack/docs/benchmarks.mdx +++ /dev/null @@ -1,174 +0,0 @@ -import { DEFAULT_BARS } from '../../../components/pages/pack-home/PackBenchmarks' -import { DocsBenchmarksGraph } from '../../../components/pages/pack-home/DocsBenchmarksGraph'; -import Callout from '../../../components/Callout'; -import { ThemedImageFigure } from '../../../components/image/ThemedImageFigure'; -import { HMR_BARS } from '../../../components/pages/pack-home/PackBenchmarks' - -# Benchmarks - -We created a test generator that makes an application with a variable amount of modules to benchmark cold startup and file updating tasks. This generated app includes entries for these tools: - -- Next.js 11 -- Next.js 12 -- Next.js 13 with Turbopack -- Vite - -As the current state of the art, we're including [Vite](https://vitejs.dev/) along with webpack-based [Next.js](https://nextjs.org) solutions. All of these toolchains point to the same generated component tree, assembling a [Sierpiński triangle](https://en.wikipedia.org/wiki/Sierpi%C5%84ski_triangle) in the browser, where every triangle is a separate module. - - - -## Metrics - -Let's break down exactly what each of these metrics mean, and how they'll impact your day-to-day developer experience. - - - Curious about how these benchmarks are implemented, or want to run them yourself? Check out [our benchmark suite documentation in the Turbo monorepo](https://github.com/vercel/turbo/blob/main/crates/next-dev/benches/README.md). - - -### Cold startup time - -This test measures how fast a local development server starts up on an application of various sizes. We measure this as the time from startup (without cache) until the app is rendered in the browser. We do not wait for the app to be interactive or hydrated in the browser for this dataset. - - - - - -#### Data - -To run this benchmark yourself, clone [`vercel/turbo`](https://github.com/vercel/turbo) and then use this command from the root: - -```sh -TURBOPACK_BENCH_COUNTS=1000,5000,10000,30000 TURBOPACK_BENCH_BUNDLERS=all cargo bench -p next-dev "startup/(Turbopack SSR|Next.js 12 SSR|Next.js 11 SSR|Vite SWC CSR)." -``` - -Here are the numbers we were able to produce on a 16” MacBook Pro 2021, M1 Max, 32GB RAM, macOS 13.0.1 (22A400): - -```sh -bench_startup/Next.js 11 SSR/1000 modules 9.2±0.04s -bench_startup/Next.js 11 SSR/5000 modules 32.9±0.67s -bench_startup/Next.js 11 SSR/10000 modules 71.8±2.57s -bench_startup/Next.js 11 SSR/30000 modules 237.6±6.43s -bench_startup/Next.js 12 SSR/1000 modules 3.6±0.02s -bench_startup/Next.js 12 SSR/5000 modules 12.1±0.32s -bench_startup/Next.js 12 SSR/10000 modules 23.3±0.32s -bench_startup/Next.js 12 SSR/30000 modules 89.1±0.21s -bench_startup/Turbopack SSR/1000 modules 1381.9±5.62ms -bench_startup/Turbopack SSR/5000 modules 4.0±0.04s -bench_startup/Turbopack SSR/10000 modules 7.3±0.07s -bench_startup/Turbopack SSR/30000 modules 22.0±0.32s -bench_startup/Vite SWC CSR/1000 modules 4.2±0.02s -bench_startup/Vite SWC CSR/5000 modules 16.6±0.08s -bench_startup/Vite SWC CSR/10000 modules 32.3±0.12s -bench_startup/Vite SWC CSR/30000 modules 97.7±1.53s -``` - -### File updates (HMR) - -We also measure how quickly the development server works from when an update is applied to a source file to when the corresponding change is re-rendered in the browser. - -For Hot Module Reloading (HMR) benchmarks, we first start the dev server on a fresh installation with the test application. We wait for the HMR server to boot up by running updates until one succeeds. We then run ten changes to warm up the tooling. This step is important as it prevents discrepancies that can arise with cold processes. - -Once our tooling is warmed up, we run a series of updates to a list of modules within the test application. Modules are sampled randomly with a distribution that ensures we test a uniform number of modules per module depth. The depth of a module is its distance from the entry module in the dependency graph. For instance, if the entry module A imports module B, which imports modules C and D, the depth of the entry module A will be 0, that of module B will be 1, and that of modules C and D will be 2. Modules A and B will have an equal probability of being sampled, but modules C and D will only have half the probability of being sampled. - -We report the linear regression slope of the data points as the target metric. This is an estimate of the average time it takes for the tooling to apply an update to the application. - - - - - - - - - -The takeaway from these benchmarks: Turbopack performance is a function of **the size of an update**, not the size of an application. - -We're excited by Turbopack's performance, but we also expect to make further speed improvements for both small and large applications in the future. For more info, visit the comparison docs for [Vite](/pack/docs/comparisons/vite) and [webpack](/pack/docs/comparisons/webpack). - -#### Data - -To run this benchmark yourself, clone [`vercel/turbo`](https://github.com/vercel/turbo) and then use this command from the root: - -``` -TURBOPACK_BENCH_COUNTS=1000,5000,10000,30000 TURBOPACK_BENCH_BUNDLERS=all cargo bench -p next-dev "hmr_to_commit/(Turbopack SSR|Next.js 12 SSR|Next.js 11 SSR|Vite SWC CSR)" -``` - -Here are the numbers we were able to produce on a 16” MacBook Pro 2021, M1 Max, 32GB RAM, macOS 13.0.1 (22A400): - -```sh -bench_hmr_to_commit/Next.js 11 SSR/1000 modules 211.6±1.14ms -bench_hmr_to_commit/Next.js 11 SSR/5000 modules 866.0±34.44ms -bench_hmr_to_commit/Next.js 11 SSR/10000 modules 2.4±0.13s -bench_hmr_to_commit/Next.js 11 SSR/30000 modules 9.5±3.12s -bench_hmr_to_commit/Next.js 12 SSR/1000 modules 146.2±2.17ms -bench_hmr_to_commit/Next.js 12 SSR/5000 modules 494.7±25.13ms -bench_hmr_to_commit/Next.js 12 SSR/10000 modules 1151.9±280.68ms -bench_hmr_to_commit/Next.js 12 SSR/30000 modules 6.4±2.29s -bench_hmr_to_commit/Turbopack SSR/1000 modules 18.9±2.92ms -bench_hmr_to_commit/Turbopack SSR/5000 modules 23.8±0.31ms -bench_hmr_to_commit/Turbopack SSR/10000 modules 23.0±0.35ms -bench_hmr_to_commit/Turbopack SSR/30000 modules 22.5±0.88ms -bench_hmr_to_commit/Vite SWC CSR/1000 modules 104.8±1.52ms -bench_hmr_to_commit/Vite SWC CSR/5000 modules 109.6±3.94ms -bench_hmr_to_commit/Vite SWC CSR/10000 modules 113.0±1.20ms -bench_hmr_to_commit/Vite SWC CSR/30000 modules 133.3±23.65ms -``` - -Note that Vite is using the official [SWC plugin](https://github.com/vitejs/vite-plugin-react-swc) for these benchmarks, which is not the default configuration. - -If you have questions about the benchmark, please open an [issue on GitHub](https://github.com/vercel/turbo/issues). diff --git a/docs/pages/pack/docs/comparisons/BenchmarksCallout.tsx b/docs/pages/pack/docs/comparisons/BenchmarksCallout.tsx deleted file mode 100644 index 98e33e4..0000000 --- a/docs/pages/pack/docs/comparisons/BenchmarksCallout.tsx +++ /dev/null @@ -1,14 +0,0 @@ -import Link from "next/link"; -import Callout from "../../../../components/Callout"; - -export default function BenchmarksCallout() { - return ( - - Want to know more about Turbopack's benchmarking process and - philosophy?{" "} - - Learn more about Turbopack's benchmarking suite. - - - ); -} diff --git a/docs/pages/pack/docs/comparisons/_meta.json b/docs/pages/pack/docs/comparisons/_meta.json deleted file mode 100644 index 58ddd9f..0000000 --- a/docs/pages/pack/docs/comparisons/_meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "vite": "Vite", - "webpack": "Webpack" -} diff --git a/docs/pages/pack/docs/comparisons/vite.mdx b/docs/pages/pack/docs/comparisons/vite.mdx deleted file mode 100644 index 5425796..0000000 --- a/docs/pages/pack/docs/comparisons/vite.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: Turbopack vs. Vite -description: Compare Turbopack vs. Vite ---- - -import { DocsBenchmarksGraph } from '../../../../components/pages/pack-home/DocsBenchmarksGraph'; -import { DocsBenchmarkStat } from '../../../../components/pages/pack-home/DocsBenchmarkStat'; -import BenchmarksCallout from './BenchmarksCallout'; -import Callout from '../../../../components/Callout' - -# Comparing Turbopack and Vite - -[Vite](https://vitejs.dev/) is an incredibly fast (non-)bundler that the web development community is extremely excited about - and so are we. Vite has raised the bar for web development and shown us what is possible for the future of the Web. If we were going to build a bundler, it had to perform at least as good as the (already impressive) Vite to validate our efforts. We're proud to say that we achieved that. - - - -## Speed - -Turbopack can outperform Vite on several key metrics. - -### Dev server startup time - -Vite is a non-bundler, which means it doesn't bundle your code at all. It sends each module directly to the browser. This means the browser does the hard work of handling dependencies between modules. - -On the surface, this seems like an unfair fight. Turbopack _bundles_ your application, meaning that a lot more work needs doing _before_ sending the code to the browser. - -But it turns out that Turbopack can handle this _faster_ than the browser can. By pre-bundling, we can save a lot of time over Vite's Native ESM system. You can learn more about this in our [Why Turbopack](/pack/docs/why-turbopack#bundling-vs-native-esm) section. - -This means that Turbopack's dev server starts up much faster than Vite's. On a 1,000 module application, Vite takes to start up. Turbopack starts up in - ** faster**. - -In large applications, this differential stays consistent. In a 30,000 module application, Turbopack starts up faster than Vite. - -Note that Vite is using the official [SWC plugin](https://github.com/vitejs/vite-plugin-react-swc) for these benchmarks, which is not the default configuration. - - - -### Code updates - -Vite is extremely fast in development because of its speedy Fast Refresh capabilities. When you update a file, Vite uses its Native ESM system to to send the updated module to the browser - and performs a little bit of magic to integrate that into the existing module graph. - -In Turbopack, we discovered that for Fast Refresh, we don't really need to do bundling work at all. We can send updates in a similar style to Vite. In fact - a little bit more efficiently: Turbopack sends changed modules directly through the WebSocket without doing any bundling at all. - -In a 1,000 module application, Turbopack can react to file changes ** faster** than Vite. - - diff --git a/docs/pages/pack/docs/comparisons/webpack.mdx b/docs/pages/pack/docs/comparisons/webpack.mdx deleted file mode 100644 index a8b821a..0000000 --- a/docs/pages/pack/docs/comparisons/webpack.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Turbopack vs. webpack -description: Compare Turbopack vs. webpack ---- - -import { DocsBenchmarksGraph } from '../../../../components/pages/pack-home/DocsBenchmarksGraph'; -import { DocsBenchmarkStat } from '../../../../components/pages/pack-home/DocsBenchmarkStat'; -import BenchmarksCallout from './BenchmarksCallout'; - -# Comparing Turbopack and webpack - -webpack has been downloaded over 3 billion times, making it today's most common JavaScript bundler. However, we found that we'd hit the limits of what it could do with its JavaScript-based architecture. - -We've built Turbopack as the successor of webpack: much **faster**, but just as **flexible and extensible**. - - - -## Speed - -Turbopack's incremental architecture outstrips webpack's speed on several key metrics. - -### Dev server startup time - -The main problem we found with webpack was development server startup time. If you end up importing a lot of modules in a certain page and open that page in your browser, the initial compile will take a few seconds. If you change routes in your development environment, you have to wait for a similar compile again for your new page. - -We designed Turbopack to be as lazy as possible, only doing work when it's requested. In a dev server, this means on incoming requests we do **exactly the work the user asked for**. No more unnecessary bundling of on demand loaded code before the user needs it. You can learn more in our [core concepts docs](/pack/docs/core-concepts#compiling-by-request). - -This means that Turbopack's dev server starts up much faster than webpack. Next.js 12, which uses webpack under the hood, can start up a build server on a 1,000 module application in . Turbopack starts up in - ** faster**. - - - -### Code updates - -As we continued to optimize webpack, we found a performance ceiling on how much faster we could make Fast Refresh. With around 2,000 components, the best number we could produce was 500ms. This mark was a tremendous feat in Next.js 12. Previously, that process would have taken around 10 seconds. - -With Turbopack, we achieved the goal we were aiming for: Fast Refresh performance that stays near-constant, no matter your application size. Instead of scaling with your application size, it scales based on the size of the _changes made_. - -In a 1,000 module application, Turbopack can react to file changes ** faster** than webpack. In a 30,000 module application, this is ** faster**. - - - -## Extensibility - -webpack has an extraordinary collection of [plugins](https://webpack.js.org/plugins/) to customize its behavior. Composing plugins lets you create custom toolchains which can support a huge variety of bundler features. - -In its alpha state, Turbopack cannot currently be configured with plugins. In the future, we plan to make Turbopack just as extensible as webpack - though likely with an altered API. diff --git a/docs/pages/pack/docs/core-concepts.mdx b/docs/pages/pack/docs/core-concepts.mdx deleted file mode 100644 index 40e2dd7..0000000 --- a/docs/pages/pack/docs/core-concepts.mdx +++ /dev/null @@ -1,64 +0,0 @@ ---- -title: Core Concepts -description: Learn about the innovative architecture that powers Turbopack's speed improvements. ---- - -# Core Concepts - -Let’s dive deep into the internals of Turbopack to figure out why it’s so fast. - -## The Turbo engine - -Turbopack is so fast because it’s built on a reusable library for Rust which enables incremental computation known as the Turbo engine. Here’s how it works: - -### Function-level caching - -In a Turbo engine-powered program, you can mark certain functions as ‘to be remembered’. When these functions are called, the Turbo engine will remember **what they were called with**, and **what they returned**. It’ll then save it in an in-memory cache. - -Here’s a simplified example of what this might look like in a bundler: - -![](/images/docs/pack/turbo-engine-first-run.png) - -We start with calling `readFile` on two files, `api.ts` and `sdk.ts`. We then `bundle` those files, `concat` them together, and end up with the `fullBundle` at the end. The results of all of those function calls get saved in the cache for later. - -Let’s imagine that we’re running on a dev server. You save the `sdk.ts` file on your machine. Turbopack receives the file system event, and knows it needs to recompute `readFile("sdk.ts")`: - -![](/images/docs/pack/turbo-engine-second-run.png) - -Since the result of `sdk.ts` has changed, we need to `bundle` it again, which then needs to be concatenated again. - -Crucially, `api.ts` hasn’t changed. We read its result from the cache and pass that to `concat` instead. So we save time by not reading it and re-bundling it again. - -Now imagine this in a real bundler, with thousands of files to read and transformations to execute. The mental model is the same. You can save enormous amounts of work by remembering the result of function calls and not re-doing work that’s been done before. - -### The cache - -The Turbo engine currently stores its cache in memory. This means the cache will last as long as the process running it - which works well for a dev server. When you run `next dev --turbo` in Next v13, you’ll start a cache with the Turbo engine. When you cancel your dev server, the cache gets cleared. - -In the future, we’re planning to persist this cache - either to the filesystem, or to a remote cache like Turborepo’s. This will mean that Turbopack could remember work done _across runs and machines._ - -### How does it help? - -This approach makes Turbopack extremely fast at computing incremental updates to your apps. This optimizes Turbopack for handling updates in development, meaning your dev server will always respond snappily to changes. - -In the future, a persistent cache will open the door to much faster production builds. By remembering work done _across runs_, new production builds could only rebuild changed files - potentially leading to enormous time savings. - -## Compiling by Request - -The Turbo engine helps provide extremely fast _updates_ on your dev server, but there’s another important metric to consider - startup time. The faster your dev server can start running, the faster you can get to work. - -There are two ways to make a process faster - work faster, or do less work. For starting up a dev server, the way to do less work is to compile _only the code that’s needed_ to get started. - -### Page-level compilation - -Versions of Next.js from 2-3 years ago used to compile the _entire application_ before showing your dev server. In Next.js [11], we began compiling _only the code on the page you requested._ - -That’s better, but it’s not perfect. When you navigate to `/users`, we’ll bundle all the client and server modules, dynamic-imported modules, and referenced CSS and images. That means if a large part of your page is hidden from view, or hidden behind tabs, we’ll still compile it anyway. - -### Request-level compilation - -Turbopack is smart enough to compile _only the code you request_. That means if a browser requests HTML, we compile only the HTML - not anything that is referenced by the HTML. - -If a browser wants some CSS, we’ll compile only that - without compiling referenced images. Got a big charting library behind `next/dynamic`? Doesn’t compile it until the tab showing the chart is shown. Turbopack even knows _to not compile source maps unless your Chrome DevTools are open_. - -If we were to use native ESM, we’d get similar behavior. Except that Native ESM produces a _lot_ of requests to the server, as discussed in our [Why Turbopack](/pack/docs/why-turbopack) section. With request-level compilation, we get to both reduce the number of requests _and_ use native speed to compile them. As you can see in our [benchmarks](/pack/docs/benchmarks), this provides significant performance improvements. diff --git a/docs/pages/pack/docs/features.mdx b/docs/pages/pack/docs/features.mdx deleted file mode 100644 index 984bd34..0000000 --- a/docs/pages/pack/docs/features.mdx +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Features -description: Learn about Turbopack's supported features ---- - -import { TurbopackFeatures } from '../../../components/TurbopackFeatures' - -# Features - -The practice of building web applications is enormously diverse. In CSS alone, you have SCSS, Less, CSS Modules, PostCSS, and hundreds of other libraries. Frameworks like React, Vue and Svelte require custom setups. - -When building a bundler, we needed to consider which features would be: - -- **Built-in**: they work out of the box, no config required -- **Available via plugins**: usually installed from a registry and configured -- **Unavailable**: not available at all - -**Turbopack is in alpha**, so very few of these decisions are set in stone. In its current state, **Turbopack cannot yet be configured** - so plugins are not available yet. - -Let's discuss which features are available out-of-the-box, in Turbopack's default configuration. We'll also touch on features which will be configurable via plugins. - - diff --git a/docs/pages/pack/docs/features/_meta.json b/docs/pages/pack/docs/features/_meta.json deleted file mode 100644 index c63b5ee..0000000 --- a/docs/pages/pack/docs/features/_meta.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "javascript": "JavaScript", - "typescript": "TypeScript", - "frameworks": "Frameworks", - "css": "CSS", - "dev-server": "Dev Server", - "static-assets": "Static Assets", - "imports": "Imports", - "environment-variables": "Environment Variables", - "customizing-turbopack": "Customizing Turbopack" -} diff --git a/docs/pages/pack/docs/features/css.mdx b/docs/pages/pack/docs/features/css.mdx deleted file mode 100644 index 6e2c2fd..0000000 --- a/docs/pages/pack/docs/features/css.mdx +++ /dev/null @@ -1,80 +0,0 @@ -import Callout from '../../../../components/Callout'; - -# CSS - -CSS bundling is handled by SWC, using a Rust crate called `swc_css`. We haven't yet documented `swc_css` separately, but it's integrated into Turbopack and supports several CSS features: - -## Global CSS - -Importing CSS into global scope is supported **out-of-the-box** in Turbopack. - -```ts -import './globals.css'; -``` - -## CSS Modules - -Turbopack handles CSS Modules out-of-the-box. Any file with a `.module.css` extension will be considered a CSS module, and you can import it into a JavaScript or TypeScript file: - -```tsx Component.tsx -import cssExports from './phone.module.css' -``` - -This follows the same rules set out by [Next.js](https://nextjs.org/docs/basic-features/built-in-css-support#adding-component-level-css) - letting you easily distinguish between global and scoped CSS. - -## `postcss-nested` - -Turbopack handles [`postcss-nested`](https://www.npmjs.com/package/postcss-nested) syntax out-of-the-box. This useful library lets you nest CSS declarations inside each other: - -```css phone.css -.phone { - &_title { - width: 500px; - @media (max-width: 500px) { - width: auto; - } - body.is_dark & { - color: white; - } - } - img { - display: block; - } -} -``` - -## `@import` syntax - -Using the CSS `@import` syntax to import other CSS files works **out-of-the-box**. This gives you the ability to combine several CSS files together into a single module: - -```css filename="globals.css" -@import './modal.css'; -@import './dark.css'; -``` - -## PostCSS - -PostCSS gives you the ability to use plugins to enhance your CSS toolchain. It's been an invaluable tool for integrating libraries like Tailwind and `autoprefixer` into applications. - -The most common pattern is adding a `postcss.config.js` file to the root of your application, where you can import and configure your plugins. - -When Turbopack finds a `postcss.config.js` file, it will automatically process your CSS files with PostCSS in a Node.js worker pool. - -```js filename="postcss.config.js" -module.exports = { - plugins: { - tailwindcss: {}, - autoprefixer: {} - } -}; -``` - -## SCSS and LESS - -`.scss` and `.less` files let you utilize SCSS and LESS - languages which enhance CSS in various ways. These languages **don't currently work** out-of-the-box with Turbopack. - -These are likely to be available via plugins in the future. - -## Tailwind CSS - -Tailwind CSS can be used via PostCSS plugins. You can use the [official Tailwind Next.js guide](https://tailwindcss.com/docs/guides/nextjs) to get started. diff --git a/docs/pages/pack/docs/features/customizing-turbopack.mdx b/docs/pages/pack/docs/features/customizing-turbopack.mdx deleted file mode 100644 index 2ddd6a1..0000000 --- a/docs/pages/pack/docs/features/customizing-turbopack.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Customizing Turbopack -description: Learn about how to customize Turbopack to your needs ---- - -import Callout from "../../../../components/Callout"; - -# Customizing Turbopack - -Turbopack can be customized to transform different files and change how modules are resolved. It supports a subset of webpack's loader API and offers similar configuration aliasing module resolution. - -## webpack loaders for Next.js - - - Turbopack for Next.js does not require loaders nor loader configuration for built-in functionality, just as they aren't required for Next.js. Turbopack has built-in support for css and compiling modern JavaScript, so there's no need for `css-loader`, `postcss-loader`, or `babel-loader` if you're just using `@babel/preset-env`. - - -If you need loader support beyond what's built in, many webpack loaders already work with Turbopack. There are currently some limitations: - -- Only a core subset of the webpack loader API is implemented. This is enough for some popular loaders, and we'll expand our support for this API in the future. -- Only loaders that return JavaScript code are supported. Loaders that transform files like stylesheets or images are not currently supported. -- Options passed to webpack loaders must be plain JavaScript primitives, objects, and arrays. For example, it's not possible to pass `require()`d plugin modules as option values. - -As of Next 13.2, configuring webpack loaders is possible for Next.js apps through an experimental option in `next.config.js`. `turbo.loaders` can be set as a mapping of file extensions to a list of package names or `{loader, options}` pairs: - -```js filename="next.config.js" -module.exports = { - experimental: { - turbo: { - loaders: { - // Option format - '.md': [ - { - loader: '@mdx-js/loader', - options: { - format: 'md', - }, - }, - ], - // Option-less format - '.mdx': ['@mdx-js/loader'], - }, - }, - }, -} -``` - -If you need to pass something like the result of importing an external package as a loader option, it's possible to wrap the webpack loader with your own, specifying options there. **This is an interim solution and should not be necessary in the future.** This loader wraps `@mdx-js/loader` and configures the `rehypePrism` rehype plugin: - -```js filename="my-mdx-loader.js" -const mdxLoader = require('@mdx-js/loader'); -const rehypePrism = require('@mapbox/rehype-prism'); - -module.exports = function (code) { - const prevGetOptions = this.getOptions.bind(this); - this.getOptions = function getOptions(...args) { - return { - ...prevGetOptions(...args), - rehypePlugins: [rehypePrism] - } - } - - mdxLoader.call(this, code); -} -``` - -Then, configure Next.js to load the wrapper loader: - -```js filename="next.config.js" -module.exports = { - experimental: { - turbo: { - loaders: { - '.mdx': ['./my-mdx-loader'], - }, - }, - }, -} -``` - -### Supported loaders - -The following loaders have been tested to work with Turbopack's webpack loader implementation: - -- [`babel-loader`](https://www.npmjs.com/package/babel-loader) -- [`@mdx-js/loader`](https://www.npmjs.com/package/@mdx-js/loader) -- [`@svgr/webpack`](https://www.npmjs.com/package/@svgr/webpack) -- [`svg-inline-loader`](https://www.npmjs.com/package/svg-inline-loader) -- [`yaml-loader`](https://www.npmjs.com/package/yaml-loader) -- [`string-replace-loader`](https://www.npmjs.com/package/string-replace-loader) -- [`raw-loader`](https://www.npmjs.com/package/raw-loader) - -## Resolve aliases - -Turbopack can be configured to modify module resolution through aliases, similar to webpack's [`resolve.alias`](https://webpack.js.org/configuration/resolve/#resolvealias) configuration: - -```js filename="next.config.js" -module.exports = { - experimental: { - turbo: { - resolveAlias: { - underscore: 'lodash', - mocha: { browser: 'mocha/browser-entry.js' }, - }, - }, - }, -} -``` - -This aliases imports of the `underscore` package to the `lodash` package. In other words, `import underscore from 'underscore'` will load the `lodash` module instead of `underscore`. - -Turbopack also supports conditional aliasing through this field, similar to Node.js's [conditional exports](https://nodejs.org/docs/latest-v18.x/api/packages.html#conditional-exports). At the moment only the `browser` condition is supported. In the case above, imports of the `mocha` module will be aliased to `mocha/browser-entry.js` when Turbopack targets browser environments. diff --git a/docs/pages/pack/docs/features/dev-server.mdx b/docs/pages/pack/docs/features/dev-server.mdx deleted file mode 100644 index ef8e01a..0000000 --- a/docs/pages/pack/docs/features/dev-server.mdx +++ /dev/null @@ -1,17 +0,0 @@ -# Dev Server - -Turbopack is optimized to give you an extremely fast development server. We considered these features indispensable. - -## HMR - -Hot Module Replacement (HMR) gives your dev server the ability to push file updates to the browser without triggering a full refresh. This works for most static assets (including JavaScript files) enabling a smooth and fast developer experience. - -Turbopack supports Hot Module Replacement out of the box. Because of our [incremental architecture](/pack/docs/core-concepts), we are hyper-optimized for delivering fast updates. - -{/* Maybe link to benchmarks here? */} - -## Fast Refresh - -Fast Refresh builds on top of HMR by providing a framework-level integration to preserve _state_ across updates. Changes to a `` component, for instance, would preserve the component's internal `count` across changes. - -Turbopack supports Fast Refresh out of the box for React. Support for other frameworks will be [added over time](/pack/docs/features/frameworks). diff --git a/docs/pages/pack/docs/features/environment-variables.mdx b/docs/pages/pack/docs/features/environment-variables.mdx deleted file mode 100644 index 4e6daec..0000000 --- a/docs/pages/pack/docs/features/environment-variables.mdx +++ /dev/null @@ -1,29 +0,0 @@ -# Environment variables - -## `.env` files - -Turbopack will parse and inject `.env` files out of the box. - -``` -NEXT_PUBLIC_DEPLOYMENT_NAME="my-site" -DATABASE_URL="postgres://" -``` - -This includes all the variations these files come in: - -``` -.env -.env.local -.env.development -.env.production.local -``` - -### Live reloading - -Not only that, but Turbopack will live reload when these values change. Restarting your dev server just to inject a new environment variable can be extremely annoying - Turbopack does it for you. - -## `process.env` - -Environment variables will be injected into `process.env`. For instance, `DATABASE_URL` will be on `process.env.DATABASE_URL`. - -This follows the tradition of Node.js, webpack 5 and Next.js 12, which each use `process.env` for variable injection. diff --git a/docs/pages/pack/docs/features/frameworks.mdx b/docs/pages/pack/docs/features/frameworks.mdx deleted file mode 100644 index 59f6998..0000000 --- a/docs/pages/pack/docs/features/frameworks.mdx +++ /dev/null @@ -1,45 +0,0 @@ -# Frameworks - -Turbopack plans to offer first-class support for multiple frameworks. No matter whether you're using Svelte, React, Vue.js, or another framework, we want to provide a great experience on Turbopack. - -## React - -### JSX/TSX - -`.jsx` and `.tsx` files are supported out of the box with Turbopack. We use [SWC](https://swc.rs/) to compile your JavaScript and TypeScript code, which results in extremely fast compilation. - -Similar to Next.js, Turbopack doesn't require you to import React in order to use JSX: - -```diff filename="src/index.tsx" -- import React from 'react'; - -const Component = () => { - return
-} -``` - -### React Server Components - -React Server Components let you declare certain components as 'server' components, allowing you to run backend code inside an `async` function. Next.js 13 brings [first-class support for them](https://beta.nextjs.org/docs/rendering/server-and-client-components). - -React Server Components impose unusual constraints on your bundler. The mix of client and server code means you need to ensure that server code does not get compiled to the client, and vice versa. - -Turbopack has been built from the ground up to solve these problems - it works with React Server Components out of the box. - -## Next - -Turbopack's Alpha version has been focused on providing a great experience for Next.js's dev server. We're using this as our initial goal to show what Turbopack can do. In the future, we want Turbopack to act as a low-level engine for other frameworks. - -This means that Turbopack plans to support everything in Next.js. - -### `next/dynamic` - -[`next/dynamic`](https://nextjs.org/docs/advanced-features/dynamic-import) is not yet supported - however, we plan to support it out of the box soon. - -## Vue and Svelte - -[VueJS](https://vuejs.org/) and [Svelte](https://svelte.dev/) are tremendously popular frameworks which deliver a world-class developer experience. - -Since Turbopack is in alpha, we're focusing our support on Next.js's dev server. That means that right now, Vue and Svelte don't work out of the box. - -In future versions, we'll be supporting Vue and Svelte via plugins. diff --git a/docs/pages/pack/docs/features/imports.mdx b/docs/pages/pack/docs/features/imports.mdx deleted file mode 100644 index 5dee4ce..0000000 --- a/docs/pages/pack/docs/features/imports.mdx +++ /dev/null @@ -1,47 +0,0 @@ -# Imports - -Turbopack supports CJS and ESM imports out of the box, and offers partial support for AMD. - -Turbopack bundles your application, so imports won't be resolved to native browser ESM. You can learn why in our [bundling vs Native ESM](/pack/docs/why-turbopack#bundling-vs-native-esm) section. - -## CommonJS - -Turbopack supports the `require` syntax out-of-the-box: - -```ts -const { add } = require('./math'); - -add(1, 2); -``` - -We also support dynamic `require()` syntax, for if you want to import a dynamically named asset: - -```ts -const imgName = getRandomImgName(); - -const img = require(`./images/${imgName}.png`); -``` - -## ESM - -Importing via the `import` syntax is also supported out-of-the-box. This includes static assets, and `import type`: - -```ts -import img from './img.png'; - -import type { User } from '../server/types'; - -import { z } from 'zod'; -``` - -## Dynamic Imports - -Turbopack supports dynamic imports via `import()`: - -```ts -const getFeatureFlags = () => { - return import('/featureFlags').then(mod => { - return mod.featureFlags; - }) -} -``` diff --git a/docs/pages/pack/docs/features/javascript.mdx b/docs/pages/pack/docs/features/javascript.mdx deleted file mode 100644 index 8b7a294..0000000 --- a/docs/pages/pack/docs/features/javascript.mdx +++ /dev/null @@ -1,39 +0,0 @@ -import Callout from "../../../../components/Callout"; - -# JavaScript - -## ECMAScript Support - -Turbopack uses [SWC](https://swc.rs/) to bundle JavaScript and TypeScript files. So, we match SWC's support for ECMAScript versions - anything that SWC supports, Turbopack will support. - -This means that by default **we support all syntax in ESNext**. - -## Browserslist - -[Browserslist](https://github.com/browserslist/browserslist) has become an industry standard for defining which browsers you plan to target. To make use of it, you can add a `browserslist` field to your `package.json`: - -```json filename="package.json" -{ - "browserslist": [ - "last 1 version", - "> 1%", - "not dead" - ] -} -``` - -Turbopack supports Browserslist **out-of-the-box**. We pass the information we find in your `package.json` to SWC, which handles [`browserslist` support](https://swc.rs/docs/configuration/supported-browsers) for us. - -This means you can feel comfortable using Turbopack to target legacy browsers, or deciding to only ship code to modern browsers. - - - Turbopack is available in alpha preview with a dev server, which uses a pre-set minimal browserslist to minimize transformation during development. In a future release, Turbopack will build apps for production targeting your defined browserslist. - - -## Babel - -[Babel](https://babel.dev/) allows you to add custom transformations to your code to provide custom syntax, including support for early language proposals. - -Babel plugins are currently **not supported** on Turbopack. In our default configuration, we don't use Babel to compile JavaScript or TypeScript code. - -In the future, Babel support will be provided via plugins. diff --git a/docs/pages/pack/docs/features/static-assets.mdx b/docs/pages/pack/docs/features/static-assets.mdx deleted file mode 100644 index 26ebf7a..0000000 --- a/docs/pages/pack/docs/features/static-assets.mdx +++ /dev/null @@ -1,47 +0,0 @@ -# Static Assets - -Part of bundling for the web is handling all the asset types the web supports - images, videos, JSON, fonts, and much more. Turbopack offers familiar tools for these so you can immediately get productive. - -## Import static assets - -Importing static assets works out of the box with Turbopack: - -```ts -import img from './img.png' -import video from './video.mp4' -import audio from './audio.wav' -``` - -### Next.js - -In webpack and some other frameworks, importing an image returns a string containing that image's URL. - -```ts -import img from './img.png'; - -console.log(img); // /assets/static/1uahwd98h123.png -``` - -In Next.js, importing an image actually returns an object, containing various metadata about the image. This is so it can be fed into [Next.js's Image component](https://nextjs.org/docs/basic-features/image-optimization#local-images). - -The behavior of extracting an object of metadata from the image is **not yet supported**. For now, imported images will resolve to strings. - -## Public directory - -The `/public` directory lets you place assets which you want to be available on the root URL of the website. For instance, `public/favicon.png` will be available at `https://example/favicon.png`. - -In Turbopack, the `/public` directory is supported out of the box. - -## JSON - -Most frameworks allow you to import JSON directly into your application: - -```ts -import fixtures from './fixtures.json'; -``` - -This is supported out of the box with Turbopack, as is performing a named import on that JSON: - -```ts -import { users, posts } from './fixtures.json'; -``` diff --git a/docs/pages/pack/docs/features/typescript.mdx b/docs/pages/pack/docs/features/typescript.mdx deleted file mode 100644 index a643486..0000000 --- a/docs/pages/pack/docs/features/typescript.mdx +++ /dev/null @@ -1,40 +0,0 @@ -# TypeScript - -Turbopack supports [TypeScript](https://www.typescriptlang.org/) out of the box. This means you can import `.ts` files with Turbopack. We support all of TypeScript's feature set. - -Thanks to our JSX support, you can also import `.tsx` files too. - -## Resolving `paths` and `baseUrl` - -In TypeScript, you can use the [`paths`](https://www.typescriptlang.org/tsconfig#paths) property of `tsconfig.json` to let you import files from custom paths. - -```json -{ - "compilerOptions": { - "baseUrl": "src", - "paths": { - "app/*": ["app/*"], - "config/*": ["app/_config/*"], - "shared/*": ["app/_shared/*"], - }, -} -``` - -This would let you import directly from `app/*` without needing to do a relative import: - -```diff filename="src/app/some/deep/file/in/your/app.ts" -- import { add } from '../../../../../math'; -+ import { add } from 'app/math'; - -add(); -``` - -Turbopack reads the `paths` and `baseUrl` in `tsconfig.json` in order to resolve these paths, just like `Next.js` does. - -This means you only need to configure your absolute paths in one place. - -## Type Checking - -Turbopack does not perform type checks on your application. We use [SWC](https://swc.rs/) to compile TypeScript code, which also does not perform type checks. - -This means that in order to run your type checks, you'll need a sidecar process running `tsc --watch`. Or, you can rely on your IDE's TypeScript integration. diff --git a/docs/pages/pack/docs/index.mdx b/docs/pages/pack/docs/index.mdx deleted file mode 100644 index 3cbc782..0000000 --- a/docs/pages/pack/docs/index.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: Turbopack Quickstart -description: Start Building Web Applications with Turbopack ---- - -import { TurbopackQuickstartArea } from "../../../components/TurbopackQuickstart"; -import Callout from "../../../components/Callout"; -import { Tabs, Tab } from "../../../components/Tabs"; -import FullTurboCTA from "../../../components/FullTurboCTA"; - -# Getting Started with Turbopack - -Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust by the creators of webpack and [Next.js](https://nextjs.org/) at [Vercel](https://vercel.com/). - -The secret to Turbopack's performance is twofold: highly optimized machine code and a low-level incremental computation engine that enables caching down to the level of individual functions. Once Turbopack performs a task it never does it again. - -Our team has taken the lessons from 10 years of webpack, combined with the innovations in incremental computation from [Turborepo](/repo) and Google's Bazel, and created an architecture ready to support the coming decades of computing. - - - Turbopack is currently in alpha. It is not yet ready for production use. We appreciate your support and feedback as we work to make it ready for everyone. - - -## Quickstart - -As of today, Turbopack can be used in Next.js v13. In the future we will be releasing a standalone CLI, plugin API, and support for other frameworks such as Svelte and Vue. For now, please follow these instructions to get started: - -1. Create a Next.js v13 project with Turbopack: - -```bash -npx create-next-app --example with-turbopack -``` - -2. Start the Next.js development server (with Turbopack): - - - - ```bash - npm run dev - ``` - - - ```bash - yarn dev - ``` - - - ```bash - pnpm dev - ``` - - - -The Next.js v13 development server is now powered by Turbopack! Startup and updates should both be near-instant. The larger the application, the larger the improvement will be. - -## Next Steps - -Want to learn more about Turbopack? Here's a deep dive on what we think makes it special. - - - - diff --git a/docs/pages/pack/docs/migrating-from-webpack.mdx b/docs/pages/pack/docs/migrating-from-webpack.mdx deleted file mode 100644 index 1788b18..0000000 --- a/docs/pages/pack/docs/migrating-from-webpack.mdx +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Migrate from webpack to Turbopack -description: Learn about how to migrate from webpack to its Rust-powered successor, Turbopack. ---- - -import Callout from "../../../components/Callout"; - -# Migrating from webpack to Turbopack - - - Turbopack now implements basic webpack loader support and configuration familiar to webpack users. Visit [Customizing Turbopack](features/customizing-turbopack) for how to configure Turbopack to use webpack loaders. - - -We're planning Turbopack as the successor to webpack. In the future, we plan to give Turbopack all the tools needed to support your webpack app. - -## webpack loaders and resolve aliases - -For apps running Next.js 13.2 or later, Turbopack supports configuration familiar to webpack users, including support for webpack loaders and customizing resolution rules. Visit [Customizing Turbopack](features/customizing-turbopack) for how to configure Turbopack with these options. Note that using webpack-based Next.js plugins as-is from `next.config.js` is **not yet possible**. - -## FAQ - -### Will it be compatible with webpack's API? - -webpack has a huge API. It's extremely flexible and extensible, which is a big reason why it's so popular. - -We're planning on making Turbopack very flexible and extensible, but we're **not planning 1:1 compatibility with webpack**. This lets us make choices which improve on webpack's API, and lets us optimize for speed and efficiency. - -### Will we be able to use webpack plugins? - -webpack plugins are a crucial part of webpack's ecosystem. They let you customize your toolchain, giving you low-level tools to maximize your productivity. - -Unlike loaders, webpack plugins can be tightly integrated with webpack's internals. - -Since we're not offering 1:1 API compatibility for plugins, most won't work out of the box with Turbopack. However, we're working on porting several of the most popular webpack plugins to Turbopack. diff --git a/docs/pages/pack/docs/roadmap.mdx b/docs/pages/pack/docs/roadmap.mdx deleted file mode 100644 index 9bd7c97..0000000 --- a/docs/pages/pack/docs/roadmap.mdx +++ /dev/null @@ -1,33 +0,0 @@ -# Roadmap - -We've got big plans for Turbopack. Here's what we're aiming for in the future: - -## Next.js - -Right now, Turbopack is being used as an opt-in feature in Next.js's dev server. This is helping to create an extremely fast experience in local development that scales to big projects. - -Next, we want to use Turbopack to power production builds with Next.js. We think that this will result in a big boost in performance, especially when integrated with remote caching. - -## Svelte - -We're planning to build a first-class integration with Svelte to let Turbopack power the next generation of SvelteKit applications. - -## Other Frameworks - -We are in active discussions with other frameworks to bring Turbopack to their users. We're excited to see what we can build together! - -## Remote Caching and Replication - -Turbopack is built from the ground up to take advantage of [caching](/pack/docs/core-concepts#the-turbo-engine). Currently, this cache is stored in-memory only. This lets us optimize for our current use case - making the Next.js dev server fast. - -In the future, we plan to persist this cache to the file system, to speed up Turbopack between runs. This will work similarly to [Turborepo's cache](/repo/docs/core-concepts/caching) - but at a much more granular level. Turborepo can currently only cache the results of entire builds. Turbopack, however, can cache the results of individual functions within those builds - saving much more time over subsequent runs. - -Once persisting to the file system is working, we can build the next logical step: persisting to a remote cache. With Turborepo, we've already built [remote caching](/repo/docs/core-concepts/remote-caching) on Vercel. In the future, you'll be able to _share_ Turbopack's hyper-granular cache across your whole team, using the Vercel Remote Cache. - -## Migration for webpack users - -To learn more about our future plans for webpack integration, check out our [Migrating from webpack](/pack/docs/migrating-from-webpack) page. - -## Fusion with Turborepo - -We are currently migrating/rewriting Turborepo in Rust. In the future, Turborepo and Turbopack will merge into a single toolchain--Turbo--that can be used as either a bundler or a build system or both. diff --git a/docs/pages/pack/docs/why-turbopack.mdx b/docs/pages/pack/docs/why-turbopack.mdx deleted file mode 100644 index 18cec98..0000000 --- a/docs/pages/pack/docs/why-turbopack.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Why Turbopack? -description: Learn why we think Turbopack is the future of bundling for the web. ---- - -# Why Turbopack? - -When we set out to create Turbopack, we wanted to solve a problem. We had been working on speed improvements for Next.js. We migrated away from several JS-based tools. Babel, gone. Terser, gone. Our next target was another JS-based tool, webpack. - -Replacing it became our goal. But with what? - -A new generation of native-speed bundlers were emerging, like esbuild and swc. But after assessing the bundlers on the market, we decided to build our own. Why? - -## Bundling vs Native ESM - -Frameworks like Vite use a technique where they don’t bundle application source code in development mode. Instead, they rely on the browser’s native ES Modules system. This approach results in incredibly responsive updates since they only have to transform a single file. - -However, Vite can hit scaling issues with large applications made up of many modules. A flood of cascading network requests in the browser can lead to a relatively slow startup time. For the browser, it’s faster if it can receive the code it needs in as few network requests as possible - even on a local server. - -That’s why we decided that, like webpack, we wanted Turbopack to bundle the code in the development server. Turbopack can do it much faster, especially for larger applications, because it is written in Rust and skips optimization work that is only necessary for production. - -## Incremental Computation - -There are two ways to make a process faster: do less work or do work in parallel. We knew if we wanted to make the fastest bundler possible, we’d need to pull hard on both levers. - -We decided to create a reusable Turbo build engine for distributed and incremental behavior. The Turbo engine works like a scheduler for function calls, allowing calls to functions to be parallelized across all available cores. - -The Turbo engine also caches the result of all the functions it schedules, meaning it never needs to do the same work twice. Put simply, **it does the minimum work at maximum speed**. - -### Vite and esbuild - -Other tools take a different attitude to ‘doing less work’. Vite minimizes work done by using Native ESM in development mode. We decided not to take this approach for the reasons listed above. - -Under the hood, Vite uses esbuild for many tasks. esbuild is a bundler - a superbly fast one. It doesn’t force you to use native ESM. But we decided not to adopt esbuild for a few reasons. - -esbuild’s code is hyper-optimized for one task - bundling fast. It doesn’t have HMR, which we don’t want to lose from our dev server. - -esbuild is an extremely fast bundler, but it doesn’t do much caching. This means you _will_ end up doing the same work again and again, even if that work is at the speed of native. - -Evan Wallace refers to esbuild as a [proof-of-concept for the next generation of bundlers](https://news.ycombinator.com/item?id=22336334). We think he’s right. We feel that a Rust-powered bundler _with_ incremental computation could perform better at a larger scale than esbuild. - -## Lazy bundling - -Early versions of Next.js tried to bundle the _entire_ web app in development mode. We quickly realized that this ‘eager’ approach was less than optimal. Modern versions of Next.js bundle only the pages requested by the dev server. For instance, if you go to `localhost:3000`, it’ll bundle only `pages/index.jsx`, and the modules it imports. - -This more ‘lazy’ approach (only bundling assets when absolutely necessary) is key for a fast dev server. Native ESM handles this without much magic - you request a module, which requests other modules. However, we wanted to build a bundler, for the reasons explained above. - -esbuild doesn’t have a concept of ‘lazy’ bundling - it’s all-or-nothing, unless you specifically target only certain entry points. - -Turbopack’s development mode builds a minimal graph of your app’s imports and exports based on received requests and only bundles the minimal code necessary. Learn more in the [core concepts docs](/pack/docs/core-concepts#compiling-by-request). - -This strategy makes Turbopack extremely fast when first starting up the dev server. We compute only the code necessary to render the page, then ship it to the browser in a single chunk. At large scale, this ends up being significantly faster than Native ESM. - -## Summary - -We wanted to: - -- Build a bundler. Bundlers outperform Native ESM when working on large applications. -- Use incremental computation. The Turbo engine brings this into the core of Turbopack’s architecture - maximizing speed and minimizing work done. -- Optimize our dev server’s startup time. For that, we build a lazy asset graph to compute only the assets requested. - -That’s why we chose to build Turbopack. diff --git a/docs/pages/pack/index.mdx b/docs/pages/pack/index.mdx deleted file mode 100644 index f1f71b1..0000000 --- a/docs/pages/pack/index.mdx +++ /dev/null @@ -1,8 +0,0 @@ ---- -overrideTitle: "Turbopack - The successor to webpack" -description: "Turbopack is an incremental bundler optimized for JavaScript and TypeScript, written in Rust." ---- - -import TurbopackHome from "../../components/pages/pack-home"; - - diff --git a/docs/pages/repo/_meta.json b/docs/pages/repo/_meta.json deleted file mode 100644 index 4941080..0000000 --- a/docs/pages/repo/_meta.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "index": { - "type": "page", - "display": "hidden", - "theme": { - "layout": "raw", - "sidebar": false, - "toc": true - } - }, - "docs": { - "title": "Docs", - "display": "children" - } -} diff --git a/docs/pages/repo/docs/_meta.json b/docs/pages/repo/docs/_meta.json deleted file mode 100644 index 750a466..0000000 --- a/docs/pages/repo/docs/_meta.json +++ /dev/null @@ -1,20 +0,0 @@ -{ - "index": { - "title": "Quickstart" - }, - "installing": "Installing Turborepo", - "getting-started": "Getting Started", - "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", - "acknowledgements": "Acknowledgements", - "faq": "FAQ" -} diff --git a/docs/pages/repo/docs/acknowledgements.mdx b/docs/pages/repo/docs/acknowledgements.mdx deleted file mode 100644 index 50a5c46..0000000 --- a/docs/pages/repo/docs/acknowledgements.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Acknowledgements and Prior Art -description: Thank you to all these developers, build systems, and monorepo tools for their support and assistance. ---- - -# Acknowledgements - -Turborepo was originally created by [Jared Palmer](https://twitter.com/jaredpalmer) as a closed-source enterprise software offering. In late 2021, [Vercel acquired Turborepo](https://vercel.com/blog/vercel-acquires-turborepo) and open sourced the codebase. - -Today, Turborepo has dedicated full-time team working on it as well as a growing list of [open source contributors](https://github.com/vercel/turbo/graphs/contributors). - -## Inspiration / Prior Art - -At [Vercel](https://vercel.com/), we believe deeply in the open source movement and in the power of open collaboration. To that end, it's important to provide meaningful attribution to the projects and people that inspire(d) us and our work. - -We'd like to make a special shoutout to other build systems, monorepo tools, and prior art: - -- Bazel - https://bazel.build -- Buck - https://buck.build -- Please - https://please.build -- Pants - https://www.pantsbuild.org -- Scoot - https://github.com/twitter/scoot -- TSDX - https://tsdx.io -- Lerna - https://lerna.js.org -- Lage - https://microsoft.github.io/lage -- Backfill - https://github.com/microsoft/backfill -- Bolt - https://github.com/boltpkg/bolt -- Rush - https://rushjs.io -- Preconstruct - https://preconstruct.tools -- Nx - https://nx.dev -- Yarn - https://yarnpkg.com -- npm - https://www.npmjs.com -- pnpm - https://pnpm.js.org - -Throughout the documentation, wherever applicable, we also provide inline callouts and links to the projects and people that have inspired us. - -## Additional Thanks - -Additionally, we're grateful to: - -- [Rick Button](https://twitter.com/rickbutton) for donating the `turbo` package name on npm -- [Iheanyi Ekechukwu](https://twitter.com/kwuchu) for helping Jared pick up Golang during the Pandemic! -- [Kenneth Chau](https://twitter.com/kenneth_chau) for Lage's Scope and Pipeline API and docs -- [Miguel Oller](https://mobile.twitter.com/ollermi) and [MakeSwift.com](https://www.makeswift.com/) for piloting Turborepo -- [Eric Koslow](https://twitter.com/ekosz1), [Jack Hanford](https://twitter.com/jackhanford), and [Lattice.com](https://lattice.com/) for piloting Turborepo diff --git a/docs/pages/repo/docs/ci.mdx b/docs/pages/repo/docs/ci.mdx deleted file mode 100644 index 779a891..0000000 --- a/docs/pages/repo/docs/ci.mdx +++ /dev/null @@ -1,13 +0,0 @@ ---- -title: Continuous Integration -description: Recipes for using Turborepo with GitHub Actions, CircleCI, and other continuous integration providers. ---- - -# Continuous Integration - -Turborepo not only speeds up builds, but also your CI pipeline. Below are a few ways to use Turborepo with various Continuous Integration providers. - -- [CircleCI](/repo/docs/ci/circleci) -- [GitHub Actions](/repo/docs/ci/github-actions) -- [GitLab CI](/repo/docs/ci/gitlabci) -- [Travis CI](/repo/docs/ci/travisci) diff --git a/docs/pages/repo/docs/ci/_meta.json b/docs/pages/repo/docs/ci/_meta.json deleted file mode 100644 index b9ed68d..0000000 --- a/docs/pages/repo/docs/ci/_meta.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "circleci": "CircleCI", - "github-actions": "GitHub Actions", - "gitlabci": "GitLab CI", - "travisci": "Travis CI" -} diff --git a/docs/pages/repo/docs/ci/circleci.mdx b/docs/pages/repo/docs/ci/circleci.mdx deleted file mode 100644 index c102dab..0000000 --- a/docs/pages/repo/docs/ci/circleci.mdx +++ /dev/null @@ -1,145 +0,0 @@ ---- -title: Using Turborepo with CircleCI -description: How to use CircleCI with Turborepo to optimize your CI workflow ---- - -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Using Turborepo with CircleCI - -The following example shows how to use Turborepo with [CircleCI](https://circleci.com/). - -For a given root `package.json`: - -```json -{ - "name": "my-turborepo", - "scripts": { - "build": "turbo run build", - "test": "turbo run test" - }, - "devDependencies": { - "turbo": "1.2.5" - } -} -``` - -And a `turbo.json`: - -```json -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**"], - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["^build"] - }, - } -} -``` - -Create a file called `.circleci/config.yml` in your repository with the following contents: - - - - ```yaml - version: 2.1 - orbs: - node: circleci/node@5.0.2 - workflows: - test: - jobs: - - test - jobs: - test: - docker: - - image: cimg/node:lts - steps: - - checkout - - node/install-packages - - run: - command: npm run build - - run: - command: npm run test - ``` - - - ```yaml - version: 2.1 - orbs: - node: circleci/node@5.0.2 - workflows: - test: - jobs: - - test - jobs: - test: - docker: - - image: cimg/node:lts - steps: - - checkout - - node/install-packages: - pkg-manager: yarn - - run: - command: yarn build - - run: - command: yarn test - ``` - - - ```yaml - version: 2.1 - orbs: - node: circleci/node@5.0.2 - workflows: - test: - jobs: - - test - jobs: - test: - docker: - - image: cimg/node:lts - steps: - - checkout - - node/install-packages: - - run: - command: npm i -g pnpm - - run: - command: pnpm build - - run: - command: pnpm test - ``` - - - -## Remote Caching - -To use Remote Caching with CircleCI, add the following environment variables to your CircleCI project -to make them available to your `turbo` commands. - -- `TURBO_TOKEN` - The Bearer token to access the Remote Cache -- `TURBO_TEAM` - The account to which the monorepo belongs - -To use Vercel Remote Caching, you can get the value of these variables in a few steps: - -1. Create a Scoped Access Token to your account in the [Vercel Dashboard](https://vercel.com/account/tokens) - -![Vercel Access Tokens](/images/docs/vercel-create-token.png) - -Copy the value to a safe place. You'll need it in a moment. - -2. Go to your CircleCI project settings and click on the **Environment Variables** tab. Create a new secret called `TURBO_TOKEN` and enter the value of your Scoped Access Token. - -![CircleCI Environment Variables](/images/docs/circleci-environment-variables.png) -![CircleCI Create Environment Variables](/images/docs/circleci-create-environment-variables.png) - -3. Make a second secret called `TURBO_TEAM` and enter the value of your team's Vercel URL _without_ the `vercel.com/`. Your Team URL can be found inside your team's general project settings from the dashboard. - - If you're using a Hobby Plan, you can use your username. Your username can be found in your [Vercel Personal Account Settings](https://vercel.com/account) - -![Vercel Account Slug](/images/docs/vercel-slug.png) - -4. CircleCI automatically loads environment variables stored in project settings into the CI environment. No modifications are necessary for the CI file. diff --git a/docs/pages/repo/docs/ci/github-actions.mdx b/docs/pages/repo/docs/ci/github-actions.mdx deleted file mode 100644 index 3b69a94..0000000 --- a/docs/pages/repo/docs/ci/github-actions.mdx +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: Using Turborepo with GitHub Actions -description: How to use GitHub Actions with Turborepo to optimize your CI workflow ---- - -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Using Turborepo with GitHub Actions - -The following example shows how to use Turborepo with [GitHub Actions](https://github.com/features/actions). - -For a given root `package.json`: - -```json -{ - "name": "my-turborepo", - "scripts": { - "build": "turbo run build", - "test": "turbo run test" - }, - "devDependencies": { - "turbo": "1.2.5" - } -} -``` - -And a `turbo.json`: - -```json -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**"], - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["^build"] - } - }, -} -``` - -Create file called `.github/workflows/ci.yml` in your repository with the following contents: - - - - ```yaml - name: CI - - on: - push: - branches: ["main"] - pull_request: - types: [opened, synchronize] - - jobs: - build: - name: Build and Test - timeout-minutes: 15 - runs-on: ubuntu-latest - # To use Remote Caching, uncomment the next lines and follow the steps below. - # env: - # TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} - # TURBO_TEAM: ${{ secrets.TURBO_TEAM }} - # TURBO_REMOTE_ONLY: true - - steps: - - name: Check out code - uses: actions/checkout@v3 - with: - fetch-depth: 2 - - - name: Setup Node.js environment - uses: actions/setup-node@v3 - with: - node-version: 16 - cache: 'npm' - - - name: Install dependencies - run: npm install - - - name: Build - run: npm run build - - - name: Test - run: npm run test - ``` - - - - ```yaml - name: CI - - on: - push: - branches: ["main"] - pull_request: - types: [opened, synchronize] - - jobs: - build: - name: Build and Test - timeout-minutes: 15 - runs-on: ubuntu-latest - # To use Remote Caching, uncomment the next lines and follow the steps below. - # env: - # TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} - # TURBO_TEAM: ${{ secrets.TURBO_TEAM }} - - steps: - - name: Check out code - uses: actions/checkout@v3 - with: - fetch-depth: 2 - - - name: Setup Node.js environment - uses: actions/setup-node@v3 - with: - node-version: 16 - cache: 'yarn' - - - name: Install dependencies - run: yarn - - - name: Build - run: yarn build - - - name: Test - run: yarn test - ``` - - - - ```yaml - name: CI - - on: - push: - branches: ["main"] - pull_request: - types: [opened, synchronize] - - jobs: - build: - name: Build and Test - timeout-minutes: 15 - runs-on: ubuntu-latest - # To use Remote Caching, uncomment the next lines and follow the steps below. - # env: - # TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} - # TURBO_TEAM: ${{ secrets.TURBO_TEAM }} - - steps: - - name: Check out code - uses: actions/checkout@v3 - with: - fetch-depth: 2 - - - uses: pnpm/action-setup@v2.0.1 - with: - version: 6.32.2 - - - name: Setup Node.js environment - uses: actions/setup-node@v3 - with: - node-version: 16 - cache: 'pnpm' - - - name: Install dependencies - run: pnpm install - - - name: Build - run: pnpm build - - - name: Test - run: pnpm test - ``` - - - - -## Remote Caching - -To use Remote Caching with GitHub Actions, add the following environment variables to your GitHub Actions workflow -to make them available to your `turbo` commands. - -- `TURBO_TOKEN` - The Bearer token to access the Remote Cache -- `TURBO_TEAM` - The account to which the monorepo belongs - -To use Vercel Remote Caching, you can get the value of these variables in a few steps: - -1. Create a Scoped Access Token to your account in the [Vercel Dashboard](https://vercel.com/account/tokens) - -![Vercel Access Tokens](/images/docs/vercel-create-token.png) - -Copy the value to a safe place. You'll need it in a moment. - -2. Go to your GitHub repository settings and click on the **Secrets** and then **Actions** tab. Create a new secret called `TURBO_TOKEN` and enter the value of your Scoped Access Token. - -![GitHub Secrets](/images/docs/github-actions-secrets.png) -![GitHub Secrets Create](/images/docs/github-actions-create-secret.png) - -3. Make a second secret called `TURBO_TEAM` and enter the value of your team's Vercel URL _without_ the `vercel.com/`. Your Team URL can be found inside your team's general project settings from the dashboard. - - If you're using a Hobby Plan, you can use your username. Your username can be found in your [Vercel Personal Account Settings](https://vercel.com/account) - -![Vercel Account Slug](/images/docs/vercel-slug.png) - -4. At the top of your GitHub Actions workflow, provide the following environment variables to jobs that use `turbo`: - -```yaml highlight="6-8" -# ... - -jobs: - build: - name: Build and Test - timeout-minutes: 15 - runs-on: ubuntu-latest - # To use Turborepo Remote Caching, set the following environment variables for the job. - env: - TURBO_TOKEN: ${{ secrets.TURBO_TOKEN }} - TURBO_TEAM: ${{ secrets.TURBO_TEAM }} - - steps: - - name: Check out code - uses: actions/checkout@v3 - with: - fetch-depth: 2 - # ... -``` diff --git a/docs/pages/repo/docs/ci/gitlabci.mdx b/docs/pages/repo/docs/ci/gitlabci.mdx deleted file mode 100644 index f8321d0..0000000 --- a/docs/pages/repo/docs/ci/gitlabci.mdx +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Using Turborepo with GitLab CI -description: How to use GitLab CI with Turborepo to optimize your CI workflow ---- - -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Using Turborepo with GitLab CI - -The following example shows how to use Turborepo with [GitLab CI](https://docs.gitlab.com/ee/ci/). - -For a given root `package.json`: - -```json -{ - "name": "my-turborepo", - "scripts": { - "build": "turbo run build", - "test": "turbo run test" - }, - "devDependencies": { - "turbo": "1.2.5" - } -} -``` - -And a `turbo.json`: - -```json -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "outputs": [".svelte-kit/**"], - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["^build"] - }, - } -} -``` - -Create a file called `.gitlab-ci.yml` in your repository with the following contents: - - - - ```yaml - image: node:latest - # To use Remote Caching, uncomment the next lines and follow the steps below. - # variables: - # TURBO_TOKEN: $TURBO_TOKEN - # TURBO_TEAM: $TURBO_TEAM - stages: - - build - build: - stage: build - script: - - npm install - - npm run build - - npm run test - ``` - - - ```yaml - image: node:latest - # To use Remote Caching, uncomment the next lines and follow the steps below. - # variables: - # TURBO_TOKEN: $TURBO_TOKEN - # TURBO_TEAM: $TURBO_TEAM - stages: - - build - build: - stage: build - script: - - yarn install - - yarn build - - yarn test - cache: - paths: - - node_modules/ - - .yarn - ``` - - - ```yaml - image: node:latest - # To use Remote Caching, uncomment the next lines and follow the steps below. - # variables: - # TURBO_TOKEN: $TURBO_TOKEN - # TURBO_TEAM: $TURBO_TEAM - stages: - - build - build: - stage: build - before_script: - - curl -f https://get.pnpm.io/v6.16.js | node - add --global pnpm@6.32.2 - - pnpm config set store-dir .pnpm-store - script: - - pnpm install - - pnpm build - - pnpm test - cache: - key: "$CI_COMMIT_REF_SLUG" - paths: - - .pnpm-store - ``` - > For more information visit the pnpm documentation section on GitLab CI integration, view it [here](https://pnpm.io/continuous-integration#gitlab) - - - -## Remote Caching - -To use Remote Caching with GitLab CI, add the following environment variables to your GitLab CI project. - -- `TURBO_TOKEN` - The Bearer token to access the Remote Cache -- `TURBO_TEAM` - The account to which the monorepo belongs - -To use Vercel Remote Caching, you can get the value of these variables in a few steps: - -1. Create a Scoped Access Token to your account in the [Vercel Dashboard](https://vercel.com/account/tokens) - -![Vercel Access Tokens](/images/docs/vercel-create-token.png) - -Copy the value to a safe place. You'll need it in a moment. - -2. Go to your GitLab repository settings and click on the **Settings** and then **CI/CD** tab. Create a new variable called `TURBO_TOKEN` and enter the value of your Scoped Access Token. - -![GitLab CI Variables](/images/docs/gitlab-ci-variables.png) -![GitLab CI Create Variable](/images/docs/gitlab-ci-create-variable.png) - -3. Make a second secret called `TURBO_TEAM` and enter the value of your team's Vercel URL _without_ the `vercel.com/`. Your Team URL can be found inside your team's general project settings from the dashboard. - - If you're using a Hobby Plan, you can use your username. Your username can be found in your [Vercel Personal Account Settings](https://vercel.com/account) - -![Vercel Account Slug](/images/docs/vercel-slug.png) diff --git a/docs/pages/repo/docs/ci/travisci.mdx b/docs/pages/repo/docs/ci/travisci.mdx deleted file mode 100644 index 29a09e5..0000000 --- a/docs/pages/repo/docs/ci/travisci.mdx +++ /dev/null @@ -1,122 +0,0 @@ ---- -title: Using Turborepo with Travis CI -description: How to use Travis CI with Turborepo to optimize your CI workflow ---- - -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Using Turborepo with Travis CI - -The following example shows how to use Turborepo with [Travis CI](https://www.travis-ci.com/). - -For a given root `package.json`: - -```json -{ - "name": "my-turborepo", - "scripts": { - "build": "turbo run build", - "test": "turbo run test" - }, - "devDependencies": { - "turbo": "1.2.5" - } -} -``` - -And a `turbo.json`: - -```json -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "outputs": [".svelte-kit/**"], - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["^build"] - }, - } -} -``` - -Create a file called `.travis.yml` in your repository with the following contents: - - - - ```yaml - language: node_js - node_js: - - lts/* - install: - - npm install - script: - - npm run build - script: - - npm run test - ``` - - - Travis CI detects the use of Yarn by the presence of `yarn.lock`. It will automatically ensure it is installed. - ```yaml - language: node_js - node_js: - - lts/* - install: - - yarn - script: - - yarn build - script: - - yarn test - ``` - - - ```yaml - language: node_js - node_js: - - lts/* - cache: - npm: false - directories: - - "~/.pnpm-store" - before_install: - - curl -f https://get.pnpm.io/v6.16.js | node - add --global pnpm@6.32.2 - - pnpm config set store-dir ~/.pnpm-store - install: - - pnpm install - script: - - pnpm build - script: - - pnpm test - ``` - > For more information visit the pnpm documentation section on Travis CI integration, view it [here](https://pnpm.io/continuous-integration#travis) - - - -## Remote Caching - -To use Remote Caching with Travis CI, add the following environment variables to your Travis CI project. - -- `TURBO_TOKEN` - The Bearer token to access the Remote Cache -- `TURBO_TEAM` - The account to which the monorepo belongs - -To use Vercel Remote Caching, you can get the value of these variables in a few steps: - -1. Create a Scoped Access Token to your account in the [Vercel Dashboard](https://vercel.com/account/tokens) - -![Vercel Access Tokens](/images/docs/vercel-create-token.png) - -Copy the value to a safe place. You'll need it in a moment. - -2. Go to your Travis repository settings and scroll down to the _Environment Variables_ section. Create a new variable called `TURBO_TOKEN` and enter the value of your Scoped Access Token. - -![Travis CI Variables](/images/docs/travis-ci-environment-variables.png) - -3. Make a second secret called `TURBO_TEAM` and enter the value of your team's Vercel URL _without_ the `vercel.com/`. Your Team URL can be found inside your team's general project settings from the dashboard. - - If you're using a Hobby Plan, you can use your username. Your username can be found in your [Vercel Personal Account Settings](https://vercel.com/account) - -![Vercel Account Slug](/images/docs/vercel-slug.png) - -4. Travis CI automatically loads environment variables stored in project settings into the CI environment. No modifications are necessary for the CI file. diff --git a/docs/pages/repo/docs/core-concepts/_meta.json b/docs/pages/repo/docs/core-concepts/_meta.json deleted file mode 100644 index 92e93f2..0000000 --- a/docs/pages/repo/docs/core-concepts/_meta.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "caching": "Caching Tasks", - "remote-caching": "Remote Caching", - "monorepos": "Monorepos", - "scopes": { - "display": "hidden" - } -} diff --git a/docs/pages/repo/docs/core-concepts/caching.mdx b/docs/pages/repo/docs/core-concepts/caching.mdx deleted file mode 100644 index b815977..0000000 --- a/docs/pages/repo/docs/core-concepts/caching.mdx +++ /dev/null @@ -1,460 +0,0 @@ ---- -title: Caching -description: Caching allows Turborepo to skip work that's already been done, for the fastest builds. ---- - -import Callout from "../../../../components/Callout"; - -# Caching Tasks - -Every JavaScript or TypeScript codebase will need to run `package.json` scripts, like `build`, `test` and `lint`. In Turborepo, we call these **tasks**. - -Turborepo can cache the results and logs of your tasks - leading to enormous speedups for slow tasks. - -## Missing the cache - -Each task in your codebase has **inputs** and **outputs**. - -- A `build` task might have source files as inputs and outputs logs to `stderr` and `stdout` as well as bundled files. -- A `lint` or `test` task might have source files as inputs and outputs logs to `stdout` and `stderr`. - -Let's say you run a `build` task with Turborepo using `turbo run build`: - -![](/images/docs/cache-miss.png) - -1. Turborepo will **evaluate the inputs to your task** (by default all non-git-ignored files in the workspace folder) and **turn them into a hash** (e.g. `78awdk123`). - -2. **Check the local filesystem cache** for a folder named with the hash (e.g.`./node_modules/.cache/turbo/78awdk123`). - -3. If Turborepo doesn't find any matching artifacts for the calculated hash, Turborepo will then **execute the task**. - -4. Once the task is over, Turborepo **saves all the outputs** (including files and logs) into its cache under the hash. - - - Turborepo takes a lot of information into account when creating the hash - - source files, environment variables, and even the source files of dependent - workspaces. Learn more [below](/repo/docs/core-concepts/caching#hashing). - - -## Hitting the cache - -Let's say that you run the task again without changing any of its inputs: - -![](/images/docs/cache-hit.png) - -1. The **hash will be the same** because **the inputs haven't changed** (e.g. `78awdk123`) - -2. Turborepo will find the folder in its cache with the calculated hash (e.g. `./node_modules/.cache/turbo/78awdk123`) - -3. **Instead of running the task**, Turborepo will **replay the output** - printing the saved logs to `stdout` and restoring the saved output files to their respective position in the filesystem. - -Restoring files and logs from the cache happens near-instantaneously. This can take your build times from minutes or hours down to seconds or milliseconds. Although specific results will vary depending on the shape and granularity of your codebase's dependency graph, most teams find that they can cut their overall monthly build time by around 40-85% with Turborepo's caching. - -## Configuring Cache Outputs - -Using [`pipeline`](/repo/docs/reference/configuration#pipeline), you can configure cache conventions across your Turborepo. - -To override the default cache output behavior, pass an array of globs to a [`pipeline..outputs`](/repo/docs/reference/configuration#outputs) array. Any file that satisfies the glob patterns for a task will be treated as artifact. - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**"], - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["build"] - } - } -} -``` - -If your task does not emit any files (e.g. unit tests with Jest) you can omit `outputs`. Even without any file outputs, Turborepo automatically records and caches the logs of every task. If no inputs change (i.e. if there is a cache hit), subsequent runs will replay these logs. - -When you run `turbo run build test`, Turborepo will execute your build and test scripts, -and cache their `output`s in `./node_modules/.cache/turbo`. - - - Pro Tip for caching ESLint: You can get a cacheable pretty terminal output - (even for non-errors) by setting `TIMING=1` variable before `eslint`. Learn - more over in the [ESLint - docs](https://eslint.org/docs/latest/developer-guide/working-with-rules#per-rule-performance). - - -## Configuring Cache Inputs - -A workspace is considered to have been updated when any of the files in that workspace have changed. -However, for some tasks, we only want to rerun that task when relevant files have changed. -Specifying `inputs` lets us define which files are relevant for a particular task. For example, the -`test` configuration below declares that the `test` task only needs to execute if a `.tsx` or `.ts` file -in the `src/` and `test/` subdirectories has changed since the last execution. - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - // ... omitted for brevity - - "test": { - // A workspace's `test` task depends on that workspace's - // own `build` task being completed first. - "dependsOn": ["build"], - // A workspace's `test` task should only be rerun when - // either a `.tsx` or `.ts` file has changed. - "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"] - } - } -} -``` - -## Turn off caching - -Sometimes you really don't want to write the cache output (e.g. when you're using [`next dev`](https://nextjs.org/docs/api-reference/cli#development) or `react-scripts start` for live reloading). To disable cache writes, append `--no-cache` to any command: - -```shell -# Run `dev` npm script in all workspaces in parallel, -# but don't cache the output -turbo run dev --no-cache -``` - -Note that `--no-cache` disables cache writes but does not disable cache reads. If you want to disable cache reads, use the `--force` flag. - -You can also disable caching on specific tasks by setting the [`pipeline..cache`](/repo/docs/reference/configuration#cache) configuration to `false`: - -```json -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "dev": { - "cache": false, - "persistent": true - } - } -} -``` - -## Alter Caching Based on File Changes - -For some tasks, you may not want a cache miss if an irrelevant file has changed. For instance, updating `README.md` -might not need to trigger a cache miss for the `test` task. You can use `inputs` to restrict the set -of files `turbo` considers for a particular task. In this case, only consider `.ts` and `.tsx` files relevant for -determining a cache hit on the `test` task: - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - // ...other tasks - "test": { - "dependsOn": ["build"], - "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"] - } - } -} -``` - - - `package.json` is *always* considered an input for tasks in the workspace it - lives in. This is because the *definition* of the task itself lives in - `package.json` in the `scripts` key. If you change that, any cached output is - considered invalid. - - -If you want _all_ tasks to depend on certain files, you can declare this dependency in the -`globalDependencies` array. - -```diff -{ - "$schema": "https://turbo.build/schema.json", -+ "globalDependencies": [".env"], - "pipeline": { - // ...other tasks - "test": { - "dependsOn": ["build"], - "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"] - } - } -} -``` - - - `turbo.json` is *always* considered a global dependency. If you modify - `turbo.json`, all caches are invalidated. - - -## Altering Caching Based on Environment Variables - -When you use `turbo` with tools that inline environment variables at build time -(e.g. [Next.js][1] or [Create React App][2]), it is important to tell `turbo` about it. -Otherwise, you could ship a cached build with the wrong environment variables! - -You can control `turbo`'s caching behavior based on -the values of environment variables: - -- Including environment variables in the `env` key in your `pipeline` definition will impact the cache fingerprint on a per-task or per-workspace-task basis. -- The value of any environment variable that includes `THASH` in its name will impact the cache fingerprint of _all_ tasks. - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"], - // env vars will impact hashes of all "build" tasks - "env": ["SOME_ENV_VAR"], - "outputs": ["dist/**"] - }, - - // override settings for the "build" task for the "web" app - "web#build": { - "dependsOn": ["^build"], - "env": [ - // env vars that will impact the hash of "build" task for only "web" app - "STRIPE_SECRET_KEY", - "NEXT_PUBLIC_STRIPE_PUBLIC_KEY", - "NEXT_PUBLIC_ANALYTICS_ID" - ], - "outputs": [".next/**", "!.next/cache/**"] - } - } -} -``` - - - Declaring environment variables in the `dependsOn` config with a `$` prefix is - deprecated. - - -To alter the cache for _all_ tasks, you can declare environment variables in the -`globalEnv` array: - -```diff -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"], - // env vars will impact hashes of all "build" tasks - "env": ["SOME_ENV_VAR"], - "outputs": ["dist/**"] - }, - - // override settings for the "build" task for the "web" app - "web#build": { - "dependsOn": ["^build"], - "env": [ - // env vars that will impact the hash of "build" task for only "web" app - "STRIPE_SECRET_KEY", - "NEXT_PUBLIC_STRIPE_PUBLIC_KEY", - "NEXT_PUBLIC_ANALYTICS_ID" - ], - "outputs": [".next/**", "!.next/cache/**"], - }, - }, -+ "globalEnv": [ -+ "GITHUB_TOKEN" // env var that will impact the hashes of all tasks, -+ ] -} -``` - -### Automatic environment variable inclusion - -To help ensure correct caching across environments, Turborepo automatically infers and includes public environment variables when calculating cache keys for apps built with detected frameworks. You can safely omit framework-specific public environment variables from `turbo.json`: - -```diff filename="turbo.json" -{ - "pipeline": { - "build": { - "env": [ -- "NEXT_PUBLIC_EXAMPLE_ENV_VAR" - ] - } - } -} -``` - -Note that this automatic detection and inclusion only works if Turborepo successfully infers the framework your apps are built with. The supported frameworks and the environment variables that Turborepo will detect and include in the cache keys: - -- Astro: `PUBLIC_*` -- Blitz: `NEXT_PUBLIC_*` -- Create React App: `REACT_APP_*` -- Gatsby: `GATSBY_*` -- Next.js: `NEXT_PUBLIC_*` -- Nuxt.js: `NUXT_ENV_*` -- RedwoodJS: `REDWOOD_ENV_*` -- Sanity Studio: `SANITY_STUDIO_*` -- Solid: `VITE_*` -- SvelteKit: `VITE_*` -- Vite: `VITE_*` -- Vue: `VUE_APP_*` - - - There are some exceptions to the list above. For various reasons, CI systems (including Vercel) - set environment variables that start with these prefixes even though they aren't part of your build - output. These can change unpredictably — even on every build! — invalidating Turborepo's - cache. To workaround this, Turborepo uses a `TURBO_CI_VENDOR_ENV_KEY` variable to - _exclude_ environment variables from Turborepo's inference. - -For example, Vercel sets the `NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA`. This value changes on every build, -so Vercel _also_ sets `TURBO_CI_VENDOR_ENV_KEY="NEXT_PUBLIC_VERCEL_"` to exclude these variables. - -Luckily, you only need to be aware of this on other build systems; you don't need to worry -about these edge cases when using Turborepo on Vercel. - - - -#### A note on monorepos - -The environment variables will only be included in the cache key for tasks in workspaces where that framework is used. In other words, environment variables inferred for Next.js apps will only be included in the cache key for workspaces detected as Next.js apps. Tasks in other workspaces in the monorepo will not be impacted. - -For example, consider a monorepo with three workspaces: a Next.js project, a Create React App project, and a TypeScript package. Each has a `build` script, and both apps depend on the TypeScript project. Let's say that this Turborepo has a standard `turbo.json` pipeline that builds them all in order: - -```jsonc filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**", "dist/**"], - "dependsOn": ["^build"] - } - } -} -``` - -As of 1.4, when you run `turbo run build`, Turborepo will not consider any build time environment variables relevant when building the TypeScript package. However, when building the Next.js app, Turborepo will infer that environment variables starting with `NEXT_PUBLIC_` could alter the output of the `.next` folder and should thus be included when calculating the hash. Similarly, when calculating the hash of the Create React App's `build` script, all build time environment variables starting with `REACT_APP_PUBLIC_` will be included. - -### `eslint-config-turbo` - -To further assist in detecting unseen dependencies creeping into your builds, and to help ensure that your Turborepo cache is correctly shared across every environment, use the [`eslint-config-turbo`](https://www.npmjs.com/package/eslint-config-turbo) package. While automatic environment variable inclusion should cover most situations with most frameworks, this ESLint config will provide just-in-time feedback for teams using other build time inlined environment variables. This will also help support teams using in-house frameworks that we cannot detect automatically. - -To get started, extend from `eslint-config-turbo` in your root [`eslintrc`](https://eslint.org/docs/latest/user-guide/configuring/configuration-files#configuration-file-formats) file: - -```jsonc -{ - // Automatically flag env vars missing from turbo.json - "extends": ["turbo"] -} -``` - -For more control over the rules, you can install and configure the [`eslint-plugin-turbo`](https://www.npmjs.com/package/eslint-plugin-turbo) _plugin_ directly by first adding it to plugins and then configuring the desired rules: - -```jsonc -{ - "plugins": ["turbo"], - "rules": { - // Automatically flag env vars missing from turbo.json - "turbo/no-undeclared-env-vars": "error" - } -} -``` - -The plugin will warn you if you are using non-framework-related environment variables in your code that have not been declared in your `turbo.json`. - -### Invisible Environment Variables - -Since Turborepo runs _before_ your tasks, it is possible for your tasks to create or mutate environment -variables after `turbo` has already calculated the hash for a particular task. For example, consider this `package.json`: - -```json -{ - "scripts": { - "build": "NEXT_PUBLIC_GA_ID=UA-00000000-0 next build" - } -} -``` - -`turbo`, having calculated a task hash prior to executing the `build` script, will be unable to discover -the `NEXT_PUBLIC_GA_ID` environment variable, and thus unable to partition the cache based -on its value. Be careful to ensure that all of your environment variables are configured prior to -invoking `turbo`! - -```jsonc -{ - "$schema": "https://turborepo.org/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"], - "env": ["SOME_ENV_VAR"], - "outputs": [".next/**", "!.next/cache/**"], - }, - } -} -``` - -### Using dotenv - -Frameworks commonly use [dotenv][3] to automatically load environment variables when the dev server -starts or when creating a build. This makes it hard for Turborepo to understand the environment of your task by default: - -- dotenv stores environment variables in a _file_ rather than in the environment -- this file is loaded _after_ Turborepo has already started execution of the task -- sometimes the file is git-ignored, so even if `inputs` are not specified, Turborepo won't be able to detect changes - -To ensure you end up with the correct caching behavior for your task, add these `.env` files to the `globalDependencies` key: - -```diff -{ - "$schema": "https://turborepo.org/schema.json", -+ "globalDependencies": ["**/.env.*local"], - "pipeline": { - "build": { - "dependsOn": ["^build"], - "env": ["SOME_ENV_VAR"], - "outputs": [".next/**", "!.next/cache/**"], - }, - } -} -``` - -Alternatively, you can add specific environment variables to the `inputs` key for specific tasks. - -## Force overwrite cache - -Conversely, if you want to disable reading the cache and force `turbo` to re-execute a previously cached task, add the `--force` flag: - -```shell -# Run `build` npm script in all workspaces, -# ignoring cache hits. -turbo run build --force -``` - -Note that `--force` disables cache reads but does not disable cache writes. If you want to disable cache writes, use the `--no-cache` flag. - -## Logs - -Not only does `turbo` cache the output of your tasks, it also records the terminal output (i.e. combined `stdout` and `stderr`) to (`/.turbo/run-.log`). When `turbo` encounters a cached task, it will replay the output as if it happened again, but instantly, with the package name slightly dimmed. - -## Hashing - -By now, you're probably wondering how `turbo` decides what constitutes a cache hit vs. miss for a given task. Good question! - -First, `turbo` constructs a hash of the current global state of the codebase: - -- The contents of any files that satisfy the glob patterns and any the values of environment variables listed in [`globalDependencies`](/repo/docs/reference/configuration#globalDependencies) -- The sorted list environment variable key-value pairs that include `THASH` _anywhere_ in their names (e.g. `STRIPE_PUBLIC_THASH_SECRET_KEY`, but not `STRIPE_PUBLIC_KEY`) - -Then it adds more factors relevant to a given workspace's task: - -- Hash the contents of all version-controlled files in the workspace folder or the files matching the `inputs` globs, if present -- The hashes of all internal dependencies -- The `outputs` option specified in the [`pipeline`](/repo/docs/reference/configuration#pipeline) -- The set of resolved versions of all installed `dependencies`, `devDependencies`, and `optionalDependencies` specified in a workspace's `package.json` from the root lockfile -- The workspace task's name -- The sorted list of environment variable key-value pairs that correspond to the environment variable names listed in applicable [`pipeline..dependsOn`](/repo/docs/reference/configuration#dependson) list. - -Once `turbo` encounters a given workspace's task in its execution, it checks the cache (both locally and remotely) for a matching hash. If it's a match, it skips executing that task, moves or downloads the cached output into place and replays the previously recorded logs instantly. If there isn't anything in the cache (either locally or remotely) that matches the calculated hash, `turbo` will execute the task locally and then cache the specified `outputs` using the hash as an index. - -The hash of a given task is injected at execution time as an environment variable `TURBO_HASH`. This value can be useful in stamping outputs or tagging Dockerfile etc. - - - As of `turbo` v0.6.10, `turbo`'s hashing algorithm when using `npm` or `pnpm` - differs slightly from the above. When using either of these package managers, - `turbo` will include the hashed contents of the lockfile in its hash algorithm - for each workspace's task. It will _not_ parse/figure out the resolved set of - all dependencies like the current `yarn` implementation. - - -[1]: https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser -[2]: https://create-react-app.dev/docs/adding-custom-environment-variables/ -[3]: https://github.com/motdotla/dotenv diff --git a/docs/pages/repo/docs/core-concepts/monorepos.mdx b/docs/pages/repo/docs/core-concepts/monorepos.mdx deleted file mode 100644 index d245469..0000000 --- a/docs/pages/repo/docs/core-concepts/monorepos.mdx +++ /dev/null @@ -1,23 +0,0 @@ -# Turborepo in Monorepos - -## The problem - -![](/images/docs/why-turborepo-problem.png) - -Monorepos have many advantages - but **they struggle to scale**. Each workspace has its own test suite, its own linting and its own build process. A single monorepo might have **hundreds of tasks to execute**. - -## The solution - -![](/images/docs/why-turborepo-solution.png) - -**Turborepo solves your monorepo's scaling problem**. Our remote cache stores the result of all your tasks, meaning that **your CI never needs to do the same work twice**. - -Task scheduling can be difficult in a monorepo. Imagine `yarn build` needs to run before `yarn test`, across all your workspaces. Turborepo **can schedule your tasks for maximum speed**, across all available cores. - -Turborepo can be **adopted incrementally**. It uses the `package.json` scripts you've already written, the dependencies you've already declared, and a single `turbo.json` file. You can **use it with any package manager**, like `npm`, `yarn` or `pnpm`. You can add it to any monorepo in just a few minutes. - -## What turborepo is not - -Turborepo **doesn't handle [package installation](/repo/docs/handbook/package-installation)**. Tools like `npm`, `pnpm` or `yarn` already do that brilliantly. But they run tasks inefficiently, meaning slow CI builds. - -We recommend that **Turborepo runs your tasks**, and your favorite package manager installs your packages. diff --git a/docs/pages/repo/docs/core-concepts/monorepos/_meta.json b/docs/pages/repo/docs/core-concepts/monorepos/_meta.json deleted file mode 100644 index d66bf5d..0000000 --- a/docs/pages/repo/docs/core-concepts/monorepos/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "running-tasks": "Running Tasks", - "filtering": "Filtering Workspaces", - "skipping-tasks": "Skipping Tasks in CI" -} diff --git a/docs/pages/repo/docs/core-concepts/monorepos/configuring-workspaces.mdx b/docs/pages/repo/docs/core-concepts/monorepos/configuring-workspaces.mdx deleted file mode 100644 index f205e64..0000000 --- a/docs/pages/repo/docs/core-concepts/monorepos/configuring-workspaces.mdx +++ /dev/null @@ -1,267 +0,0 @@ ---- -title: Configuring Workspaces -description: Turborepo lets you configure each workspace ---- - -import Callout from "../../../../../components/Callout"; - -# Configuring Workspaces - -Most monorepos can declare a `turbo.json` in the root directory with a uniform -[pipeline][2] that apply to all workspaces. Sometimes, a monorepo can contain -workspaces that need to configure their tasks differently. To accommodate this, -starting in version 1.8, Turborepo enables you to extend the root configuration -with a `turbo.json` in any workspace. This flexibility enables a more diverse -set of apps and packages to co-exist, and allows workspace owners to maintain -specialized tasks and configuration without affecting other apps and packages of -the monorepo. - -## How it Works - -To override the configuration for any task defined in the root `turbo.json`, add -a `turbo.json` file in any workspace of your monorepo with a top-level `extends` -key: - -```jsonc filename="apps/my-app/turbo.json" -{ - "extends": ["//"], - "pipeline": { - "build": { - // custom configuration for the build task in this workspace - }, - // new tasks only available in this workspace - "special-task": {}, - } -} -``` - - - For now, the only valid value for the `extends` key is `["//"]`. -`//` is a special name used to identify the root directory of the monorepo. - - -Configuration in a workspace can override any of [the configurations for a -pipeline task][2]. If you don't include a key, the configuration is inherited -from the extended `turbo.json`. - -## Examples - -To illustrate, let's look at some use cases. - -### Different Frameworks - -Let's say your monorepo has multiple [Next.js][5] apps, and one [SvelteKit][6] -app. Both frameworks create their build output with a `build` script in their -respective `package.json`s. You _could_ configure Turborepo to run these tasks -with a single `turbo.json` at the root like this: - -```jsonc filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"], - } - } -} -``` - -Notice that both `.next/**` and `.svelte-kit/**` need to be specified as -[`outputs`][7], even though Next.js apps do not generate a `.svelte-kit` directory, and -vice versa. With Workspace Configurations, you can instead add custom -configuration in the SvelteKit workspace in `apps/my-svelte-kit-app/turbo.json`: - -```jsonc filename="apps/my-svelte-kit-app/turbo.json" -{ - "extends": ["//"], - "pipeline": { - "build": { - "outputs": [".svelte-kit/**"] - } - } -} -``` - -and remove the config from the root configuration: - -```diff filename="turbo.json" -{ - "pipeline": { - "build": { -- "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"] -+ "outputs": [".next/**", "!.next/cache/**"] - } - } -} -``` - -This not only makes each configuration easier to read, it puts the configuration -closer to where it is used. - -### Specialized Tasks - -In another example, say that the `build` task in one workspace `dependsOn` a -`compile` task. You could universally declare it as `dependsOn: ["compile"]`. -This means that your root `turbo.json` has to have an empty `compile` task -entry: - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "dependsOn": ["compile"] - }, - "compile": {} - } -} -``` - -With Workspace Configurations, you can move that `compile` task into the -`apps/my-custom-app/turbo.json`, - -```json filename="apps/my-app/turbo.json" -{ - "extends": ["//"], - "pipeline": { - "build": { - "dependsOn": ["compile"] - }, - "compile": {} - } -} -``` - -and remove it from the root: - -```diff filename="turbo.json" -{ - "pipeline": { -+ "build": {} -- "build": { -- "dependsOn": ["compile"] -- }, -- "compile": {} - } -} -``` - -Now, the owners of `my-app`, can have full ownership over their `build` task, -but continue to inherit any other tasks defined at the root. - -## Comparison to Workspace-specific tasks - -At first glance, Workspace Configurations may sound a lot like the -[`workspace#task` syntax][3] in the root `turbo.json`. The features are -similar, but have one significant difference: when you declare a Workspace-specific -in the root `turbo.json`, it _completely_ overwrites the baseline task -configuration. With a Workspace Configuration, the task configuration is merged -instead. - -Consider the example of the monorepo with multiple Next.js apps and a Sveltekit -app again. Without a Workspace-specific task, you might configure your root -`turbo.json` like this: - -```jsonc filename="turbo.json" -{ - "pipeline": { - "build": { - "outputMode": "hash-only", - "inputs": ["src/**"], - "outputs": [".next/**", "!.next/cache/**"], - }, - "my-sveltekit-app#build": { - "outputMode": "hash-only", // must duplicate this - "inputs": ["src/**"], // must duplicate this - "outputs": [".svelte-kit/**"] - } - } -} -``` - -In this example, `my-sveltekit-app#build` completely overwrites `build` for the -Sveltekit app, so `outputMode` and `inputs` also need to be duplicated. - -With Workspace Configurations, `outputMode` and `inputs` are inherited, so -you don't need to duplicate them. You only need to override `outputs` -`my-sveltekit-app` config. - - - Although there are no plans to remove Workspace-specific task configurations, - we expect that Workspace Configurations can be used for most use cases instead. - - -## Limitations - -Although the general idea is the same as the root `turbo.json`, Workspace -Configurations come with a set of guardrails that can prevent workspaces from creating -confusing situations. These guardrails are listed here to make it clear that -they are intentional, rather than accidental: - -- Workspace Configurations cannot use [the `workspace#task` syntax][3] as pipeline entries - - The `workspace` is inferred based on the _location_ of the config, and it is - not possible to change configuration for another workspace. For example, in a - Workspace Configuration for 'my-nextjs-app': - - ```jsonc filename="apps/my-nextjs-app/turbo.json" - { - "pipeline": { - "my-nextjs-app#build": { - // ❌ This is not allowed. Even though it's - // referencing the correct workspace, "my-nextjs-app" - // is inferred, and we don't need to specify it again. - // This syntax also has different behavior, so we do not want to allow it. - // (see "Comparison to Workspace-specific tasks" section) - }, - "my-sveltekit-app#build": { - // ❌ Changing configuration for the "my-sveltekit-app" workspace - // from Workspace Configuraton in "my-nextjs-app" is not allowed. - }, - "build": { - // ✅ just use the task name! - }, - } - } - ``` - - Note that the `build` task can still depend on a Workspace-specific task: - - ```jsonc filename="apps/my-nextjs-app/turbo.json" - { - "pipeline": { - "build": { - // ✅ It's still ok to have workspace#task in dependsOn! - "dependsOn": ["some-pkg#compile"] - }, - } - } - ``` - -- Workspace Configurations cannot override anything outside the `pipeline` key. - - For example, it is not possible to override `globalEnv` or - `globalDependencies`. We expect that monorepo owners should control this - absolutely, and if this config is not _truly_ global, it should not be - configured that way. - -- Root turbo.json cannot use the `extends` key. - - To avoid creating circular dependencies on workspaces, the root `turbo.json` - cannot extend from anything. - -If you have a use case for any of these, please [file an issue][4]! - -## Troubleshooting - -In large monorepos, it can sometimes be difficult to understand how Turborepo is -interpreting your configuration. To help, we've added a `resolvedTaskDefinition` -to the Dry Run output. If you run `turbo run build --dry-run`, for example, the -output will include the combination of all `turbo.json` configurations that were -considered before running the `build` task. - -[1]: /repo/docs/core-concepts/monorepos/running-tasks#running-tasks-from-the-root -[2]: /repo/docs/reference/configuration#pipeline -[3]: /repo/docs/core-concepts/monorepos/running-tasks#specific-workspace-tasks -[4]: https://github.com/vercel/turbo/issues/new/choose -[5]: https://nextjs.org -[6]: https://kit.svelte.dev/ -[7]: /repo/docs/reference/configuration#outputs diff --git a/docs/pages/repo/docs/core-concepts/monorepos/filtering.mdx b/docs/pages/repo/docs/core-concepts/monorepos/filtering.mdx deleted file mode 100644 index f88d9c8..0000000 --- a/docs/pages/repo/docs/core-concepts/monorepos/filtering.mdx +++ /dev/null @@ -1,208 +0,0 @@ ---- -title: Filtering Workspaces -description: Only build the workspaces you care about. ---- - -import Callout from "../../../../../components/Callout"; -import HeartIcon from "@heroicons/react/solid/HeartIcon"; - -# Filtering Workspaces - -A monorepo can contain hundreds, or thousands, of workspaces. By default, running `turbo run test` from the root of the repository will execute the `test` task in **all available workspaces**. - -![Without using a filter, test will be run across all packages](/images/docs/no-filter.png) - -Turborepo supports a `--filter` flag that lets you **select the workspaces you'd like to execute your task in**. - -![With a filter on shared, only the shared package runs test](/images/docs/with-filter.png) - -You can use it to: - -- Filter by [workspace name](#filter-by-workspace-name) -- Filter by [workspace directory](#filter-by-directory) -- Include [dependents](#include-dependents-of-matched-workspaces) and [dependencies](#include-dependencies-of-matched-workspaces) of matched workspaces -- Execute tasks from the [workspace root](#the-workspace-root) -- Filter by [changes in git history](#filter-by-changed-workspaces) -- [Exclude workspaces](#excluding-workspaces) from selection - -Turborepo will run each task against each matched workspace, ensuring that any tasks which depend on it are run first, according to the `pipeline` specification in [`turbo.json`](/repo/docs/reference/configuration#pipeline). - -## Filter Syntax - -### Multiple filters - -You can specify more than one filter by passing multiple `--filter` flags to the command: - -```sh -turbo build --filter=my-pkg --filter=my-app -``` - -### Filter by workspace name - -When you want to run a script in only one workspace, you can use a single filter: `--filter=my-pkg`. - -```sh -# Build 'my-pkg', letting `turbo` infer task dependencies -# from the pipeline defined in turbo.json -turbo run build --filter=my-pkg - -# Build '@acme/bar', letting `turbo` infer task dependencies -# from the pipeline defined in turbo.json -turbo run build --filter=@acme/bar -``` - -If you want to run tasks inside several workspaces with similar names, you can use glob syntax: `--filter=*my-pkg*`. - -```sh -# Build all workspaces that start with 'admin-', letting turbo infer task -# dependencies from the pipeline defined in turbo.json -turbo run build --filter=admin-* -``` - -#### Scopes - -Some monorepos prepend their workspace names with a scope, such as `@acme/ui` and `@acme/app`. As long as the scope (`@acme`) is unique across the codebase, you may omit it from filters. - -```diff -- turbo run build --filter=@acme/ui -+ turbo run build --filter=ui -``` - -### Include dependents of matched workspaces - -Sometimes, you'll want to ensure that your shared package isn't affecting any downstream dependencies. For that, you can use `--filter=...my-lib`. - -If `my-app` depends on `my-lib`, `...my-lib` will select `my-app` and `my-lib`. - -Including a `^` (`...^my-lib`) will select all of `my-lib`'s dependents, but not `my-lib` itself. - -```sh -# Test 'my-lib' and everything that depends on 'my-lib' -turbo run test --filter=...my-lib - -# Test everything that depends on 'my-lib', but not 'my-lib' itself -turbo run test --filter=...^my-lib -``` - -### Include dependencies of matched workspaces - -Sometimes, you'll want to make sure that `build` is run in all of the dependencies of the lib you're targeting. For that, you can use `--filter=my-app...`. - -If `my-app` depends on `my-lib`, `my-app...` will select `my-app` and `my-lib`. - -Including a `^` (`my-app^...`) will select all of `my-app`'s dependencies, but not `my-app` itself. - -```sh -# Build 'my-app' and its dependencies -turbo run build --filter=my-app... - -# Build 'my-app's dependencies, but not 'my-app' itself -turbo run build --filter=my-app^... -``` - -### Filter by directory - -Useful for when you want to target a specific directory, not a workspace name. It supports: - -- Exact matches: `--filter=./apps/docs` -- Globs: `--filter='./apps/*'` - -```sh -# Build all of the workspaces in the 'apps' directory -turbo run build --filter='./apps/*' -``` - -#### Combining with other syntaxes - -When combining directory filters with other syntaxes, enclose in `{}`. For example: - -```sh -# Build all of the workspaces in the 'libs' directory, -# and all the workspaces that depends on them -turbo run build --filter=...{./libs/*} -``` - -### Filter by changed workspaces - -You can run tasks on any workspaces which have changed since a certain commit. These need to be wrapped in `[]`. - -For example, `--filter=[HEAD^1]` will select all workspaces that have changed in the most recent commit: - -```sh -# Test everything that changed in the last commit -turbo run test --filter=[HEAD^1] -``` - -#### Check a range of commits - -If you need to check a specific range of commits, rather than comparing to `HEAD`, you can set both ends of the comparison via `[...]`. - -```sh -# Test each workspace that changed between 'main' and 'my-feature' -turbo run test --filter=[main...my-feature] -``` - -#### Ignoring changed files - -You can use [`--ignore`](/repo/docs/reference/command-line-reference#--ignore) to specify changed files to be ignored in the calculation of which workspaces have changed. - -#### Combining with other syntaxes - -You can additionally prepend the commit reference with `...` to match the dependencies of other components -against the changed workspaces. For instance, to select `foo` if any of `foo`'s dependencies have changed in the last commit, -you can pass `--filter=foo...[HEAD^1]`. - -```sh -# Build everything that depends on changes in branch 'my-feature' -turbo run build --filter=...[origin/my-feature] - -# Build '@foo/bar' if it or any of its dependencies -# changed in the last commit -turbo run build --filter=@foo/bar...[HEAD^1] -``` - -You can even combine `[]` and `{}` syntax together: - -```sh -# Test each workspace in the '@scope' scope that -# is in the 'packages' directory, if it has -# changed in the last commit -turbo run test --filter=@scope/*{./packages/*}[HEAD^1] -``` - -### The workspace root - -The monorepo's root can be selected using the token `//`. - -```sh -# Run the format script from the root "package.json" file: -turbo run format --filter=// -``` - -### Excluding workspaces - -Prepend `!` to the filter. Matched workspaces from the entire filter will be excluded from the set of targets. -For example, match everything except `@foo/bar`: `--filter=!@foo/bar`. Note that you may need to escape `!` as appropriate for your shell (e.g. `\!`). - -```sh -# Build everything except '@foo/bar' -turbo run build --filter=!@foo/bar -# Build all of the workspaces in the 'apps' directory, except the 'admin' workspace -turbo run build --filter=./apps/* --filter=!admin -``` - -### Via global `turbo` - -If you are using a globally installed version of `turbo`, running from within a workspace automatically -filters to that workspace's directory. That means running `turbo run test --filter={./packages/shared}` from the root of the repository is equivalent to -running `cd packages/shared && turbo run test`. - -Running with an explicitly named workspace will always work from anywhere in the repository: `turbo run test --filter=shared`. - - diff --git a/docs/pages/repo/docs/core-concepts/monorepos/running-tasks.mdx b/docs/pages/repo/docs/core-concepts/monorepos/running-tasks.mdx deleted file mode 100644 index 6225b41..0000000 --- a/docs/pages/repo/docs/core-concepts/monorepos/running-tasks.mdx +++ /dev/null @@ -1,315 +0,0 @@ ---- -title: Running Tasks -description: Turborepo helps you specify task dependencies declaratively. ---- - -import Callout from "../../../../../components/Callout"; -import HeartIcon from "@heroicons/react/solid/HeartIcon"; - -# Running Tasks in a Monorepo - -Every monorepo has two main building blocks: **workspaces** and **tasks**. Let's imagine you have a monorepo containing **three workspaces**, each with **three tasks**: - -![](/images/docs/your-monorepo-excalidraw.png) - -Here, both `apps/web` and `apps/doc` use code from `packages/shared`. In fact, when they're built (via `build`) **they need `packages/shared` to be built _first_**. - -## Most tools don't optimize for speed - -Let's imagine we want to run all our tasks across all our workspaces. In a tool like `yarn`, you might run a script like this: - -``` -yarn workspaces run lint -yarn workspaces run test -yarn workspaces run build -``` - -This would mean the tasks run like this: - -![](/images/docs/yarn-workspaces-excalidraw.png) - -As you can see, `lint` gets run in all the workspaces. Then, `build` gets run - with `shared` going first. Finally, `test` gets run. - -**This is the slowest possible way to run these tasks**. Each task needs to wait for the previous one to finish before it can start. To improve on this, we'll need a tool that can multitask. - -## Turborepo can multitask - -Turborepo can schedule our tasks for maximum speed by understanding the dependencies between our tasks. - -First, we declare our tasks inside `turbo.json`: - -```json -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - // ^build means build must be run in dependencies - // before it can be run in this workspace - "outputs": [".next/**", "!.next/cache/**",".svelte-kit/**"], - "dependsOn": ["^build"] - }, - "test": {}, - "lint": {} - } -} -``` - -Next, we can replace our `yarn workspaces` script with this: - -```diff -- yarn workspaces run lint -- yarn workspaces run test -- yarn workspaces run build -+ turbo run lint test build -``` - -When we run it, Turborepo will **multitask as many tasks as possible over all available CPU's**, meaning our tasks run like this: - -![](/images/docs/turborepo-excalidraw.png) - -Both `lint` and `test` run immediately, because they have no `dependsOn` specified in `turbo.json`. - -The `build` task inside `shared` completes first, then `web` and `docs` build afterwards. - -## Defining a pipeline - -The `pipeline` configuration declares which tasks depend on each other in your monorepo. Here's a kitchen sink example: - -```jsonc filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - // A workspace's `build` task depends on that workspace's - // topological dependencies' and devDependencies' - // `build` tasks being completed first. The `^` symbol - // indicates an upstream dependency. - "dependsOn": ["^build"], - "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"] - }, - "test": { - // A workspace's `test` task depends on that workspace's - // own `build` task being completed first. - "dependsOn": ["build"], - // A workspace's `test` task should only be rerun when - // either a `.tsx` or `.ts` file has changed. - "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "test/**/*.tsx"] - }, - // A workspace's `lint` task has no dependencies and - // can be run whenever. - "lint": {}, - "deploy": { - // A workspace's `deploy` task depends on the `build`, - // `test`, and `lint` tasks of the same workspace - // being completed. - "dependsOn": ["build", "test", "lint"] - } - } -} -``` - -Let's walk through some common patterns you'll want to get to know before diving in to `turbo.json`. - -### Dependencies between tasks - -#### In the same workspace - -There might be tasks which need to run _before_ other tasks. For instance, `build` might need to be run before `deploy`. - -If both tasks are in the same workspace, you can specify the relationship like this: - -```jsonc filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"], - "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"] - }, - "deploy": { - // A workspace's `deploy` task depends on the `build`, - // task of the same workspace being completed. - "dependsOn": ["build"] - } - } -} -``` - -This means that whenever `turbo run deploy` is run, `build` will also be run inside the same workspace. - -#### In a different workspace - -A common pattern in monorepos is to declare that a workspace's `build` task should only run once the `build` tasks of all _the workspaces it depends on_ are complete. - -The `^` symbol explicitly declares that the task has a dependency on a task in a workspace it depends on. - -```jsonc filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - // "A workspace's `build` command depends on its dependencies' - // and devDependencies' `build` commands being completed first" - "dependsOn": ["^build"], - "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"] - } - } -} -``` - -#### No dependencies - -An empty dependency list (`dependsOn` is either undefined or `[]`) means that nothing needs to run before this task! After all, it has NO dependencies. - -```jsonc filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - // A workspace's `lint` command has no dependencies and can be run - // whenever. - "lint": {} - } -} -``` - -#### Specific workspace-tasks - -Sometimes, you may want to create a workspace-task dependency on another workspace-task. This can be especially helpful for repos migrating from `lerna` or `rush`, where tasks are run in separate phases by default. Sometimes these configurations make assumptions that cannot be expressed in a simple `pipeline` configuration, as seen above. Or you may just want to express sequences of tasks between applications or microservices when using `turbo` in CI/CD. - -For these cases, you can express these relationships in your `pipeline` configuration using the `#` syntax. -The example below describes the `deploy` script of a `frontend` application that depends on the `deploy` and `health-check` scripts of `backend`, as well as the `test` script of a `ui` workspace: - -```jsonc filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - // Standard configuration - "build": { - "dependsOn": ["^build"], - "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"] - }, - "test": { - "dependsOn": ["^build"] - }, - "deploy": { - "dependsOn": ["test", "build"] - }, - - // Explicit workspace-task to workspace-task dependency - "frontend#deploy": { - "dependsOn": ["ui#test", "backend#deploy", "backend#health-check"] - } - } -} -``` - -This explicit configuration for `frontend#deploy` may seem to conflict with the `test` and `deploy` task configurations, but it does not. Since `test` and `deploy` do not have dependencies on other workspaces (e.g. `^`), they can execute any time after their workspace's `build` and `test` scripts have finished. - - - Notes: - -1. Although this `#` syntax is a useful escape hatch, we generally recommend using it for deployment orchestration tasks such as health checks, rather than build-time dependencies, so that Turborepo can optimize these tasks more efficiently -1. Package-tasks do not inherit cache configuration. You must redeclare - [`outputs`](/repo/docs/reference/configuration#outputs) at the moment. -1. `` must match the `name` key in the workspace's `package.json` or the task will be ignored. - - - -### Running tasks from the root - -`turbo` can run tasks that exist in the `package.json` file at the root of the monorepo. -These must be explicitly added to the pipeline configuration using the key syntax `"//#"`. This is -true even for tasks that already have their own entry. For example, if your pipeline declares a `"build"` task, -and you want to include the `build` script defined in the monorepo's root `package.json` file with -`turbo run build`, you must opt the root into it by declaring `"//#build": {...}` in your configuration. -Conversely, you _do not_ need to define a generic `"my-task": {...}` entry if all you need is `"//#my-task": {...}`. - -A sample pipeline that defines the root task `format` and opts the root into `test` might look like: - -```jsonc filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"], - "outputs": [".next/**", "!.next/cache/**", ".svelte-kit/**"] - }, - "test": { - "dependsOn": ["^build"], - }, - // This will cause the "test" script to be included when - // "turbo run test" is run - "//#test": { - "dependsOn": [], - }, - // This will cause the "format" script in the root package.json - // to be run when "turbo run format" is run. Since the general - // "format" task is not defined, only the root's "format" script - // will be run. - "//#format": { - "dependsOn": [], - "outputs": ["dist/**/*"], - "inputs": ["version.txt"] - } - } -} -``` - -**A note on recursion**: Scripts defined in the monorepo's root `package.json` often call `turbo` themselves. -For example, the `build` script might be `turbo run build`. In this situation, including `//#build` in -`turbo run build` will cause infinite recursion. It is for this reason that tasks run from the monorepo's root must -be explicitly opted into via including `//#` in the pipeline configuration. `turbo` includes -some best-effort checking to produce an error in the recursion situations, but it is up to you to only -opt in those tasks which don't themselves trigger a `turbo` run that would recurse. - -### Dependencies outside of a task - -When your task has topological dependencies that are outside of that given task, you'll still want to enjoy the parallelism of Turborepo and ensure that your caching behavior is correct according to your code changes. - -To demonstrate how to do this, let's say you have a set of workspaces to do a little bit of math: `add`, `subtract`, and `multiply`. `subtract` is implemented by calling `add` with a negative number and your `multiply` works by calling `add` in a loop. So, `add` is a dependency of both `subtract` and `multiply`. - -You've written tests in all three of these workspaces and it's time to run them. There are two requirements here: - -1. All tests run in parallel to keep things speedy -2. A change in a dependency should result in a cache miss - -To accomplish this, we can set up a pipeline like so: - -```jsonc filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "topo": { - "dependsOn": ["^topo"] - }, - "test": { - "dependsOn": ["^topo"] - } - } - } -``` - -![](/images/docs/task-graph-with-placeholder-task.png) - -In this pipeline, we create an intermediary placeholder `topo` task. Since we don't have a `topo` command in our workspaces, the pipeline will go straight to running `test` scripts in parallel, meeting our first requirement. The second requirement will also be taken care of, falling back on Turborepo's default behavior of creating hashes for a workspace task and it's dependencies as a tree. - - - -### Tips - -#### Tasks that are in the `pipeline` but not in SOME `package.json` - -Sometimes tasks declared in the `pipeline` are not present in all workspaces' `package.json` files. `turbo` will gracefully ignore those. No problem! - -#### `pipeline` tasks are the only ones that `turbo` knows about - -`turbo` will only account for tasks declared in the `pipeline` configuration. If it's not listed there, `turbo` will not know how to run them. diff --git a/docs/pages/repo/docs/core-concepts/monorepos/skipping-tasks.mdx b/docs/pages/repo/docs/core-concepts/monorepos/skipping-tasks.mdx deleted file mode 100644 index 5096d21..0000000 --- a/docs/pages/repo/docs/core-concepts/monorepos/skipping-tasks.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: Skipping tasks -description: Never do the same work twice. ---- - -import Callout from '../../../../../components/Callout' - -# Skipping Tasks - -[Build caching](/repo/docs/core-concepts/caching) can dramatically speed up your tasks - but you can do even better by using `npx turbo-ignore`. If your workspace is unaffected by your code changes, you can completely skip executing a task altogether. - -Let's say you want to skip the unit tests for your `web` workspace when there aren't any changes to your `web` application (or its package dependencies). If you are already using [Remote Caching](https://turbo.build/repo/docs/core-concepts/remote-caching), you will probably get a cache hit, but you would still spend time provisioning the CI container, installing `npm` dependencies, and other things that can take a while. - -Ideally, we would do a quick check to see if any of that work needs to happen in the first place. - -After we've checked out the repo, but **before** any other work, we can take a few seconds to check that our `web` tests have changed since the parent commit. - -```bash -npx turbo-ignore web --task=test -``` - -This command will: - -1. Filter for the `web` workspace. -2. Create the `dry` output for your `test` task compared to your parent commit. -3. Parse the output to determine which packages have changed. -4. Exit with a `1` code if changes are detected. Otherwise, exits with a `0`. - -While you may have been able to hit a `>>> FULL TURBO` cache for this task, we just saved time with all of the other setup tasks required to run your CI. - -## Using `turbo-ignore` - -To skip unaffected work, first ensure that your git history is available on the machine. Then, run `npx turbo-ignore`. - -`turbo-ignore` uses a combination of the `--filter` and `--dry=json` flags to find changes from the parent commit to the current commit to identify affected packages. By default, `turbo-ignore` finds the difference for the **build task in the current working directory**, but you can [customize this behavior with flags](#customizing-behavior). - -Here's an example of the command that will be built and run: - -```bash -npx turbo run build --filter=@example/web...3c8387ffd98b751305fe3f0284befdd00cbd4610 --dry=json -``` - -Note that a dry run does not _execute_ the build task. Instead, it checks your packages to see if your code changes will affect your build (or other task) in only a few seconds. - -If `turbo-ignore` finds that the task can be skipped, it will exit the process with a `0` code. If changes have been found, the process will exit with `1`. - -On Vercel, the previously deployed SHA will be used instead of the parent commit. - -## Customizing behavior - -To specify a workspace, you can add it to your command like: - -``` -npx turbo-ignore web -``` - -where `web` is your workspace's name. - -If you'd like to change more of the default behavior, there are a few flags available: - -- `--task`: Specifies the task for the command that `turbo-ignore` will invoke. Defaults to `build`. -- `--fallback`: Specify a ref/head to compare against. Defaults to `HEAD^`. - -## Using `turbo-ignore` on Vercel - -To use `npx turbo-ignore` on Vercel, you can use the [Ignored Build Step](https://vercel.com/docs/concepts/projects/overview#ignored-build-step) feature. Vercel will automatically infer the correct arguments to successfully run `turbo-ignore`. diff --git a/docs/pages/repo/docs/core-concepts/remote-caching.mdx b/docs/pages/repo/docs/core-concepts/remote-caching.mdx deleted file mode 100644 index 6f7c542..0000000 --- a/docs/pages/repo/docs/core-concepts/remote-caching.mdx +++ /dev/null @@ -1,112 +0,0 @@ ---- -title: Remote Caching -description: Share cache artifacts across machines for even faster builds. ---- - -import Callout from "../../../../components/Callout"; -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Remote Caching - -Turborepo's [task cache](/repo/docs/core-concepts/caching) can save a lot of time by never doing the same work twice. - -But there's an issue - the **cache is local to your machine**. When you're working with a CI, this can result in a lot of duplicated work: - -![](/images/docs/local-caching.png) - -Since Turborepo only caches to the local filesystem by default, the same task (`turbo run build`) must be **re-executed on each machine** (by you, by your teammates, by your CI, by your PaaS, etc.) even when all of the task inputs are identical — which **wastes time and resources**. - -## A single, shared cache - -What if you could share a single Turborepo cache across your entire team (and even your CI)? - -![](/images/docs/remote-caching.png) - -By working with providers like [Vercel](#vercel), Turborepo can securely communicate with a remote cache - a cloud server that stores the results of your tasks. - -This can save enormous amounts of time by **preventing duplicated work across your entire organization**. - - - Remote Caching is a powerful feature of Turborepo, but with great power comes - great responsibility. Make sure you are caching correctly first and double - check handling of environment variables. Please also remember Turborepo treats - logs as artifacts, so be aware of what you are printing to the console. - - -## Vercel - -### For Local Development - -If you want to link your local turborepo to your Remote Cache, first authenticate the Turborepo CLI with your Vercel account: - -```sh -turbo login -``` - - - If your Remote Cache is configured to use single-sign-on you will need to run - `npx turbo login --sso-team=TEAMNAME` in order to get a cache token with the - correct privileges. - - -Next, link your Turborepo to your remote cache: - -```sh -turbo link -``` - -Once enabled, make some changes to a workspace you are currently caching and run tasks against it with `turbo run`. -Your cache artifacts will now be stored locally _and_ in your Remote Cache. - -To verify, delete your local Turborepo cache with: - - - - ```sh - rm -rf ./node_modules/.cache/turbo - ``` - - - ```sh - rd /s /q "./node_modules/.cache/turbo" - ``` - - - -Then run the same build again. If things are working properly, `turbo` should not execute tasks locally, but rather download both the logs and artifacts from your Remote Cache and replay them back to you. - -### Remote Caching on Vercel Builds - -If you are building and hosting your apps on Vercel, Remote Caching will be automatically set up on your behalf once you use `turbo`. You need to update your [build settings](https://vercel.com/docs/concepts/deployments/configure-a-build) to build with `turbo`. - -Please refer to the [Vercel documentation](https://vercel.com/docs/concepts/git/monorepos#turborepo?utm_source=turbo.build&utm_medium=referral&utm_campaign=docs-link) for instructions. - -### Artifact Integrity and Authenticity Verification - -You can enable Turborepo to sign artifacts with a secret key before uploading them to the Remote Cache. Turborepo uses `HMAC-SHA256` signatures on artifacts using a secret key you provide. -Turborepo will verify the remote cache artifacts' integrity and authenticity when they're downloaded. -Any artifacts that fail to verify will be ignored and treated as a cache miss by Turborepo. - -To enable this feature, set the `remoteCache` options on your `turbo.json` config to include `signature: true`. Then specify your secret key by declaring the `TURBO_REMOTE_CACHE_SIGNATURE_KEY` environment variable. - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "remoteCache": { - // Indicates if signature verification is enabled. - "signature": true - } -} -``` - -## Custom Remote Caches - -You can self-host your own Remote Cache or use other remote caching service providers as long as they comply with Turborepo's Remote Caching Server API. - -You can set the remote caching domain by specifying the `--api` and `--token` flags, where `--api` is the hostname and `--token` is a bearer token. - -```sh -turbo run build --api="https://my-server.example.com" --token="xxxxxxxxxxxxxxxxx" -``` - -You can see the endpoints / requests [needed here](https://github.com/vercel/turbo/blob/main/cli/internal/client/client.go). diff --git a/docs/pages/repo/docs/core-concepts/scopes.mdx b/docs/pages/repo/docs/core-concepts/scopes.mdx deleted file mode 100644 index 4757c13..0000000 --- a/docs/pages/repo/docs/core-concepts/scopes.mdx +++ /dev/null @@ -1,50 +0,0 @@ ---- -title: Scoped tasks -description: Even faster Turborepo builds with scoped tasks. -searchable: false ---- - -import Callout from "../../../../components/Callout"; -import HeartIcon from "@heroicons/react/solid/HeartIcon"; - - - `--scope` is deprecated in `1.2.x`. Please use - [`--filter`](/repo/docs/core-concepts/monorepos/filtering) instead. - - -# Scoped Tasks - -Scoping task execution can speed up the process especially if there are distinct clusters of workspaces that are not related to each other within your repository. Turborepo has a `scope` option that allows the task running to proceed up to the workspaces found that matches the `scope` argument. It's useful to think of `scope` as an "entry point" into your monorepo's workspace/task graph. This is a string matcher based on the name of the workspaces (not the workspace path). - - - It is important to note that dependents and dependencies refer to the - workspace and task. - - -## Scoped tasks with all its dependents - -By default, it is helpful to be able to run tasks on all affected workspaces within a scope. Workspaces that changed will affect downstream consumers. In this case, pass along the `scope` to build all the dependencies as well. - - - You can use wildcard character: `*`. This is particularly helpful when - workspaces are named by group or by scope. - - -```sh -turbo run build --scope=*build-tools* -``` - -## Scoped tasks with no dependents & their dependencies - -Sometimes we want to run the tasks needed to satisfy the `build` script of all the workspaces that has the `build-tools` string in their names. Think of this as running tasks up and including the workspace matched in the scope. Add a `--no-deps` flag to run up to a workspace task. - -```sh -turbo run build --scope=*build-tools* --no-deps --include-dependencies -``` - - diff --git a/docs/pages/repo/docs/faq.mdx b/docs/pages/repo/docs/faq.mdx deleted file mode 100644 index 5d4c1c5..0000000 --- a/docs/pages/repo/docs/faq.mdx +++ /dev/null @@ -1,51 +0,0 @@ ---- -title: Frequently Asked Questions -description: Frequently asked questions about Turborepo. ---- - -import Callout from '../../../components/Callout' - -# Frequently Asked Questions - -## Should I install Turborepo globally? - -You have two options when working with Turborepo: - -1. Install it globally, via `npm install --global turbo` -2. Install a local version in your project - -We recommend installing the `turbo` CLI globally. This gives you a smooth, ergonomic experience for running tasks. - -## Do I have to use Remote Caching to use Turborepo? - -No. [Remote Caching](/repo/docs/core-concepts/remote-caching) is optional. However, you'll find it very useful to speed up development on a team, speed up builds inside of Docker, and also save space on your own machine. - -## Does Turborepo / Remote Caching store my source code? - -No. Turborepo does not store source code. Without [Remote Caching](/repo/docs/core-concepts/remote-caching), no code ever leaves your machine—it will only cache artifacts to local disk. - -With Turborepo's Remote Caching, you are responsible for configuring cache behavior and should only set up Turborepo to cache compiled artifacts. Please be aware that Turborepo treats all logs as artifacts and so these _will_ be stored along with other cache artifacts. - -## Do I have to use Vercel to use Turborepo? - -No. Turborepo is an open-source project and is not tied to any specific hosting provider or Remote Cache provider. The default Remote Cache provider is Vercel, should you opt-in to enable it. However, you can use any other provider you like if they support the same API. Several open-source community Remote Caches are compatible with Turborepo. - -## Can I use Turborepo with a different Remote Cache provider other than Vercel? - -Yes. As long as the [Remote Cache](/repo/docs/core-concepts/remote-caching) provider you choose supports the same API, you can use Turborepo with it. - -## Does Turborepo collect any personally identifiable information? - -Due to the nature of Turborepo's functionality, no personal information is gathered when the open source binary is run locally. All cached artifacts are stored on your machine by default. Further, no log in information or contact details are collected by the `turbo` CLI, so Turborepo will never have access to any personally identifiable information. Thus, for any data privacy questions and concerns please refer to [Turborepo's Privacy Policy](/privacy). - -## Does Turborepo collect any personally identifiable information when using Remote Caching? - -When [Remote Caching](/repo/docs/core-concepts/remote-caching) is enabled, by default Turborepo will utilize your Vercel account to cache artifacts in the cloud. Thus, for any data privacy questions and concerns, please refer to [Turborepo's Privacy Policy](/privacy) and [Vercel's Privacy Policy](https://vercel.com/legal/privacy-policy). If you use a different Remote Cache provider, please refer to the provider's privacy policy. - -## How can I retain Fast Refresh in my Turborepo when using multiple Next.js applications? - -[Fast Refresh](https://nextjs.org/docs/basic-features/fast-refresh) gives you instantaneous feedback on edits made to your React components in Next.js applications. - -If your Turborepo has multiple Next.js applications, you can use `transpilePackages` inside `next.config.js` to ensure that imports across workspaces will work with Fast Refresh when changes are made. Turborepo will effectively watch for any edits and the rebuild when saving. You can get started from [this example](https://github.com/vercel/turbo/tree/main/examples/basic) which is set up to handle Fast Refresh. - -If you are using a Next.js version below 13, you will want to use [`next-transpile-modules`](https://www.npmjs.com/package/next-transpile-modules) for the same Fast Refresh behavior. diff --git a/docs/pages/repo/docs/getting-started/_meta.json b/docs/pages/repo/docs/getting-started/_meta.json deleted file mode 100644 index 2ed5b29..0000000 --- a/docs/pages/repo/docs/getting-started/_meta.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "add-to-project": "Add to Existing Project", - "from-example": "Start from an Example", - "create-new": "Create a New Monorepo", - "existing-monorepo": "Add to Existing Monorepo" -} diff --git a/docs/pages/repo/docs/getting-started/add-to-project.mdx b/docs/pages/repo/docs/getting-started/add-to-project.mdx deleted file mode 100644 index 5923a47..0000000 --- a/docs/pages/repo/docs/getting-started/add-to-project.mdx +++ /dev/null @@ -1,147 +0,0 @@ -import { Tabs, Tab } from '../../../../components/Tabs' - -# Add Turborepo to your existing project - -Turborepo can be used in **any project** to speed up the execution of scripts in your `package.json`. - -After you install `turbo`, you'll be able to run all your `package.json` tasks from `turbo` instead of your package manager. - -By configuring your `turbo.json` correctly, you'll notice how [caching](/repo/docs/core-concepts/caching) helps your tasks run a lot faster. - -## Quickstart - -0. **If you don't have one already, create a new application:** - - - -```bash -npx create-next-app@latest -``` - - -```bash -npm create vite@latest -``` - - - -1. **Install `turbo` globally:** - - - - ```bash - npm install turbo --global - ``` - - - ```bash - yarn global add turbo - ``` - - - ```bash - pnpm add turbo --global - ``` - - - -For more details about installation, see [Installing Turborepo](../installing) - -2. **Add a `turbo.json` file at the base of your new repository:** - -For more information on configuring your `turbo.json`, see the [Configuration Options](/repo/docs/reference/configuration) documentation. - - - -```json filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**"] - }, - "lint": {} - } -} -``` - - -```json filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "outputs": ["dist/**"] - }, - "lint": {} - } -} -``` - -Some Vite starters ship with a `package.json` that looks like this: - -```json filename="package.json" -{ - "scripts": { - "build": "tsc && vite build" - } -} -``` - -We recommend splitting these into a `lint` and `build` script. - -```json filename="package.json" -{ - "scripts": { - "build": "vite build", - "lint": "tsc" - } -} -``` - -This means that Turbo can schedule them separately. - - - - -3. **Edit `.gitignore`** - -Add `.turbo` to your `.gitignore` file. The CLI uses these folders for logs and certain task outputs. - -```diff -+ .turbo -``` - -4. **Try running `build` and `lint` with `turbo`:** - -```bash -turbo build lint -``` - -This runs `build` and `lint` at the same time. - -5. **Without making any changes to the code, try running `build` and `lint` again:** - -```bash -turbo build lint -``` - -You should see terminal output like this: - -``` - Tasks: 2 successful, 2 total -Cached: 2 cached, 2 total - Time: 185ms >>> FULL TURBO -``` - -Congratulations - **you just completed a build and lint in under 200ms**. - -To learn how this is possible, check out our [core concepts docs](/repo/docs/core-concepts/caching). - -6. **Try running `dev` with `turbo`:** - -```bash -turbo dev -``` - -You'll notice that your `dev` script starts up. You can use `turbo` to run any script in your `package.json`. diff --git a/docs/pages/repo/docs/getting-started/create-new.mdx b/docs/pages/repo/docs/getting-started/create-new.mdx deleted file mode 100644 index fa6f061..0000000 --- a/docs/pages/repo/docs/getting-started/create-new.mdx +++ /dev/null @@ -1,527 +0,0 @@ ---- -title: Getting Started with Turborepo -description: Create your first monorepo or add Turborepo to an existing project. ---- - -import Callout from "../../../../components/Callout"; -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Creating a new monorepo - - - This guide uses a global installation of `turbo`. Follow the [installation guide](../installing) - to get this setup. Alternatively, you can use your package manager to run a locally installed `turbo` - in the commands below. - - -## Quickstart - -To create a new monorepo, use our [`create-turbo`](https://www.npmjs.com/package/create-turbo) npm package: - - - - ```sh - npx create-turbo@latest - ``` - - - ```sh - yarn dlx create-turbo@latest - ``` - - - ```sh - pnpm dlx create-turbo@latest - ``` - - - -You can also clone a Turborepo starter repository to get a head start on your monorepo. To see Turborepo examples and starters, see the [Turborepo examples directory on GitHub](https://github.com/vercel/turbo/tree/main/examples). - -## Full tutorial - -This tutorial will walk you through setting up a basic example. By the end, you'll feel confident with using `turbo`, and know all the basic functionality. - - - -During this tutorial, some lines of code are omitted from the code samples. For instance, when showing a `package.json` we won't show _all_ of the keys - only the ones that matter. - - - -### 1. Running `create-turbo` - -First, run: - - - - ```sh - npx create-turbo@latest - ``` - - - ```sh - yarn dlx create-turbo@latest - ``` - - - ```sh - pnpm dlx create-turbo@latest - ``` - - - -This installs the [`create-turbo`](https://www.npmjs.com/package/create-turbo) CLI, and runs it. You'll be asked several questions: - -#### Where would you like to create your turborepo? - -Choose anywhere you like. The default is `./my-turborepo`. - -#### Which package manager do you want to use? - -Turborepo doesn't handle installing packages, so you'll need to choose either: - -- [npm](https://www.npmjs.com//) -- [pnpm](https://pnpm.io/) -- [yarn](https://yarnpkg.com/) - -If you're not sure, we recommend choosing `pnpm`. If you don't have it installed, cancel `create-turbo` (via `ctrl-C`) and take a look at the [installation instructions](https://pnpm.io/installation). - -#### Installation - -Once you've picked a package manager, `create-turbo` will create a bunch of new files inside the folder name you picked. It'll also install all the dependencies that come with the `basic` example by default. - -### 2. Exploring your new repo - -You might have noticed something in the terminal. `create-turbo` gave you a description of all of the things it was adding. - -``` ->>> Creating a new turborepo with the following: - - - apps/web: Next.js with TypeScript - - apps/docs: Next.js with TypeScript - - packages/ui: Shared React component library - - packages/eslint-config-custom: Shared configuration (ESLint) - - packages/tsconfig: Shared TypeScript `tsconfig.json` -``` - -Each of these is a _workspace_ - a folder containing a `package.json`. Each workspace can declare its own dependencies, run its own scripts, and export code for other workspaces to use. - -Open the root folder - `./my-turborepo` - in your favourite code editor. - -#### Understanding `packages/ui` - -First, open `./packages/ui/package.json`. You'll notice that the package's name is `"name": "ui"` - right at the top of the file. - -Next, open `./apps/web/package.json`. You'll notice that this package's name is `"name": "web"`. But also - take a look in its dependencies. - -You'll see that `"web"` depends on a package called `"ui"`. If you're using `pnpm`, you'll see it's declared like this: - - - - ```json filename="apps/web/package.json" - { - "dependencies": { - "ui": "*" - } - } - ``` - - - ```json filename="apps/web/package.json" - { - "dependencies": { - "ui": "*" - } - } - ``` - - - ```json filename="apps/web/package.json" - { - "dependencies": { - "ui": "workspace:*" - } - } - ``` - - - -This means that our **web app depends on our local `ui` package**. - -If you look inside `apps/docs/package.json`, you'll see the same thing. Both `web` and `docs` depend on `ui` - a shared component library. - -This pattern of sharing code across applications is extremely common in monorepos - and means that multiple apps can share a single design system. - -#### Understanding imports and exports - -Take a look inside `./apps/docs/pages/index.tsx`. Both `docs` and `web` are [Next.js](https://nextjs.org/) applications, and they both use the `ui` library in a similar way: - -```tsx filename="apps/docs/pages/index.tsx" -import { Button } from "ui"; -// ^^^^^^ ^^ - -export default function Docs() { - return ( -
-

Docs

-
- ); -} -``` - -They're importing `Button` directly from a dependency called `ui`! How does that work? Where is `Button` coming from? - -Open `packages/ui/package.json`. You'll notice these two attributes: - -```json filename="packages/ui/package.json" -{ - "main": "./index.tsx", - "types": "./index.tsx" -} -``` - -When workspaces import from `ui`, `main` tells them where to access the code they're importing. `types` tells them where the TypeScript types are located. - -So, let's look inside `packages/ui/index.tsx`: - -```tsx filename="packages/ui/index.tsx" -import * as React from "react"; -export * from "./Button"; -``` - -Everything inside this file will be able to be used by workspaces that depend on `ui`. - -`index.tsx` is exporting everything from a file called `./Button`, so let's go there: - -```tsx filename="packages/ui/Button.tsx" -import * as React from "react"; - -export const Button = () => { - return ; -}; -``` - -We've found our button! Any changes we make in this file will be shared across `web` and `docs`. Pretty cool! - - - -Try experimenting with exporting a different function from this file. Perhaps `add(a, b)` for adding two numbers together. - -This can then be imported by `web` and `docs`. - - - -#### Understanding `tsconfig` - -We have two more workspaces to look at, `tsconfig` and `eslint-config-custom`. Each of these allow for shared configuration across the monorepo. Let's look in `tsconfig`: - -```json filename="packages/tsconfig/package.json" -{ - "name": "tsconfig", - "files": ["base.json", "nextjs.json", "react-library.json"] -} -``` - -Here, we specify three files to be exported, inside `files`. Packages which depend on `tsconfig` can then import them directly. - -For instance, `packages/ui` depends on `tsconfig`: - - - - ```json filename="packages/ui/package.json" - { - "devDependencies": { - "tsconfig": "*" - } - } - ``` - - - ```json filename="packages/ui/package.json" - { - "devDependencies": { - "tsconfig": "*" - } - } - ``` - - - ```json filename="packages/ui/package.json" - { - "devDependencies": { - "tsconfig": "workspace:*" - } - } - ``` - - - -And inside its `tsconfig.json` file, it imports it using `extends`: - -```json filename="packages/ui/tsconfig.json" -{ - "extends": "tsconfig/react-library.json" -} -``` - -This pattern allows for a monorepo to share a single `tsconfig.json` across all its workspaces, reducing code duplication. - -#### Understanding `eslint-config-custom` - -Our final workspace is `eslint-config-custom`. - -You'll notice that this is named slightly differently to the other workspaces. It's not as concise as `ui` or `tsconfig`. Let's take a look inside `.eslintrc.js` in the root of the monorepo to figure out why. - -```ts filename=".eslintrc.js" -module.exports = { - // This tells ESLint to load the config from the workspace `eslint-config-custom` - extends: ["custom"], -}; -``` - -[ESLint](https://eslint.org/) resolves configuration files by looking for workspaces with the name `eslint-config-*`. This lets us write `extends: ['custom']` and have ESLint find our local workspace. - -But why is this in the root of the monorepo? - -The way ESLint finds its configuration file is by looking at the closest `.eslintrc.js`. If it can't find one in the current directory, it'll look in the directory above until it finds one. - -So that means that if we're working on code inside `packages/ui` (which doesn't have a `.eslintrc.js`) it'll refer to the _root_ instead. - -Apps that _do_ have an `.eslintrc.js` can refer to `custom` in the same way. For instance, in `docs`: - -```ts filename="apps/docs/.eslintrc.js" -module.exports = { - root: true, - extends: ["custom"], -}; -``` - -Just like `tsconfig`, `eslint-config-custom` lets us share ESLint configs across our entire monorepo, keeping things consistent no matter what project you're working on. - -#### Summary - -It's important to understand the dependencies between these workspaces. Let's map them out: - -- `web` - depends on `ui`, `tsconfig` and `eslint-config-custom` -- `docs` - depends on `ui`, `tsconfig` and `eslint-config-custom` -- `ui` - depends on `tsconfig` and `eslint-config-custom` -- `tsconfig` - no dependencies -- `eslint-config-custom` - no dependencies - -Note that **the Turborepo CLI is not responsible for managing these dependencies**. All of the things above are handled by the package manager you chose (`npm`, `pnpm` or `yarn`). - -### 3. Understanding `turbo.json` - -We now understand our repository and its dependencies. How does Turborepo help? - -Turborepo helps by making running tasks simpler and _much_ more efficient. - -Let's take a look inside `turbo.json`, at the root: - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "dependsOn": ["^build"], - "outputs": ["dist/**", ".next/**", "!.next/cache/**"] - }, - "lint": {}, - "dev": { - "cache": false - } - } -} -``` - -What we're seeing here is that we've _registered_ three tasks with `turbo`: `lint`, `dev` and `build`. -Every task registered inside `turbo.json` can be run with `turbo run ` (or `turbo ` for short). - - - Before we move on, let's try running a task called `hello` that _isn't_ registered in `turbo.json`: - -```bash -turbo hello -``` - -You'll see an error in the terminal. Something resembling: - -``` -Could not find the following tasks in project: hello -``` - -That's worth remembering - **in order for `turbo` to run a task, it must be in `turbo.json`**. - - - -Let's investigate the scripts we already have in place. - -### 4. Linting with Turborepo - -Try running our `lint` script: - -```sh -turbo lint -``` - -You'll notice several things happen in the terminal. - -1. Several scripts will be run at the same time, each prefixed with either `docs:lint`, `ui:lint` or `web:lint`. -2. They'll each succeed, and you'll see `3 successful` in the terminal. -3. You'll also see `0 cached, 3 total`. We'll cover what this means later. - -The scripts that each run come from each workspace's `package.json`. Each workspace can optionally specify its own `lint` script: - -```json filename="apps/web/package.json" -{ - "scripts": { - "lint": "next lint" - } -} -``` - -```json filename="apps/docs/package.json" -{ - "scripts": { - "lint": "next lint" - } -} -``` - -```json filename="packages/ui/package.json" -{ - "scripts": { - "lint": "eslint *.ts*" - } -} -``` - -When we run `turbo lint`, Turborepo looks at each `lint` script in each workspace and runs it. For more details, see our [pipelines](/repo/docs/core-concepts/monorepos/running-tasks#defining-a-pipeline) docs. - -#### Using the cache - -Let's run our `lint` script one more time. You'll notice a few new things appear in the terminal: - -1. `cache hit, replaying output` appears for `docs:lint`, `web:lint` and `ui:lint`. -2. You'll see `3 cached, 3 total`. -3. The total runtime should be under `100ms`, and `>>> FULL TURBO` appears. - -Something interesting just happened. Turborepo realised that **our code hadn't changed since the last time we ran the lint script**. - -It had saved the logs from the previous run, so it just replayed them. - -Let's try changing some code to see what happens. Make a change to a file inside `apps/docs`: - -```diff filename="apps/docs/pages/index.tsx" -import { Button } from "ui"; - -export default function Docs() { - return ( -
--

Docs

-+

My great docs

-
- ); -} -``` - -Now, run the `lint` script again. You'll notice that: - -1. `docs:lint` has a comment saying `cache miss, executing`. This means that `docs` is running its linting. -2. `2 cached, 3 total` appears at the bottom. - -This means that **the results of our previous tasks were still cached**. Only the `lint` script inside `docs` actually ran - again, speeding things up. To learn more, check out our [caching docs](/repo/docs/core-concepts/caching). - -### 5. Building with Turborepo - -Let's try running our `build` script: - -```bash -turbo build -``` - -You'll see similar outputs to when we ran our lint script. Only `apps/docs` and `apps/web` specify a `build` script in their `package.json`, so only those are run. - -Take a look inside `build` in `turbo.json`. There's some interesting config there. - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**"] - } - } -} -``` - -You'll notice that some `outputs` have been specified. Declaring outputs will mean that when `turbo` finishes running your task, it'll save the output you specify in its cache. - -Both `apps/docs` and `apps/web` are Next.js apps, and they output builds to the `./.next` folder. - -Let's try something. Delete the `apps/docs/.next` build folder. - -Run the `build` script again. You'll notice: - -1. We hit `FULL TURBO` - the builds complete in under `100ms`. -2. The `.next` folder re-appears! - -Turborepo cached the result of our previous build. When we ran the `build` command again, it restored the entire `.next/**` folder from the cache. To learn more, check out our docs on [cache outputs](/repo/docs/core-concepts/caching#configuring-cache-outputs). - -### 6. Running dev scripts - -Let's now try running `dev`. - -```bash -turbo dev -``` - -You'll notice some information in the terminal: - -1. Only two scripts will execute - `docs:dev` and `web:dev`. These are the only two workspaces which specify `dev`. -2. Both `dev` scripts are run simultaneously, starting your Next.js apps on ports `3000` and `3001`. -3. In the terminal, you'll see `cache bypass, force executing`. - -Try quitting out of the script, and re-running it. You'll notice we don't go `FULL TURBO`. Why is that? - -Take a look at `turbo.json`: - -```json filename="turbo.json" -{ - "pipeline": { - "dev": { - "cache": false, - "persistent": true - } - } -} -``` - -Inside `dev`, we've specified `"cache": false`. This means we're telling Turborepo _not_ to cache the -results of the `dev` script. `dev` runs a persistent dev server and produces no outputs, so there -is nothing to cache. Learn more about it in our docs on [turning off caching](/repo/docs/core-concepts/caching#turn-off-caching). -Additionally, we set `"persistent": true`, to let turbo know that this is a long-running dev server, -so that turbo can ensure that no other tasks depend on it. You can read more in the [docs for the -`persistent` option](/repo/docs/reference/configuration#persistent). - -#### Running `dev` on only one workspace at a time - -By default, `turbo dev` will run `dev` on all workspaces at once. But sometimes, we might only want to choose one workspace. - -To handle this, we can add a `--filter` flag to our command. - -```bash -turbo dev --filter docs -``` - -You'll notice that it now only runs `docs:dev`. Learn more about [filtering workspaces](/repo/docs/core-concepts/monorepos/filtering) from our docs. - -### Summary - -Well done! You've learned all about your new monorepo, and how Turborepo makes handling your tasks easier. - -#### Next steps - -- Need to add more tasks? Learn more about using [pipelines](/repo/docs/core-concepts/monorepos/running-tasks#defining-a-pipeline) -- Want to speed up your CI? Set up [remote caching](/repo/docs/core-concepts/remote-caching). -- Want some inspiration? Take a look at our directory of [examples](https://github.com/vercel/turbo/tree/main/examples) diff --git a/docs/pages/repo/docs/getting-started/existing-monorepo.mdx b/docs/pages/repo/docs/getting-started/existing-monorepo.mdx deleted file mode 100644 index f36fd0c..0000000 --- a/docs/pages/repo/docs/getting-started/existing-monorepo.mdx +++ /dev/null @@ -1,231 +0,0 @@ ---- -title: Getting Started with Turborepo -description: Create your first monorepo or add Turborepo to an existing project. ---- - -import Callout from "../../../../components/Callout"; -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Add Turborepo to your existing monorepo - -## Configure workspaces - -`turbo` is built on top of Workspaces, a way of managing multiple packages from within a single monorepo package. Turborepo is compatible with the workspace implementations from all package managers. For more information on managing your Turborepo workspaces, see the [Workspaces](/repo/docs/handbook/workspaces) documentation. - -You can configure workspaces any way you want, but a common folder structure example is keeping applications in the `/apps` folder and packages in the `/packages` folder. The configuration of these folders is different for each package manager. - - - -Specify your `workspaces` in your monorepo's root `package.json` file: - -```json filename="package.json" -{ - "workspaces": ["packages/*", "apps/*"] -} -``` - - - -Specify your `workspaces` in your monorepo's root `package.json` file: - -```json filename="package.json" -{ - "workspaces": ["packages/*", "apps/*"] -} -``` - - - -Specify your `packages` in `pnpm-workspace.yaml`. -```yaml filename="pnpm-workspace.yaml" -packages: - - "packages/*" - - "apps/*" -``` - - - -After configuring your workspaces, re-run your package manager's `install` command. - - - Note: Nested workspaces are not supported. As package names are required to be - unique, moving each package to be a child of the monorepo's root package - should meet your needs. - - -## Install `turbo` - -Install `turbo` globally. - - - - ```bash - npm install turbo --global - ``` - - - ```bash - yarn global add turbo - ``` - - - ```bash - pnpm install turbo --global - ``` - - - -For more details about installation, see [Installing Turborepo](../installing) - -## Create `turbo.json` - -In the root of your monorepo, create an empty file named `turbo.json`. This will hold the configuration for Turborepo. - -```json filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json" -} -``` - -## Create a `pipeline` - -To define your monorepo's task dependency graph, use the [`pipeline`](/repo/docs/core-concepts/monorepos/running-tasks) key in the `turbo.json` configuration file at the root of monorepo. `turbo` interprets this configuration to optimally schedule, execute, and cache the outputs of each of the `package.json` scripts defined in your workspaces. - -Each key in the [`pipeline`](/repo/docs/core-concepts/monorepos/running-tasks) object is the name of a `package.json` script that can be executed by [`turbo run`](/repo/docs/reference/command-line-reference#turbo-run-task). You can specify its dependencies with the [`dependsOn`](/repo/docs/reference/configuration#dependson) key inside it as well as some other options related to [caching](/repo/docs/core-concepts/caching). For more information on configuring your pipeline, see the [`Pipelines`](/repo/docs/core-concepts/monorepos/running-tasks) documentation. - -Workspaces that do not have the specified script defined in their `package.json`'s list of `scripts` will be ignored by `turbo`. - -```jsonc filename="turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - // A package's `build` script depends on that package's - // dependencies and devDependencies - // `build` tasks being completed first - // (the `^` symbol signifies `upstream`). - "dependsOn": ["^build"], - // note: output globs are relative to each package's `package.json` - // (and not the monorepo root) - "outputs": [".next/**", "!.next/cache/**"] - }, - "test": { - // A package's `test` script depends on that package's - // own `build` script being completed first. - "dependsOn": ["build"], - // A package's `test` script should only be rerun when - // either a `.tsx` or `.ts` file has changed in `src` or `test` folders. - "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts", "test/**/*.tsx"] - }, - // A package's `lint` script has no dependencies and - // can be run whenever. It also has no filesystem outputs. - "lint": {}, - "deploy": { - // A package's `deploy` script depends on the `build`, - // `test`, and `lint` scripts of the same package - // being completed. It also has no filesystem outputs. - "dependsOn": ["build", "test", "lint"] - } - } -} -``` - -The rough execution order for a given package is based on the `dependsOn` keys: - -1. `build` once its upstream dependencies have run their `build` commands -2. `test` once its _own_ `build` command is finished and has no filesystem outputs (just logs) within a package -3. `lint` runs in an arbitrary order as it has no upstream dependencies -4. `deploy` once its _own_ `build`, `test`, and `lint` commands have finished. - -After execution, the full pipeline can run: - -```sh -npx turbo run deploy -``` - -`turbo` will then schedule the execution of each task(s) to optimize usage of the machine's resources. - -## Edit `.gitignore` - -Add `.turbo` to your `.gitignore` file. The CLI uses these folders for logs and certain task outputs. - -```diff -+ .turbo -``` - -Make sure that your task artifacts, the files and folders you want cached, are also included in your `.gitignore`. - -```diff -+ build/** -+ dist/** -+ .next/** -``` - -Re-run your npm client's `install` command to check your configuration. - -## Build your monorepo - -```bash -turbo build -``` - -Depending on your monorepo setup, some artifacts might already be caching properly. In the next sections, we'll show how `turbo` works, how `scope` works, and then how to get caching working after that. - -## Configure Remote Caching - -A major key 🔑 to Turborepo's speed is that it is both lazy and efficient—it does the least amount of work possible and it tries to never redo work that's already been done before. - -At the moment, Turborepo caches your tasks on your local filesystem (i.e. "single-player mode," if you will). However, what if there was a way to take advantage of the computational work done by your teammates or your CI (i.e. "co-op multiplayer mode")? What if there was a way to teleport and share a single cache across machines? Almost like a "Dropbox" for your Turborepo cache. - -> Remote Caching has entered the chat. - -Turborepo can use a technique known as Remote Caching to share cache artifacts across machines for an additional speed boost. - - - Remote Caching is a powerful feature of Turborepo, but with great power comes - great responsibility. Make sure you are caching correctly first and double - check handling of environment variables. Please also remember Turborepo treats - logs as artifacts, so be aware of what you are printing to the console. - - -### Using Remote Caching for Local development - -Turborepo uses [Vercel](https://vercel.com/?utm_source=turbo.build&utm_medium=referral&utm_campaign=docs-link) as its default remote caching provider. If you want to link your local turborepo to your Remote Cache you can authenticate the Turborepo CLI with your Vercel account: - -```sh -turbo login -``` - -Then, link your turborepo to your remote cache: - -``` -turbo link -``` - -Once enabled, make some changes to a package or application you are currently caching and run tasks against it with `turbo run`. -Your cache artifacts will now be stored locally and in your Remote Cache. To verify that this worked, delete your local Turborepo cache: - -```sh -rm -rf ./node_modules/.cache/turbo -``` - -Run the same build again. If things are working properly, `turbo` should not execute tasks locally, but rather download both the logs and artifacts from your Remote Cache and replay them back to you. - - - **Note: When connecting to an sso-enabled Vercel team, you must provide your - Team slug as an argument to `npx turbo login`.** - - -``` -turbo login --sso-team= -``` - -## Next Steps - -You're now up and running with Turborepo, but there are still a few things to do: - -- [Understand how Turborepo caching works](/repo/docs/core-concepts/caching) -- [Correctly handle environment variables](/repo/docs/core-concepts/caching#altering-caching-based-on-environment-variables) -- [Learn to orchestrate task running with pipelines](/repo/docs/core-concepts/monorepos/running-tasks) -- [Efficiently filter package tasks](/repo/docs/core-concepts/monorepos/filtering) -- [Configure Turborepo with your CI provider](/repo/docs/ci) diff --git a/docs/pages/repo/docs/getting-started/from-example.mdx b/docs/pages/repo/docs/getting-started/from-example.mdx deleted file mode 100644 index ba1e5ce..0000000 --- a/docs/pages/repo/docs/getting-started/from-example.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Examples -description: Start from an example. ---- - -import { readdirSync, lstatSync, readFileSync } from 'fs' -import path from 'path' -import { ExamplesArea } from "../../../../components/ExamplesArea"; - -export const getStaticProps = ({ params }) => { - // path to examples directory at the monorepo root. - const examplesDirectory = path.join(__dirname, '../../../../../../../examples') - const examples = []; - readdirSync(examplesDirectory).forEach(file => { - if (lstatSync(path.join(examplesDirectory, file)).isDirectory()) { - try { - examples.push({ - slug: file, - ...JSON.parse(readFileSync(path.join(examplesDirectory, file, "meta.json")).toString()) - } - ); - } catch (err) { - console.log(`No meta.json found for ${file}, excluding from docs`); - } - } - }); - // throw an error if no examples are found - if (examples.length === 0) { - throw new Error( - `No examples found in ${examplesDirectory}! Make sure you have updated the path if moving this file.` - ) - } - return { - props: { - ssg: { - examples - } - }, - revalidate: 60 * 60 * 24 - } -} - -# Turborepo Examples - -Clone a Turborepo starter repository to get a head start on your monorepo. - - - -For even more examples and starters, see the [Turborepo examples directory on GitHub](https://github.com/vercel/turbo/tree/main/examples). diff --git a/docs/pages/repo/docs/handbook.mdx b/docs/pages/repo/docs/handbook.mdx deleted file mode 100644 index 2111b68..0000000 --- a/docs/pages/repo/docs/handbook.mdx +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Monorepo Handbook -description: The missing manual on how to set up and use your monorepo. ---- - -import { - FundamentalsArea, - TasksArea, -} from "../../../components/MonorepoHandbook"; - -# Monorepo Handbook - -Now we've covered the core concepts, it's time to get practical. This handbook covers **everything you need to know to set up and use your monorepo**. - -## Fundamentals - -Learn about the **fundamental building blocks of monorepos** - workspaces, packages and dependencies. - - - -## Tasks - -Configure common tasks in your monorepo, like **linting, testing, and building** your apps and packages. - - diff --git a/docs/pages/repo/docs/handbook/_meta.json b/docs/pages/repo/docs/handbook/_meta.json deleted file mode 100644 index 38d0327..0000000 --- a/docs/pages/repo/docs/handbook/_meta.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "what-is-a-monorepo": "What is a Monorepo?", - "package-installation": "Package Installation", - "workspaces": "Workspaces", - "migrating-to-a-monorepo": "Migrating to a Monorepo", - "dev": "Development Tasks", - "building-your-app": "Building Your App", - "deploying-with-docker": "Deploying with Docker", - "environment-variables": "Environment Variables", - "sharing-code": "Sharing Code", - "linting": "Linting", - "testing": "Testing", - "publishing-packages": "Publishing Packages", - "troubleshooting": "Troubleshooting" -} diff --git a/docs/pages/repo/docs/handbook/building-your-app.mdx b/docs/pages/repo/docs/handbook/building-your-app.mdx deleted file mode 100644 index e2e09de..0000000 --- a/docs/pages/repo/docs/handbook/building-your-app.mdx +++ /dev/null @@ -1,76 +0,0 @@ -import { Tabs, Tab } from "../../../../components/Tabs"; -import Callout from "../../../../components/Callout"; - -# Building your App - -Unless your monorepo is only used for [publishing packages to npm](/repo/docs/handbook/publishing-packages), it will likely contain at least one application. Coordinating your app's builds with Turborepo can lead to some extraordinary gains in speed. - -## Setting up the build - -Turborepo works by keeping your workspace tasks where they belong - in each workspace's `package.json`. Let's imagine you have a monorepo that looks like this: - -``` -├── apps -│ └── web -│ └── package.json -├── package.json -└── turbo.json -``` - -Your `apps/web/package.json` should have a `build` script inside: - - - -```json filename="apps/web/package.json" -{ - "scripts": { - "build": "next build" - } -} -``` - - -```json filename="apps/web/package.json" -{ - "scripts": { - "build": "vite build" - } -} -``` - - - -Inside `turbo.json`, you can add `build` to the pipeline. - - - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**"] - } - } -} -``` - - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": ["dist/**"] - } - } -} -``` - - - - - -We configure the `outputs` so that we can enable [caching](/repo/docs/core-concepts/caching) - an extremely powerful feature of Turborepo that can skip tasks that have been done before. - - - -This means that running `turbo build` from root will build all of the apps in the repository. Thanks to Turborepo's task cache, you can end up with extremely fast build times. diff --git a/docs/pages/repo/docs/handbook/deploying-with-docker.mdx b/docs/pages/repo/docs/handbook/deploying-with-docker.mdx deleted file mode 100644 index fafb041..0000000 --- a/docs/pages/repo/docs/handbook/deploying-with-docker.mdx +++ /dev/null @@ -1,184 +0,0 @@ -import Callout from "../../../../components/Callout"; - -# Deploying with Docker - -Building a [Docker](https://www.docker.com/) image is a common way to deploy all sorts of applications. However, doing so from a monorepo has several challenges. - -## The problem - -**TL;DR:** In a monorepo, unrelated changes can make Docker do unnecessary work when deploying your app. - -Let's imagine you have a monorepo that looks like this: - -```txt -├── apps -│ ├── docs -│ │ ├── server.js -│ │ └── package.json -│ └── web -│ └── package.json -├── package.json -└── package-lock.json -``` - -You want to deploy `apps/docs` using Docker, so you create a Dockerfile: - -```docker filename="Dockerfile" -FROM node:16 - -WORKDIR /usr/src/app - -# Copy root package.json and lockfile -COPY package.json ./ -COPY package-lock.json ./ - -# Copy the docs package.json -COPY apps/docs/package.json ./apps/docs/package.json - -RUN npm install - -# Copy app source -COPY . . - -EXPOSE 8080 - -CMD [ "node", "apps/docs/server.js" ] -``` - -This will copy the root `package.json` and the root lockfile to the docker image. Then, it'll install dependencies, copy the app source and start the app. - -You should also create a `.dockerignore` file to prevent node_modules from being copied in with the app's source. - -```txt filename=".dockerignore" -node_modules -npm-debug.log -``` - -### The lockfile changes too often - -Docker is pretty smart about how it deploys your apps. Just like Turbo, it tries to do as [little work as possible](https://bitjudo.com/blog/2014/03/13/building-efficient-dockerfiles-node-dot-js/). - -In our Dockerfile's case, it will only run `npm install` if the files it has in its image are _different_ from the previous run. If not, it'll restore the `node_modules` directory it had before. - -This means that whenever `package.json`, `apps/docs/package.json` or `package-lock.json` change, the docker image will run `npm install`. - -This sounds great - until we realise something. The `package-lock.json` is _global_ for the monorepo. That means that **if we install a new package inside `apps/web`, we'll cause `apps/docs` to redeploy**. - -In a large monorepo, this can result in a huge amount of lost time, as any change to a monorepo's lockfile cascades into tens or hundreds of deploys. - -## The solution - -The solution is to prune the inputs to the Dockerfile to only what is strictly necessary. Turborepo provides a simple solution - `turbo prune`. - -```bash -turbo prune --scope="docs" --docker -``` - -Running this command creates a **pruned version of your monorepo** inside an `./out` directory. It only includes workspaces which `docs` depends on. - -Crucially, it also **prunes the lockfile** so that only the relevant `node_modules` will be downloaded. - -### The `--docker` flag - -By default, `turbo prune` puts all relevant files inside `./out`. But to optimize caching with Docker, we ideally want to copy the files over in two stages. - -First, we want to copy over only what we need to install the packages. When running `--docker`, you'll find this inside `./out/json`. - -```txt -out -├── json -│ ├── apps -│ │ └── docs -│ │ └── package.json -│ └── package.json -├── full -│ ├── apps -│ │ └── docs -│ │ ├── server.js -│ │ └── package.json -│ ├── package.json -│ └── turbo.json -└── package-lock.json -``` - -Afterwards, you can copy the files in `./out/full` to add the source files. - -Splitting up **dependencies** and **source files** in this way lets us **only run `npm install` when dependencies change** - giving us a much larger speedup. - - - Without `--docker`, all pruned files are placed inside `./out`. - - -### Example - -Our detailed [`with-docker` example](https://github.com/vercel/turbo/tree/main/examples/with-docker) goes into depth on how to utilise `prune` to its full potential. Here's the Dockerfile, copied over for convenience. - -```docker -FROM node:alpine AS builder -RUN apk add --no-cache libc6-compat -RUN apk update -# Set working directory -WORKDIR /app -RUN yarn global add turbo -COPY . . -RUN turbo prune --scope=web --docker - -# Add lockfile and package.json's of isolated subworkspace -FROM node:alpine AS installer -RUN apk add --no-cache libc6-compat -RUN apk update -WORKDIR /app - -# First install the dependencies (as they change less often) -COPY .gitignore .gitignore -COPY --from=builder /app/out/json/ . -COPY --from=builder /app/out/yarn.lock ./yarn.lock -RUN yarn install - -# Build the project -COPY --from=builder /app/out/full/ . -RUN yarn turbo run build --filter=web... - -FROM node:alpine AS runner -WORKDIR /app - -# Don't run production as root -RUN addgroup --system --gid 1001 nodejs -RUN adduser --system --uid 1001 nextjs -USER nextjs - -COPY --from=installer /app/apps/web/next.config.js . -COPY --from=installer /app/apps/web/package.json . - -# Automatically leverage output traces to reduce image size -# https://nextjs.org/docs/advanced-features/output-file-tracing -COPY --from=installer --chown=nextjs:nodejs /app/apps/web/.next/standalone ./ -COPY --from=installer --chown=nextjs:nodejs /app/apps/web/.next/static ./apps/web/.next/static -COPY --from=installer --chown=nextjs:nodejs /app/apps/web/public ./apps/web/public - -CMD node apps/web/server.js -``` - -## Remote caching - -To take advantage of remote caches during Docker builds, you will need to make sure your build container has credentials to access your Remote Cache. - -There are many ways to take care of secrets in a Docker image. We will use a simple strategy here with multi-stage builds using secrets as build arguments that will get hidden for the final image. - -Assuming you are using a Dockerfile similar to the one above, we will bring in some environment variables from build arguments right before `turbo build`: - -```docker -ARG TURBO_TEAM -ENV TURBO_TEAM=$TURBO_TEAM - -ARG TURBO_TOKEN -ENV TURBO_TOKEN=$TURBO_TOKEN - -RUN yarn turbo run build --filter=web... -``` - -`turbo` will now be able to hit your remote cache. To see a Turborepo cache hit for a non-cached Docker build image, run a command like this one from your project root: - -```sh -docker build -f apps/web/Dockerfile . --build-arg TURBO_TEAM=“your-team-name” --build-arg TURBO_TOKEN=“your-token“ --no-cache -``` diff --git a/docs/pages/repo/docs/handbook/dev.mdx b/docs/pages/repo/docs/handbook/dev.mdx deleted file mode 100644 index ea0d184..0000000 --- a/docs/pages/repo/docs/handbook/dev.mdx +++ /dev/null @@ -1,205 +0,0 @@ -import { Tabs, Tab } from '../../../../components/Tabs' -import Callout from '../../../../components/Callout' - -# Development tasks in a Monorepo - -The vast majority of development workflows look like this: - -1. Open a repository -2. Run a `dev` task while they develop -3. At the end of the day, shut down the `dev` task and close the repository. - -`dev` will likely be the most frequently run task in your repository, so getting it right is important. - -## Types of `dev` tasks - -`dev` tasks come in many shapes and sizes: - -1. Running a local development server for a web app -1. Running [`nodemon`](https://www.npmjs.com/package/nodemon) to re-run a backend process every time code changes -1. Running tests in `--watch` mode - -## Setup with Turborepo - -You should specify your `dev` task like this in your `turbo.json`. - -```json filename="turbo.json" -{ - "pipeline": { - "dev": { - "cache": false, - "persistent": true - } - } -} -``` - -Since `dev` tasks don't produce outputs, `outputs` is empty. `dev` tasks are also unique in that you -rarely want to [cache](/repo/docs/core-concepts/caching) them, so we set `cache` as `false`. -We also set `persistent` to `true`, because `dev` tasks are long-running tasks, and we want to ensure -that it doesn't block any other task from executing. - -### Setting up `package.json` - -You should also provide a `dev` task in your root `package.json`: - -```json filename="package.json" -{ - "scripts": { - "dev": "turbo run dev" - } -} -``` - -This enables developers to run the task directly from their normal task runner. - -## Running tasks _before_ `dev` - -In some workflows, you'll want to run tasks _before_ you run your `dev` task. For instance, generating code or running a `db:migrate` task. - -In these cases, use [`dependsOn`](/repo/docs/core-concepts/monorepos/running-tasks#in-the-same-workspace) to say that any `codegen` or `db:migrate` tasks should be run _before_ `dev` is run. - -```json filename="turbo.json" -{ - "pipeline": { - "dev": { - "dependsOn": ["codegen", "db:migrate"], - "cache": false - }, - "codegen": { - "outputs": ["./codegen-outputs/**"] - }, - "db:migrate": { - "cache": false - } - } -} -``` - -Then, in your app's `package.json`: - -```json filename="apps/web/package.json" -{ - "scripts": { - // For example, starting the Next.js dev server - "dev": "next", - // For example, running a custom code generation task - "codegen": "node ./my-codegen-script.js", - // For example, using Prisma - "db:migrate": "prisma db push" - } -} -``` - -This means that users of your `dev` task _don't need to worry about codegen or migrating their database_ - it gets handled for them before their development server even starts. - -## Running `dev` only in certain workspaces - -Let's assume you want to run the `dev` task in the `docs` workspace, located at `/apps/docs`. -`turbo` can infer the workspace from your directory, so if you run: - - ```bash - cd /apps/docs - turbo run dev - ``` - -`turbo` will automatically pick up that you're in the `docs` workspace and run the `dev` task. - -To run the same task from any other location in the repository, use [`--filter` syntax](/repo/docs/core-concepts/monorepos/filtering). -For example: - -```bash -turbo run dev --filter docs -``` - -## Using environment variables - -While developing, you'll often need to use environment variables. These let you customize the behavior of your program - for instance, pointing to a different `DATABASE_URL` in development and production. - -We recommend using a library called [`dotenv-cli`](https://www.npmjs.com/package/dotenv-cli) to solve this problem. - - - We want every dev to have a great experience using Turbo. The approach documented below does **not** live up to those standards. - -We're working on a first-class solution to this problem - but while you wait, here's the next-best solution. - - - -### Tutorial - -1. Install `dotenv-cli` in your [root workspace](/repo/docs/handbook/what-is-a-monorepo#the-root-workspace): - - - - ```bash - # Installs dotenv-cli in the root workspace - npm add dotenv-cli - ``` - - - ```bash - # Installs dotenv-cli in the root workspace - yarn add dotenv-cli --ignore-workspace-root-check - ``` - - - ```bash - # Installs dotenv-cli in the root workspace - pnpm add dotenv-cli --ignore-workspace-root-check - ``` - - - -2. Add a `.env` file to your root workspace: - -```diff - ├── apps/ - ├── packages/ -+ ├── .env - ├── package.json - └── turbo.json -``` - -Add any environment variables you need to inject: - -```txt filename=".env" -DATABASE_URL=my-database-url -``` - -3. Inside your root `package.json`, add a `dev` script. Prefix it with `dotenv` and the `--` argument separator: - -```json -{ - "scripts": { - "dev": "dotenv -- turbo run dev" - } -} -``` - -This will extract the environment variables from `.env` before running `turbo run dev`. - -4. Now, you can run your dev script: - - - - ```bash - npm run dev - ``` - - - ```bash - yarn dev - ``` - - - ```bash - pnpm dev - ``` - - - -And your environment variables will be populated! In Node.js, these are available on `process.env.DATABASE_URL`. - - - You should also [add your environment variables](/repo/docs/core-concepts/caching#altering-caching-based-on-environment-variables) to your `turbo.json` if you're using them to build your app. - diff --git a/docs/pages/repo/docs/handbook/environment-variables.mdx b/docs/pages/repo/docs/handbook/environment-variables.mdx deleted file mode 100644 index 6bb3d53..0000000 --- a/docs/pages/repo/docs/handbook/environment-variables.mdx +++ /dev/null @@ -1,54 +0,0 @@ -# Using environment variables - -We currently recommend using `dotenv-cli` as the simplest way to bring your environment variables into your development tasks. - -We're actively looking forward to improving the developer experience and ergonomics for your environment variables in a future release of Turborepo. - -## With local `turbo` - -1. Place all of your variables into the root of your monorepo as a `.env` file. - -2. Install `dotenv-cli` into the root of your repository. - -```json -{ - "devDependencies": { -+ "dotenv-cli": "latest" - } -} -``` - -3. Adjust your scripts to inject the environment variables into the `turbo` command. - -```json -{ - "scripts": { - "dev": "dotenv -- turbo dev" - } -} -``` - -## With global `turbo` - -If you're using `turbo` globally, you'll also need to install `dotenv-cli` globally so you can put `dotenv --` in front of the `turbo` command in your terminal. - -## With workspace scripts - -You may prefer to make your workspaces responsible for loading environment variables. This approach is more flexible, if you don't mind the extra configuration overhead in your `package.json` scripts. - -To use this strategy: - -1. Place all of your variables into the root of your monorepo as a `.env` file. - -2. Install `dotenv-cli` in the workspace. - -```json -{ - "scripts": { -+. "dev": "dotenv -e ../../.env start-server" - } - "devDependencies": { -+ "dotenv-cli": "latest" - }, -} -``` diff --git a/docs/pages/repo/docs/handbook/linting.mdx b/docs/pages/repo/docs/handbook/linting.mdx deleted file mode 100644 index 13300f9..0000000 --- a/docs/pages/repo/docs/handbook/linting.mdx +++ /dev/null @@ -1,50 +0,0 @@ -# Linting in a monorepo - -Linting in a monorepo can be tricky. Most of your workspaces will likely contain code that needs to be linted - so working out the most efficient way to lint them is tough. - -In this guide, we'll propose a method that plays to Turborepo's strengths: - -- Running lint tasks _inside_ the workspaces, not from root -- Sharing as much config as possible between workspaces - -## Running tasks - -We recommend specifying a single `lint` task inside your `turbo.json`. - -```json filename="turbo.json" -{ - "pipeline": { - "lint": {} - } -} -``` - -Then, inside **each workspace that needs to be linted**, add a `lint` script. We'll use TypeScript as an example: - -```json filename="packages/*/package.json" -{ - "scripts": { - "lint": "tsc" - } -} -``` - -This pattern has two benefits: - -- [**Parallelization**](/repo/docs/core-concepts/monorepos/running-tasks): the lint tasks will be run concurrently, speeding them up -- [**Caching**](/repo/docs/core-concepts/caching): `lint` tasks will only be re-run on workspaces that have changed - -This means you can lint your entire repo using one command: - -```bash -turbo run lint -``` - -## Sharing config files - -Sharing configuration across a monorepo helps keep the development experience consistent. Most linters will have a system for sharing config, or extending config across different files. - -So far, we've built guides for sharing config in: - -- [TypeScript](/repo/docs/handbook/linting/typescript) -- [ESLint](/repo/docs/handbook/linting/eslint) diff --git a/docs/pages/repo/docs/handbook/linting/_meta.json b/docs/pages/repo/docs/handbook/linting/_meta.json deleted file mode 100644 index cd627de..0000000 --- a/docs/pages/repo/docs/handbook/linting/_meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "typescript": "TypeScript", - "eslint": "ESLint" -} diff --git a/docs/pages/repo/docs/handbook/linting/eslint.mdx b/docs/pages/repo/docs/handbook/linting/eslint.mdx deleted file mode 100644 index 38b36b6..0000000 --- a/docs/pages/repo/docs/handbook/linting/eslint.mdx +++ /dev/null @@ -1,124 +0,0 @@ -import { Tabs, Tab } from "../../../../../components/Tabs"; - -# ESLint in a monorepo - -## Sharing config - -Sharing an ESLint config across workspaces can be a boon to productivity by making all your workspaces more consistent. - -Let's imagine a monorepo like this: - -``` -apps -├─ docs -│ ├─ package.json -│ └─ .eslintrc.js -└─ web - ├─ package.json - └─ .eslintrc.js -packages -└─ eslint-config-custom - ├─ index.js - └─ package.json -``` - -We've got a package called `eslint-config-custom`, and two applications, each with their own `.eslintrc.js`. - -### Our `eslint-config-custom` package - -Our `eslint-config-custom` file contains only a single file, `index.js`. It looks like this. - -```js filename="packages/eslint-config-custom/index.js" -module.exports = { - extends: ["next", "turbo", "prettier"], - rules: { - "@next/next/no-html-link-for-pages": "off", - }, -}; -``` - -It's a typical ESLint config, nothing fancy. - -The `package.json` looks like this: - -```json filename="packages/eslint-config-custom/package.json" -{ - "name": "eslint-config-custom", - "main": "index.js", - "version": "1.0.0", - "dependencies": { - "eslint": "latest", - "eslint-config-next": "latest", - "eslint-config-prettier": "latest", - "eslint-plugin-react": "latest", - "eslint-config-turbo": "latest" - } -} -``` - -Two things are notable here. First, the `main` field points to `index.js`. This allows files to easily [import this config](/repo/docs/handbook/sharing-code#anatomy-of-a-package). - -Secondly, the ESLint dependencies are all listed here. This is useful - it means we don't need to re-specify the dependencies inside the apps which import `eslint-config-custom`. - -### How to use the `eslint-config-custom` package - -In our `web` app, we first need to add `eslint-config-custom` as a dependency. - - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "eslint-config-custom": "*" - } -} -``` - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "eslint-config-custom": "*" - } -} -``` - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "eslint-config-custom": "workspace:*" - } -} -``` - - - -We can then import the config like this: - -```js filename="apps/web/.eslintrc.js" -module.exports = { - root: true, - extends: ["custom"], -}; -``` - -By adding `custom` to our `extends` array, we're telling ESLint to look for a package called `eslint-config-custom` - and it finds our workspace. - -### Summary - -This setup ships by default when you [create a new monorepo](/repo/docs/getting-started/create-new) with `npx create-turbo@latest`. You can also look at [our basic example](https://github.com/vercel/turbo/tree/main/examples/basic) to see a working version. - -## Setting up a `lint` task - -We recommend following the setup in the [`basics`](/repo/docs/handbook/linting#running-tasks) section, with one alteration. - -Each `package.json` script should look like this: - -```json filename="packages/*/package.json" -{ - "scripts": { - "lint": "eslint" - } -} -``` diff --git a/docs/pages/repo/docs/handbook/linting/typescript.mdx b/docs/pages/repo/docs/handbook/linting/typescript.mdx deleted file mode 100644 index f340f4e..0000000 --- a/docs/pages/repo/docs/handbook/linting/typescript.mdx +++ /dev/null @@ -1,129 +0,0 @@ -import { Tabs, Tab } from "../../../../../components/Tabs"; - -# TypeScript in a monorepo - -You can use TypeScript in a monorepo in one of two ways - as a linter, or as a build tool. - -In this section, we'll discuss TypeScript's role as a linter. This is when you prevent TypeScript emitting files (with [`noEmit`](https://www.typescriptlang.org/tsconfig/noEmit.html)) and instead use it _only_ to check your source code's types. - -## Sharing `tsconfig.json` - -We can share TypeScript config files across our repository with a clever solution. We can put our _base_ `tsconfig.json` files in a single workspace, and `extend` them from the `tsconfig.json` files in our apps. - -Let's imagine a workspace like this: - -``` -apps -├─ docs -│ ├─ package.json -│ ├─ tsconfig.json -├─ web -│ ├─ package.json -│ ├─ tsconfig.json -packages -├─ tsconfig -│ ├─ base.json -│ ├─ nextjs.json -│ ├─ package.json -│ ├─ react-library.json -``` - -### Our `tsconfig` package - -Inside `packages/tsconfig`, we have a few `json` files which represent different ways you might want to configure TypeScript. They each look like this: - -```json filename="packages/tsconfig/base.json" -{ - "$schema": "https://json.schemastore.org/tsconfig", - "display": "Default", - "compilerOptions": { - "composite": false, - "declaration": true, - "declarationMap": true, - "esModuleInterop": true, - "forceConsistentCasingInFileNames": true, - "inlineSources": false, - "isolatedModules": true, - "moduleResolution": "node", - "noUnusedLocals": false, - "noUnusedParameters": false, - "preserveWatchOutput": true, - "skipLibCheck": true, - "strict": true - }, - "exclude": ["node_modules"] -} -``` - -Inside `package.json`, we simply name our package: - -```json filename="packages/tsconfig/package.json" -{ - "name": "tsconfig" -} -``` - -The other `json` files in the repository can be accessed via a simple import: - -```ts -import baseJson from "tsconfig/base.json"; -import nextjsJson from "tsconfig/nextjs.json"; -import reactLibraryJson from "tsconfig/react-library.json"; -``` - -This lets us export different config settings for different types of projects. - -### How to use the `tsconfig` package - -Each app/package which uses our shared `tsconfig` must first specify it as a dependency: - - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "tsconfig": "*" - } -} -``` - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "tsconfig": "*" - } -} -``` - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "tsconfig": "workspace:*" - } -} -``` - - - -Then, they can **extend it inside their own `tsconfig.json`**: - -```json filename="apps/web/tsconfig.json" -{ - // We extend it from here! - "extends": "tsconfig/nextjs.json", - - // You can specify your own include/exclude - "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"], - "exclude": ["node_modules"] -} -``` - -### Summary - -This setup ships by default when you [create a new monorepo](/repo/docs/getting-started/create-new) with `npx create-turbo@latest`. You can also look at [our basic example](https://github.com/vercel/turbo/tree/main/examples/basic) to see a working version. - -## Running tasks - -We recommend following the setup in the [`basics`](/repo/docs/handbook/linting#running-tasks) section. diff --git a/docs/pages/repo/docs/handbook/migrating-to-a-monorepo.mdx b/docs/pages/repo/docs/handbook/migrating-to-a-monorepo.mdx deleted file mode 100644 index 912a1be..0000000 --- a/docs/pages/repo/docs/handbook/migrating-to-a-monorepo.mdx +++ /dev/null @@ -1,77 +0,0 @@ -import Callout from "../../../../components/Callout"; - -# Migrating to a Monorepo - -Migrating from a multi-repo setup to a monorepo setup can bring enormous benefits for productivity, especially if: - -- You're finding it hard to share code between applications -- You want a unified approach on how your team builds code - -It can be daunting to move to a monorepo. But with careful planning, it can go pretty smoothly. - -## Folder structure - -Let's imagine your multi-repo setup looks like this: - -``` -web (repo 1) -├─ package.json - -docs (repo 2) -├─ package.json - -app (repo 3) -├─ package.json -``` - -You've got three repositories, `web`, `docs` and `app`. They don't have any shared dependencies, but you've noticed _lots_ of duplicated code between them. - -The best way to organise them in a monorepo would be like so: - -``` -my-monorepo -├─ apps -│ ├─ app -│ │ └─ package.json -│ ├─ docs -│ │ └─ package.json -│ └─ web -│ └─ package.json -└─ package.json -``` - -To start sharing code, you could use the [internal package](/repo/docs/handbook/sharing-code/internal-packages) pattern, resulting in a new `packages` folder: - -``` -my-monorepo -├─ apps -│ ├─ app -│ │ └─ package.json -│ ├─ docs -│ │ └─ package.json -│ └─ web -│ └─ package.json -├─ packages -│ └─ shared -│ └─ package.json -└─ package.json -``` - - - If you're planning to move to a monorepo, try sketching out the exact folder - structure you're aiming for. - - -## Setting up workspaces - -Once your apps are in the right folder structure, you'll need to set up workspaces and install your dependencies. Our sections on [setting up workspaces](/repo/docs/handbook/workspaces) should help. - -## Handling tasks - -Now your workspaces are set up, you'll need to figure out how you're going to run your tasks in your new monorepo. We've got sections on: - -1. How to [configure tasks](/repo/docs/core-concepts/monorepos/running-tasks) with Turborepo. -1. How to set up your [development tasks](/repo/docs/handbook/dev) -1. How to set up [linting](/repo/docs/handbook/linting) -1. How to [build your application](/repo/docs/handbook/building-your-app) -1. How to set up [testing](/repo/docs/handbook/testing) diff --git a/docs/pages/repo/docs/handbook/package-installation.mdx b/docs/pages/repo/docs/handbook/package-installation.mdx deleted file mode 100644 index cb67afc..0000000 --- a/docs/pages/repo/docs/handbook/package-installation.mdx +++ /dev/null @@ -1,157 +0,0 @@ -import Callout from "../../../../components/Callout"; -import HeartIcon from "@heroicons/react/solid/HeartIcon"; -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Package Installation - -A package manager (like `npm`) handles two things for you: [managing workspaces](/repo/docs/handbook/workspaces) and installing packages. - -Turborepo is compatible with four package managers: - -- [npm](https://docs.npmjs.com/cli/v8/using-npm/workspaces/#description) -- [pnpm](https://pnpm.io/workspaces) -- [Yarn 1](https://classic.yarnpkg.com/lang/en/docs/workspaces/) -- Yarn >=2 (docs coming soon) - -You should use whichever you feel most comfortable with - but **if you're a monorepo beginner, we recommend npm**. - -If you're **comfortable with monorepos, we recommend pnpm**. It's faster and offers some useful CLI options like `--filter`. - -## Installing packages - -When you first clone or create your monorepo, you'll need to: - -1. Make sure you're in the root directory of your monorepo -2. Run the install command: - - - - - ```bash - npm install - ``` - - - - - ```bash - yarn install - ``` - - - - - ```bash - pnpm install - ``` - - - - -You'll now see `node_modules` folders appear in the root of your repository, and in each workspace. - -## Adding/removing/upgrading packages - -You can add, remove and upgrade packages from within your monorepo using your package manager's built-in commands: - - - - - **Install a package in a workspace** - ```bash - npm install --workspace= - ``` - - Example: - ```bash - npm install react --workspace=web - ``` - - **Remove a package from a workspace** - ```bash - npm uninstall --workspace= - ``` - - Example: - ```bash - npm uninstall react --workspace=web - ``` - - **Upgrade a package in a workspace** - ```bash - npm update --workspace= - ``` - - Example: - ```bash - npm update react --workspace=web - ``` - - - - - **Install a package in a workspace** - ```bash - yarn workspace add - ``` - - Example: - ```bash - yarn workspace web add react - ``` - - **Remove a package from a workspace** - ```bash - yarn workspace remove - ``` - - Example: - ```bash - yarn workspace web remove react - ``` - - **Upgrade a package in a workspace** - ```bash - yarn workspace upgrade - ``` - - Example: - ```bash - yarn workspace web upgrade react - ``` - - - - - **Install a package in a workspace** - ```bash - pnpm add --filter - ``` - - Example: - ```bash - pnpm add react --filter web - ``` - - **Remove a package from a workspace** - ```bash - pnpm uninstall --filter - ``` - - Example: - ```bash - pnpm uninstall react --filter web - ``` - - **Upgrade a package in a workspace** - ```bash - pnpm update --filter - ``` - - Example: - ```bash - pnpm update react --filter web - ``` - - - diff --git a/docs/pages/repo/docs/handbook/publishing-packages.mdx b/docs/pages/repo/docs/handbook/publishing-packages.mdx deleted file mode 100644 index bb6e183..0000000 --- a/docs/pages/repo/docs/handbook/publishing-packages.mdx +++ /dev/null @@ -1,15 +0,0 @@ -import Callout from "../../../../components/Callout"; - -# Publishing Packages - -Publishing a package to `npm` from a monorepo can be an extremely satisfying and smooth experience, with the right tools. - -You should follow this setup if you want to publish some of your monorepo's workspaces to `npm` as packages. If you don't need to publish to `npm`, you should use an [internal package](/repo/docs/handbook/sharing-code/internal-packages) instead. They're much easier to set up and use. - -## Tools - -You'll need to set up a few tools to get it working: - -First, you'll need a [bundler](/repo/docs/handbook/publishing-packages/bundling) to turn your code into [`CommonJS`](https://en.wikipedia.org/wiki/CommonJS), the most commonly used format on `npm`. You'll also need to set up a dev script so that you can work on the workspace in local development. - -Finally, you'll need a tool for [publishing & versioning](/repo/docs/handbook/publishing-packages/versioning-and-publishing). This will handle both bumping your monorepo's package versions _and_ publishing to npm. diff --git a/docs/pages/repo/docs/handbook/publishing-packages/_meta.json b/docs/pages/repo/docs/handbook/publishing-packages/_meta.json deleted file mode 100644 index 0c946ab..0000000 --- a/docs/pages/repo/docs/handbook/publishing-packages/_meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "bundling": "Bundling", - "versioning-and-publishing": "Versioning and Publishing" -} diff --git a/docs/pages/repo/docs/handbook/publishing-packages/bundling.mdx b/docs/pages/repo/docs/handbook/publishing-packages/bundling.mdx deleted file mode 100644 index df3d5c7..0000000 --- a/docs/pages/repo/docs/handbook/publishing-packages/bundling.mdx +++ /dev/null @@ -1,130 +0,0 @@ -import Callout from "../../../../../components/Callout"; -import { Tabs, Tab } from "../../../../../components/Tabs"; - -# Bundling packages in a Monorepo - -Unlike [internal](/repo/docs/handbook/sharing-code/internal-packages) packages, external packages can be deployed to npm _and_ used locally. In this guide, we'll be using a bundler to bundle a package to [`CommonJS`](https://en.wikipedia.org/wiki/CommonJS), the most commonly used format used on npm. - -## Setting up a build script - -Let's start with a package created using our [internal packages](/repo/docs/handbook/sharing-code/internal-packages) tutorial. - -There, we created a `math-helpers` package which contained a few helper functions for adding and subtracting. We've decided that this package is good enough for npm, so we're going to bundle it. - -At the end of that tutorial, we had a package set up under `/packages`, which looked like this: - -``` -├── apps -│ └── web -│ └── package.json -├── packages -│ └── math-helpers -│ ├── src -│ │ └── index.ts -│ ├── tsconfig.json -│ └── package.json -├── package.json -└── turbo.json -``` - -We're going to add a `build` script to `math-helpers`, using a bundler. If you're unsure which one to choose, we recommend [`tsup`](https://tsup.egoist.dev/). - - - - -First install, `tsup` inside `packages/math-helpers` using your [package manager](/repo/docs/handbook/package-installation). - -```json filename="packages/math-helpers/package.json" -{ - "scripts": { - "build": "tsup src/index.ts --format cjs --dts" - } -} -``` - -`tsup` outputs files to the `dist` directory by default, so you should: - -1. Add `dist` to your `.gitignore` files to make sure they aren't committed by `git`. -2. Add `dist` to the outputs of `build` in your `turbo.json`. - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": ["dist/**"] - } - } -} -``` - -That way, when `tsup` is run the outputs can be [cached](/repo/docs/core-concepts/caching) by Turborepo. - -Finally, we should change `main` to point at `./dist/index.js` inside `package.json`. `types` can point at `./dist/index.d.ts`: - -```json filename="packages/math-helpers/package.json" -{ - "main": "./dist/index.js", - "types": "./dist/index.d.ts" -} -``` - - - -If you run into errors by using `main` and `types`, take a look at the [tsup docs](https://tsup.egoist.dev/#bundle-formats). - -Bundling is a complicated topic, and we don't have space here to cover everything! - - - - - - -### Building our package before our app - -Before we can run `turbo run build`, there's one thing we need to consider. We've just added a [task dependency](/repo/docs/core-concepts/monorepos/running-tasks) into our monorepo. The `build` of `packages/math-helpers` needs to run **before** the `build` of `apps/web`. - -Fortunately, we can use `dependsOn` to easily configure this. - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "dependsOn": [ - // Run builds in workspaces I depend on first - "^build" - ] - } - } -} -``` - -Now, we can run `turbo run build`, and it'll automatically build our packages _before_ it builds our app. - -## Setting up a dev script - -There's a small issue with our setup. We are building our package just fine, but it's not working great in dev. Changes that we make to our `math-helpers` package aren't being reflected in our app. - -That's because we don't have a `dev` script to rebuild our packages while we're working. We can add one easily: - - - - -```json filename="packages/math-helpers/package.json" -{ - "scripts": { - "build": "tsup src/index.ts --format cjs --dts", - "dev": "npm run build -- --watch" - } -} -``` - -This passes the `--watch` flag to `tsup`, meaning it will watch for file changes. - - - - -If we've already set up [dev scripts](/repo/docs/handbook/dev) in our `turbo.json`, running `turbo run dev` will run our `packages/math` dev task in parallel with our `apps/web` dev task. - -## Summary - -Our package is now in a spot where we can consider deploying to npm. In our [versioning and publishing](/repo/docs/handbook/publishing-packages/versioning-and-publishing) section, we'll do just that. diff --git a/docs/pages/repo/docs/handbook/publishing-packages/versioning-and-publishing.mdx b/docs/pages/repo/docs/handbook/publishing-packages/versioning-and-publishing.mdx deleted file mode 100644 index ae913d2..0000000 --- a/docs/pages/repo/docs/handbook/publishing-packages/versioning-and-publishing.mdx +++ /dev/null @@ -1,57 +0,0 @@ -import Callout from "../../../../../components/Callout"; - -# Versioning and Publishing Packages in a Monorepo - -Manually versioning and publishing packages in a monorepo can be extremely tiresome. Luckily, there's a tool that makes things easy - the [Changesets](https://github.com/changesets/changesets) CLI. - -We recommend Changesets because it's intuitive to use, and - just like Turborepo - fits with the monorepo tools you're already used to. - -Some alternatives are: - -- [intuit/auto](https://github.com/intuit/auto) - Generate releases based on semantic version labels on pull requests -- [microsoft/beachball](https://github.com/microsoft/beachball) - The Sunniest Semantic Version Bumper - -## Understanding Changesets - -We recommend taking a look at the Changesets docs. Here's our recommended reading order: - -1. [Why use changesets?](https://github.com/changesets/changesets/blob/main/docs/intro-to-using-changesets.md) - an intro that takes you through the fundamentals. -1. [Installation instructions](https://github.com/changesets/changesets/blob/main/packages/cli/README.md) -1. If you're using GitHub, consider using the [Changeset GitHub bot](https://github.com/apps/changeset-bot) - a bot to nudge you to add changesets to PR's. -1. You should also consider adding the [Changesets GitHub action](https://github.com/changesets/action) - a tool which makes publishing extremely easy. - -## Using Changesets with Turborepo - -Once you've started using Changesets, you'll gain access to three useful commands: - -```bash -# Add a new changeset -changeset - -# Create new versions of packages -changeset version - -# Publish all changed packages to npm -changeset publish -``` - -Linking your publishing flow into Turborepo can make organising your deploy a lot simpler and faster. - -Our recommendation is to add a `publish-packages` script into your root `package.json`: - -```json filename="package.json" -{ - "scripts": { - // Include build, lint, test - all the things you need to run - // before publishing - "publish-packages": "turbo run build lint test && changeset version && changeset publish" - } -} -``` - - - We recommend `publish-packages` so that it doesn't conflict with npm's - built-in `publish` script. - - -This means that when you run `publish-packages`, your monorepo gets built, linted, tested and published - and you benefit from all of Turborepo's speedups. diff --git a/docs/pages/repo/docs/handbook/sharing-code.mdx b/docs/pages/repo/docs/handbook/sharing-code.mdx deleted file mode 100644 index 9cdf783..0000000 --- a/docs/pages/repo/docs/handbook/sharing-code.mdx +++ /dev/null @@ -1,71 +0,0 @@ -import Callout from "../../../../components/Callout"; - -# Sharing Code in a monorepo - -Monorepos let you share code across applications without friction. To do that, you'll be building **packages** to share code between your apps. - -## What is a package? - -The word 'package' has a double meaning when it comes to monorepos. It can refer to either of these: - -1. A set of files you download from a registry into your `node_modules`, via a package manager like `npm`. -2. A workspace containing code that can be shared between applications - by convention usually inside `/packages`. - -This dual meaning can be very confusing to folks new to the monorepo scene. You're likely very familiar with [package installation](/repo/docs/handbook/package-installation), but not so familiar with [workspaces](/repo/docs/handbook/workspaces). - -The fact is that they're very similar. A package is just a piece of shared code. Except that _installed packages_ live in your `node_modules`, and _local packages_ lives in a workspace - likely in your `/packages` folder. - -## Anatomy of a package - -Each package contains a `package.json`. You're likely familiar with using these to manage dependencies and scripts in your applications. - -However, you may not have noticed the `main` and `name` fields before: - -```jsonc filename="packages/my-lib/package.json" -{ - // The name of your package - "name": "my-lib", - - // When this package is used, this file is actually - // the thing that gets imported - "main": "./index.js" -} -``` - -Both of these fields are important for deciding **how this package behaves when it's imported**. For instance, if `index.js` has some exports: - -```js filename="packages/my-lib/index.js" -export const myFunc = () => { - console.log("Hello!"); -}; -``` - -And we import this file into one of our apps: - -```ts filename="apps/web/pages/index.jsx" -import { myFunc } from "my-lib"; - -myFunc(); // Hello! -``` - -Then we'll be able to use the code inside the `my-lib` folder inside our applications. - -To summarize, **each package must have a `name` and a `main`** declared inside its `package.json`. - - - -Package resolution in `package.json` is a very complicated topic, and we can't do justice to it here. Other fields in your `package.json` may take precedence over `main` depending on how the package is being imported. - -Check the [npm docs](https://docs.npmjs.com/cli/v8/configuring-npm/package-json/#main) for a guide. - -For our purposes, using `main` will be good enough. - - - -## Next steps - -We're going to introduce two styles of packages - **internal** packages and **external** packages: - -[**Internal** packages](/repo/docs/handbook/sharing-code/internal-packages) are intended to only be used inside the monorepo where they're housed. They are relatively simple to set up, and if your project is closed source they will be the most useful to you. - -[**External** packages](/repo/docs/handbook/publishing-packages) are bundled and sent to a package registry. This is useful for design systems, shared utility libraries or any open source work. However, they introduce more complexity around bundling, versioning and publishing. diff --git a/docs/pages/repo/docs/handbook/sharing-code/_meta.json b/docs/pages/repo/docs/handbook/sharing-code/_meta.json deleted file mode 100644 index b1305a2..0000000 --- a/docs/pages/repo/docs/handbook/sharing-code/_meta.json +++ /dev/null @@ -1,3 +0,0 @@ -{ - "internal-packages": "Internal Packages" -} diff --git a/docs/pages/repo/docs/handbook/sharing-code/internal-packages.mdx b/docs/pages/repo/docs/handbook/sharing-code/internal-packages.mdx deleted file mode 100644 index 29efd56..0000000 --- a/docs/pages/repo/docs/handbook/sharing-code/internal-packages.mdx +++ /dev/null @@ -1,237 +0,0 @@ -import Callout from "../../../../../components/Callout"; - -import { Tabs, Tab } from "../../../../../components/Tabs"; - -# Internal Packages - -Internal packages are [packages](/repo/docs/handbook/sharing-code) which are only intended to be used _inside_ your monorepo. They're extremely useful for sharing code between apps in closed-source monorepos. - -Internal packages are quick to create, and can be turned into [external packages](/repo/docs/handbook/publishing-packages) if you end up wanting to publish them to `npm`. - -## What makes a package _internal?_ - -External packages **run their files through a bundler** before putting them on a package registry. This means they need a _lot_ of tooling to handle. - -- **Bundlers**: to build the package -- **Versioning**: to help with versioning and releases -- **Publishing**: to publish the package - -If you want to use those files locally, you'll also need: - -- **Dev scripts**: for bundling the package locally when files change - -Because internal packages are not published, we can skip _all_ of these steps. Instead of bundling our package ourselves, we're going to make the **app which imports the package bundle it for us**. - -This sounds complex, but it's extremely easy to set up. - -## Our first internal package - -We're going to create a shared `math-helpers` package inside our monorepo. - -### 1. Create your monorepo - -If you don't have an existing monorepo, create one [using our guide](/repo/docs/getting-started/create-new). - -### 2. Create a new package - -Inside `/packages`, create a new folder called `math-helpers`. - -```bash -mkdir packages/math-helpers -``` - -Create a `package.json`: - -```json filename="packages/math-helpers/package.json" -{ - "name": "math-helpers", - "dependencies": { - // Use whatever version of TypeScript you're using - "typescript": "latest" - } -} -``` - -Create a `src` folder, and add a TypeScript file at `packages/math-helpers/src/index.ts`. - -```ts filename="packages/math-helpers/src/index.ts" -export const add = (a: number, b: number) => { - return a + b; -}; - -export const subtract = (a: number, b: number) => { - return a - b; -}; -``` - -You'll also need to add a `tsconfig.json` at `packages/math-helpers/tsconfig.json`: - -```json filename="packages/math-helpers/tsconfig.json" -{ - "compilerOptions": { - "esModuleInterop": true, - "forceConsistentCasingInFileNames": true, - "isolatedModules": true, - "moduleResolution": "node", - "preserveWatchOutput": true, - "skipLibCheck": true, - "noEmit": true, - "strict": true - }, - "exclude": ["node_modules"] -} -``` - -Great! We've now got all the files we need for our internal package. - -### 3. Import the package - -We're now going to import the package and see what happens. Go into one of your apps, and add `math-helpers` into the dependencies of its package.json: - - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "math-helpers": "*" - } -} -``` - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "math-helpers": "*" - } -} -``` - - -```jsonc filename="apps/web/package.json" -{ - "dependencies": { - "math-helpers": "workspace:*" - } -} -``` - - - -[Install all packages from root](/repo/docs/handbook/package-installation) to ensure that dependency works. - -Now add an import from `math-helpers` into one of your app's source files: - -```diff -+ import { add } from "math-helpers"; - -+ add(1, 2); -``` - -You'll likely see an error! - -``` -Cannot find module 'math-helpers' or its corresponding type declarations. -``` - -That's because we've missed a step. We haven't told our `math-helpers/package.json` what the entry point to our package is. - -### 4. Fix `main` and `types` - -Go back to `packages/math-helpers/package.json` and add two fields, `main` and `types`: - -```json filename="packages/math-helpers/package.json" -{ - "name": "math-helpers", - "main": "src/index.ts", - "types": "src/index.ts", - "dependencies": { - "typescript": "latest" - } -} -``` - -Now, anything that imports our `math-helpers` module will be pointed directly towards the `src/index.ts` file - _that's_ the file that they will import. - -Go back to `apps/web/pages/index.tsx`. The error should be gone! - -### 5. Try running the app - -Now, try running that app's dev script. In the default turborepo, this will be as easy as: - -```bash -turbo dev -``` - - - - -When it starts running, you'll likely see an error in your web browser: - -``` -../../packages/math-helpers/src/index.ts -Module parse failed: Unexpected token (1:21) -You may need an appropriate loader to handle this file type, -currently no loaders are configured to process this file. -See https://webpack.js.org/concepts#loaders - -> export const add = (a: number, b: number) => { -| return a + b; -| }; -``` - -This is what happens when you try and import an un-bundled file into a Next.js app. - -The fix is simple - we need to tell Next.js to bundle the files from certain packages it imports. - - - - Because `vite` transpiles modules by default, there's no more setup needed! Skip to step 7. - - - -### 6. Configuring your app - - - - - We can do that using `transpilePackages` in `next.config.js` (requires v13.1+): - - ```ts filename="apps/web/next.config.js" - /** @type {import('next').NextConfig} */ - const nextConfig = { - transpilePackages: ['math-helpers'], - }; - - module.exports = nextConfig; - ``` - - Restart your dev script, and go to the browser. - - **The error has disappeared!** - - - - No configuration is needed! - - - -### 7. Summary - -We are now able to add any amount of code into our `math-helpers` package, and use it in any app in our monorepo. We don't even need to build our package - it just works. - -This pattern is extremely powerful for creating pieces of code that can be easily shared between teams. - -### Quick Reference - -#### Quick reference - creating a new internal package - -1. Create a new folder in `packages/` -1. Add a `package.json`, with `name` and `types` pointing at `src/index.ts` (or `src/index.tsx`) -1. Add `src/index.tsx`, with at least one named export -1. [Install your packages](/repo/docs/handbook/package-installation) from root - -#### Quick reference - importing an internal package - -1. Ensure that you're [importing it correctly](/repo/docs/handbook/sharing-code/internal-packages#3-import-the-package) -2. Ensure that you've [configured your app to transpile it](/repo/docs/handbook/sharing-code/internal-packages#6-configuring-your-app) diff --git a/docs/pages/repo/docs/handbook/testing.mdx b/docs/pages/repo/docs/handbook/testing.mdx deleted file mode 100644 index a63ca72..0000000 --- a/docs/pages/repo/docs/handbook/testing.mdx +++ /dev/null @@ -1,109 +0,0 @@ -import { Tabs, Tab } from "../../../../components/Tabs"; -import Callout from "../../../../components/Callout"; - -# Testing in a Monorepo - -Along with linting and building, testing is a crucial part of a production-ready monorepo. Whether you're using end-to-end tests or a unit test suite, integrating them with Turborepo will lead to enormous speed-ups. - -## Working with test runners - -Let's say we have a monorepo that looks like this: - -``` -├── apps -│ └── web -│ └── package.json -└── packages - └── shared - └── package.json -``` - -Both `apps/web` and `packages/shared` have their own test suite. Their `package.json` files look like this: - - - -```json filename="apps/web/package.json" -{ - "scripts": { - "test": "jest" - } -} -``` - - -```json filename="apps/web/package.json" -{ - "scripts": { - "test": "vitest run" - } -} -``` - - - -Inside the root `turbo.json`, we recommend setting up a `test` task in your [pipeline](/repo/docs/core-concepts/monorepos/running-tasks): - -```json filename="turbo.json" -{ - "pipeline": { - "test": {} - } -} -``` - -Now, you can run `turbo test` and have Turborepo test the entire repository. - -Because of Turborepo's [caching](/repo/docs/core-concepts/caching), this also means that only repositories that have changed files will be tested - resulting in a lot of time saved. - -## Running tests in watch mode - -When you run your test suite normally, it completes and outputs to `stdout`. This means you can [cache it](/repo/docs/core-concepts/caching) with Turborepo. - -But when you run your tests in watched mode, the process never exits. This makes a watch task more like a [development task](/repo/docs/handbook/dev). - -Because of this difference, we recommend specifying **two separate Turborepo tasks**: one for running your tests, and one for running them in watch mode. - -Here's an example: - - - -```json filename="apps/web/package.json" -{ - "scripts": { - "test": "jest", - "test:watch": "jest --watch" - } -} -``` - - -```json filename="apps/web/package.json" -{ - "scripts": { - "test": "vitest run", - "test:watch": "vitest" - } -} -``` - - - -```json filename="turbo.json" -{ - "pipeline": { - "test": {}, - "test:watch": { - "cache": false - } - } -} -``` - -```json filename="package.json" -{ - "scripts": { - "test": "turbo run test", - "test:watch": "turbo run test:watch" - } -} -``` diff --git a/docs/pages/repo/docs/handbook/tools/_meta.json b/docs/pages/repo/docs/handbook/tools/_meta.json deleted file mode 100644 index 2a0e55f..0000000 --- a/docs/pages/repo/docs/handbook/tools/_meta.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "prisma": "Prisma", - "storybook": "Storybook" -} diff --git a/docs/pages/repo/docs/handbook/tools/prisma.mdx b/docs/pages/repo/docs/handbook/tools/prisma.mdx deleted file mode 100644 index 11e589d..0000000 --- a/docs/pages/repo/docs/handbook/tools/prisma.mdx +++ /dev/null @@ -1,207 +0,0 @@ -import { Tabs, Tab } from '../../../../../components/Tabs' -import Callout from '../../../../../components/Callout' - -# Using Prisma with Turborepo - -[Prisma](https://www.prisma.io/) is an extremely popular ORM with automated migrations, type safety and integrated tooling. Using it with Turborepo can cut time you spend generating code, and easily make sure your generated Prisma code is always up-to-date. - -## Guide - -This guide shows you how to: - -1. Set up Prisma in a monorepo -2. Handle migration and code generation scripts -3. Cache those scripts with Turborepo -4. Ensure that they're always run whenever `dev` or `build` is run - -If you've already got Prisma set up in your database, you can skip to [step 4](#4-setting-up-the-scripts). - -### 1. Create your monorepo - -If you don't have an existing project, use our [quickstart](/repo/docs/getting-started/create-new) to create a new monorepo. - -### 2. Add a new `database` package - -Create a new folder called `database` inside packages with a `package.json` inside: - -```json filename="packages/database/package.json" -{ - "name": "database", - "dependencies": { - "@prisma/client": "latest" - }, - "devDependencies": { - // Replace "latest" with the latest version - "prisma": "latest" - } -} -``` - -If you're using `pnpm`, you should add a file at the root called `.npmrc`: - -```txt filename=".npmrc" -public-hoist-pattern[]=*prisma* -``` - -Run your package manager's install step to install the new dependencies. - -### 3. Run `prisma init` - -`cd` into `packages/database`: - -```bash -cd packages/database -``` - -Run `npx prisma init`. - -This should create several files inside `packages/database`: - -``` -prisma/schema.prisma -.gitignore -.env -``` - -- `schema.prisma` is where your [Prisma schema](https://www.prisma.io/docs/concepts/components/prisma-schema) lives. Here, you'll be able to modify the shape of your database. -- `.gitignore` adds some ignored files to git -- `.env` lets you manually specify your `DATABASE_URL` for prisma. - -At this point, you should refer to the Prisma docs for [connecting your database to Prisma](https://www.prisma.io/docs/getting-started/setup-prisma/start-from-scratch/relational-databases/connect-your-database-typescript-postgres). - -Once you've got a database connected, you can move on. - -### 4. Setting up the scripts - -Let's add some scripts to the `package.json` inside `packages/database`: - -```json filename="packages/database/package.json" -{ - "scripts": { - "db:generate": "prisma generate", - "db:push": "prisma db push --skip-generate" - } -} -``` - -Let's also add these scripts to `turbo.json` in the root: - -```json filename="turbo.json" -{ - "pipeline": { - "db:generate": { - "cache": false - }, - "db:push": { - "cache": false - } - } -} -``` - -We can now run `turbo db:push db:generate` from the root of our repository to automatically migrate our database and generate our type safe Prisma client. - - - We use the `--skip-generate` flag on `db:push` to ensure it doesn't automatically run `prisma generate` after migrating the database. This ends up being faster when using Turborepo because we automatically parallelize the tasks. - - -### 5. Exporting your client - -Next, we need to export the `@prisma/client` so we can use it in our applications. Let's add a new file to `packages/database`: - -```ts filename="packages/database/index.ts" -export * from '@prisma/client'; -``` - -Following the [internal packages pattern](/repo/docs/handbook/sharing-code/internal-packages), we'll also need to add `index.ts` to `main` and `types` inside `packages/database/package.json`. - -```json filename="packages/database/package.json" -{ - "main": "./index.ts", - "types": "./index.ts" -} -``` - -#### Importing `database` - -Let's now import our database package into one of our apps to test it out. Let's say you have an app at `apps/web`. Add the dependency to `apps/web/package.json`: - - - - ```json filename="apps/web/package.json" - { - "dependencies": { - "database": "*" - } - } - ``` - - - ```json filename="apps/web/package.json" - { - "dependencies": { - "database": "*" - } - } - ``` - - - ```json filename="apps/web/package.json" - { - "dependencies": { - "database": "workspace:*" - } - } - ``` - - - -Run your package manager's install command. - -You can now import `PrismaClient` from `database` anywhere in your app: - -```ts -import { PrismaClient } from 'database' - -const client = new PrismaClient(); -``` - - - You may also need to do some configuration inside your application to allow it to run an internal package. Check out our [internal packages docs](/repo/docs/handbook/sharing-code/internal-packages#6-configuring-your-app) for more info. - - -### 6. Figuring out the scripts - -We're now in a pretty good position. We have a reusable `database` module that we can import into any of our applications. We've got a `turbo db:push` script we can use to push our changes to the database. - -However, our `db:generate` scripts aren't optimized yet. They provide crucial code to our `dev` and `build` tasks. If a new developer runs `dev` on an application without running `db:generate` first, they'll get errors. - -So, let's make sure that `db:generate` is always run _before_ the user runs `dev`: - -```json filename="turbo.json" -{ - "pipeline": { - "dev": { - "dependsOn": ["^db:generate"], - "cache": false - }, - "build": { - "dependsOn": ["^db:generate"], - "outputs": ["your-outputs-here"] - }, - "db:generate": { - "cache": false - } - } -} -``` - -Check out the section on [running tasks](/repo/docs/core-concepts/monorepos/running-tasks) to learn more about the `^db:generate` syntax. - -### 7. Caching the results of `prisma generate` - -`prisma generate` outputs files to the filesystem, usually inside `node_modules`. In theory, it should be possible to cache the output of `prisma generate` with Turborepo to save a few seconds. - -However, Prisma behaves differently with different package managers. This can lead to unpredictable results, which might lead to broken deployments in some situations. Instead of documenting the intricacies of each approach, we recommend _not_ caching the results of `prisma generate`. Since `prisma generate` usually only takes 5-6 seconds, and tends not to take longer with larger `schema` files, this seems like a fine trade-off. - -You may wish to experiment with this yourself. If you find a solution that you feel works, feel free to [add an issue](https://github.com/vercel/turbo/issues/new/choose) and we can update this section. diff --git a/docs/pages/repo/docs/handbook/tools/storybook.mdx b/docs/pages/repo/docs/handbook/tools/storybook.mdx deleted file mode 100644 index 008b8ba..0000000 --- a/docs/pages/repo/docs/handbook/tools/storybook.mdx +++ /dev/null @@ -1,223 +0,0 @@ -import { Tabs, Tab } from '../../../../../components/Tabs' -import Callout from '../../../../../components/Callout' - -# Using Storybook with Turborepo - -[Storybook](https://storybook.js.org/) is a popular way to build UI components in an isolated environment. By putting Storybook into your Turborepo, you can easily develop your design system right alongside your applications. If you'd rather use a template, this guide is walking through how to build [this Storybook/Turborepo template](https://vercel.com/templates/react/turborepo-design-system) on Vercel. - -## Guide - -This guide shows you how to: - -1. Set up Storybook in a monorepo -2. Create your first story -3. Ensure Storybook works with the rest of your tasks - -### 1. Create your monorepo - -If you don't have an existing project, use our [quickstart](/repo/docs/getting-started/create-new) to create a new monorepo. - -```shell -npx create-turbo@latest -``` - -### 2. Add a new `workshop` app - -Storybook needs a builder to use so we will create a Vite app. - - - - ```shell - cd apps - npm create vite - ``` - - - ```shell - cd apps - yarn create vite - ``` - - - ```shell - cd apps - pnpm create vite - ``` - - - -Follow the prompts to create an app named "workshop" as a React, TypeScript app. - -Next, we need to scaffold Storybook: - - - - ```shell - cd workshop - npx sb init --skip-install - npm install --save-dev @storybook/cli # Manually install deps and CLI - ``` - - You may be prompted to enable the `--legacy-peer-deps` flag. This flag is required for Storybook to work in a monorepo. - - - - ```shell - cd workshop - npx storybook init - ``` - - -

If you're using `pnpm`, you'll need to add an `.npmrc` at the root of your monorepo:

- ```txt filename=".npmrc" - auto-install-peers=true - legacy-peer-deps=true - node-linker=hoisted - ``` - Then, we scaffold Storybook and install its dependencies manually: - - ```shell - cd workshop - pnpx sb init --skip-install - pnpm install --save-dev @storybook/cli # Manually install deps and CLI - ``` - - - - -### 3. Set up a story for your Button component - -The Storybook scaffold creates some stories and React components in the `/src/stories` directory. To create a story for the button from your `ui` package, we will replace the import in `Button.stories.tsx` with our own. - -1. Update the Button in your `ui` package to match the story's specifications. - -```jsx filename="packages/ui/Button.tsx" -interface Props { - primary?: boolean; - size?: "small" | "large"; - label?: string; -} - -export const Button = ({ - primary = false, - label = "Boop", - size = "small", -}: Props) => { - return ( - - ); -}; -``` - -2. Add your `ui` package to the `workshop` app: - - - -```json filename="apps/workshop/package.json" -{ - // ... - { - "dependencies": { - "ui": "*", - // ... - } - } -} -``` - -And `npm install` one more time to make sure that your `ui` package is installed in the `workshop` app. - - - -```json filename="apps/workshop/package.json" -{ - // ... - { - "dependencies": { - "ui": "*", - // ... - } - } -} -``` - -And `yarn install` to make sure that your `ui` package is installed in the `workshop` app. - - - -```json filename="apps/workshop/package.json" -{ - // ... - { - "dependencies": { - "ui": "workspace:*", - // ... - } - } -} -``` -And `pnpm install` one more time to make sure that your `ui` package is installed in the `workshop` app. - - - -3. Replace the `Button` import in the `Button.stories.tsx` so that it comes from your `ui` package: - -```jsx filename="apps/workshop/src/stories/Button.stories.tsx" -import { Button } from 'ui' -``` - -### 4. Align tasks - -The last thing that we need to do is make sure that Storybook is lined up with the rest of your tasks: - -```json filename="apps/workshop/package.json" -{ - // ... - "scripts": { - "dev": "start-storybook -p 6006", - "build": "build-storybook" - } -} -``` - -To ensure build caching, you'll first need to add `storybook-static` to your `.gitignore`. Then, add `storybook-static` to the outputs of your `turbo.json` build task: - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": [ - "dist/**", -+ "storybook-static/**" - ] - } - } -} -``` - -Your `dev` and `build` tasks will now include Storybook, allowing you to develop your Storybook alongside your applications and enjoy cached builds with the rest of your applications. - -## Deploy on Vercel - -Let's deploy your Storybook project. - -In the "Build and Development Settings" on the General tab of your project settings, change your "Output Directory" to `storybook-static`. - -Additionally, at the time of this writing, Storybook cannot be ran on Node 18, the Vercel default. In the `package.json` of your `workshop` app, add an `engines` field to make sure that this project runs on Node 16: - -```json filename="apps/workshop/package.json" -{ - // ... - "engines": { - "node": "16" - } -} - -``` diff --git a/docs/pages/repo/docs/handbook/troubleshooting.mdx b/docs/pages/repo/docs/handbook/troubleshooting.mdx deleted file mode 100644 index fd88afd..0000000 --- a/docs/pages/repo/docs/handbook/troubleshooting.mdx +++ /dev/null @@ -1,31 +0,0 @@ -# Troubleshooting - -## Handling mismatched package versions - -As your monorepo grows, you may end up with different versions of packages in different workspaces. - -For instance, `app` may use `react@18.0.0`, but `web` may use `react@17.0.0`. This is especially true when you've just [migrated from a multi-repo setup](/repo/docs/handbook/migrating-to-a-monorepo). - -Mis-matched dependencies in different repositories can mean that code runs unexpectedly. React, for instance, will error if there is more than one version installed. - -#### `@manypkg/cli` - -Our recommended method for handling this problem is with [`@manypkg/cli`](https://www.npmjs.com/package/@manypkg/cli) - a CLI which can ensure that your dependencies match across your repositories. - -Here's a quick example. At the root of your `package.json`, add a `postinstall` script. - -```json filename="package.json" -{ - "scripts": { - // This will check your dependencies match - // after each installation - "postinstall": "manypkg check" - }, - "dependencies": { - // Make sure you install @manypkg/cli - "@manypkg/cli": "latest" - } -} -``` - -You can also run `manypkg fix` to automatically update them throughout your repository. diff --git a/docs/pages/repo/docs/handbook/what-is-a-monorepo.mdx b/docs/pages/repo/docs/handbook/what-is-a-monorepo.mdx deleted file mode 100644 index 0a3b916..0000000 --- a/docs/pages/repo/docs/handbook/what-is-a-monorepo.mdx +++ /dev/null @@ -1,85 +0,0 @@ -import { Tabs, Tab } from "../../../../components/Tabs"; - -# What is a Monorepo? - -A monorepo is a collection of many different apps and packages in a single codebase. - -The alternative setup is called **a polyrepo** - multiple codebases which are published and versioned separately. - -## Sharing code - -### In a polyrepo - -In a polyrepo setup, the process for sharing code between applications is relatively lengthy. - -Imagine that you have three separate repositories - `app`, `docs`, and `shared-utils`. Both `app` and `docs` depend on `shared-utils`, which is published as a package on npm. - -Let's say a bug in `shared-utils` is causing a critical issue in both `app` and `docs`. You'll need to: - -1. Make a commit in `shared-utils` fixing the error -2. Run a `publish` task inside `shared-utils` to publish it to npm -3. Make a commit in `app` bumping the version of the `shared-utils` dependency -4. Make a commit in `docs` bumping the version of the `shared-utils` dependency -5. `app` and `docs` are now ready to be deployed. - -The more apps you have that depend on `shared-utils`, the longer this process takes. It can be extremely arduous. - -### In a monorepo - -In a monorepo setup, `shared-utils` would be _in the same codebase_ as `app` and `docs`. This makes the process very simple: - -1. Make a commit in `shared-utils` fixing the error -2. `app` and `docs` are now ready to be deployed. - -No versioning is required, because `app` and `docs` don't depend on the version of `shared-utils` in npm - they depend on the **version that's in the codebase**. - -This makes it possible to create single commits which fix bugs in multiple apps and packages at once. This can be an enormous gain in speed for teams. - -## How do monorepos work? - -The main building block of the monorepo is the [workspace](/repo/docs/handbook/workspaces). Each application and package you build will be in its own workspace, with its own `package.json`. As you'll learn from our guide, workspaces can **depend on each other**, meaning your `docs` workspace can depend on `shared-utils`: - - - - -```json filename="apps/docs/package.json" -{ - "dependencies": { - "shared-utils": "*" - } -} -``` - - - -```json filename="apps/docs/package.json" -{ - "dependencies": { - "shared-utils": "*" - } -} -``` - - - - -```json filename="apps/docs/package.json" -{ - "dependencies": { - "shared-utils": "workspace:*" - } -} -``` - - - - -Workspaces are managed by the same CLI which [installs your dependencies](/repo/docs/handbook/package-installation). - -### The root workspace - -You'll also have a root workspace - a `package.json` in the root folder of your codebase. This is a useful place for: - -1. Specifying dependencies which are present across your entire monorepo -1. Adding tasks that operate on the _whole_ monorepo, not just individual workspaces -1. Adding documentation on how to use the monorepo diff --git a/docs/pages/repo/docs/handbook/workspaces.mdx b/docs/pages/repo/docs/handbook/workspaces.mdx deleted file mode 100644 index 903021f..0000000 --- a/docs/pages/repo/docs/handbook/workspaces.mdx +++ /dev/null @@ -1,168 +0,0 @@ -import Callout from "../../../../components/Callout"; -import HeartIcon from "@heroicons/react/solid/HeartIcon"; -import { Tabs, Tab } from "../../../../components/Tabs"; - -# Workspaces - -Workspaces are the building blocks of your monorepo. Each app and package you add to your monorepo will be **inside its own workspace**. - -Workspaces are managed by your [package manager](/repo/docs/handbook/package-installation), so make sure you've set that up first. - -## Configuring workspaces - -To use workspaces, you must first declare their file system locations to your package manager. - -A common convention we recommend is having top-level `apps/` and `packages/` directories. This isn't a requirement - just a suggested directory structure. - -The `apps` folder should contain workspaces for launchable apps, such as a [Next.js](https://nextjs.org/) or [Svelte](https://svelte.dev/) app. - -The `packages` folder should contain workspaces for packages used by either an app or another package. - - - - - Add the folders you want to configure as workspaces to the `workspaces` field in your root `package.json` file. This field contains a list of workspace folders in the form of globs: - - ```json - { - "name": "my-monorepo", - "version": "1.0.0", - "workspaces": [ - "docs", - "apps/*", - "packages/*" - ] - } - ``` - - - - - Add the folders you want to configure as workspaces to the `workspaces` field in your root `package.json` file. This field contains a list of workspace folders in the form of globs: - - ```json - { - "name": "my-monorepo", - "version": "1.0.0", - "workspaces": [ - "docs", - "apps/*", - "packages/*" - ] - } - ``` - - - - - - Add the folders you want to configure as workspaces to the `pnpm-workspace.yaml` file that exists in your root directory. This file contains a list of workspace folders in the form of globs: - - ```yaml - packages: - - "docs" - - "apps/*" - - "packages/*" - ``` - - - - -``` -my-monorepo -├─ docs -├─ apps -│ ├─ api -│ └─ mobile -├─ packages -│ ├─ tsconfig -│ └─ shared-utils -└─ sdk -``` - -In the example above, all directories inside `my-monorepo/apps/` and `my-monorepo/packages/` are workspaces, and the `my-monorepo/docs` directory itself is also a workspace. `my-monorepo/sdk/` is _not_ a workspace, as it is not included in the workspace configuration. - -## Naming workspaces - -Each workspace has a unique name, which is specified in its `package.json`: - -```json filename="packages/shared-utils/package.json" -{ - "name": "shared-utils" -} -``` - -This name is used to: - -1. Specify which workspace a [package should be installed to](/repo/docs/handbook/package-installation) -1. Use this workspace in other workspaces -1. [Publish packages](/repo/docs/handbook/publishing-packages): it'll be published on npm under the `name` you specify - -You can use an npm organization or user scope to avoid collisions with existing packages on npm. For instance, you could use `@mycompany/shared-utils`. - -## Workspaces which depend on each other - -To use a workspace inside another workspace, you'll need to specify it as a dependency, using its name. - -For instance, if we want `apps/docs` to import `packages/shared-utils`, we'd need to add `shared-utils` as a dependency inside `apps/docs/package.json`: - - - - -```json filename="apps/docs/package.json" -{ - "dependencies": { - "shared-utils": "*" - } -} -``` - - - -```json filename="apps/docs/package.json" -{ - "dependencies": { - "shared-utils": "*" - } -} -``` - - - - -```json filename="apps/docs/package.json" -{ - "dependencies": { - "shared-utils": "workspace:*" - } -} -``` - - - - - - The `*` allows us to reference the _latest_ version of the dependency. It - saves us from needing to bump the versions of our dependency if the versions - of our packages change. - - -Just like a normal package, we'd need to run `install` from root afterwards. Once installed, we can use the workspace as if it were any other package from `node_modules`. See our [section on sharing code](/repo/docs/handbook/sharing-code) for more information. - -## Managing workspaces - -In a monorepo, when you run an `install` command from root, a few things happen: - -1. The workspace dependencies you have installed are checked -1. Any workspaces are [symlinked](https://en.wikipedia.org/wiki/Symbolic_link) into `node_modules`, meaning that you can import them like normal packages -1. Other packages are downloaded and installed into `node_modules` - -This means that whenever you add/remove workspaces, or change their locations on the filesystem, you'll need to re-run your `install` command from root to set up your workspaces again. - - - You **don't need to re-install every time your source code changes** inside a - package - only when you change the locations (or configuration) of your - workspaces in some way. - - -If you run into issues, you may have to delete each `node_modules` folder in your repository and re-run `install` to correct it. diff --git a/docs/pages/repo/docs/index.mdx b/docs/pages/repo/docs/index.mdx deleted file mode 100644 index 04f6fcf..0000000 --- a/docs/pages/repo/docs/index.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: Turborepo Quickstart -description: Create your first monorepo or add Turborepo to an existing project. ---- - -import { readdirSync, lstatSync, readFileSync } from 'fs'; -import path from 'path'; -import { QuickStartArea, LearnMoreArea, MonoreposArea } from "../../../components/QuickStart"; -import { ExamplesArea } from "../../../components/ExamplesArea"; -import FullTurboCTA from "../../../components/FullTurboCTA"; - -export const getStaticProps = ({ params }) => { - // path to examples directory at the monorepo root. - const examplesDirectory = path.join(__dirname, '../../../../../examples') - const examples = []; - readdirSync(examplesDirectory).forEach(file => { - if (lstatSync(path.join(examplesDirectory, file)).isDirectory()) { - try { - examples.push({ - slug: file, - ...JSON.parse(readFileSync(path.join(examplesDirectory, file, "meta.json")).toString()) - } - ); - } catch (err) { - console.log(`No meta.json found for ${file}, excluding from docs`); - } - } - }); - // throw an error if no examples are found - if (examples.length === 0) { - throw new Error( - `No examples found in ${examplesDirectory}! Make sure you have updated the path if moving this file.` - ) - } - return { - props: { - ssg: { - examples - } - }, - revalidate: 60 * 60 * 24 - } -} - -# Turborepo Quickstart - -Turborepo is an intelligent **build system optimized for JavaScript and TypeScript codebases**. - -Your codebase's tasks - like `lint`, `build` and `test` - **don't run as fast as they could**. Turborepo uses [caching](/repo/docs/core-concepts/caching) to turbocharge your local setup and speed up your CI. - -Turborepo is designed to be **incrementally adopted**, so you can add it to most codebases in a few minutes. - - - -## Features - -Turborepo leverages advanced build system techniques to speed up development, **both on your local machine and your CI/CD**. - - - -## Monorepos - -Turborepo works out-of-the-box with monorepo tools like `npm`, `pnpm` and `yarn`. If you've ever felt that your monorepo slowed you down, it might be time for Turborepo. - - - -## Examples - -You can also clone a Turborepo starter repository to get a head start on your monorepo. For even more examples and starters, see the [Turborepo examples directory on GitHub](https://github.com/vercel/turbo/tree/main/examples). - - - - diff --git a/docs/pages/repo/docs/installing.mdx b/docs/pages/repo/docs/installing.mdx deleted file mode 100644 index cc1e9c2..0000000 --- a/docs/pages/repo/docs/installing.mdx +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Installing Turborepo -description: Learn how to install Turborepo for use with your repository ---- - -import Callout from "../../../components/Callout"; -import { Tabs, Tab } from '../../../components/Tabs' - -# Install Turborepo - -`turbo` works with [yarn](https://classic.yarnpkg.com/lang/en/), [npm](https://www.npmjs.com/), and [pnpm](https://pnpm.io/) on the following operating systems: - -- macOS darwin 64-bit (Intel), ARM 64-bit (Apple Silicon) -- Linux 64-bit, ARM 64-bit -- Windows 64-bit, ARM 64-bit - - - Note: Linux builds of `turbo` link against `glibc`. For Alpine Docker environments, you will need to ensure libc6-compat is installed as well, via `RUN apk add --no-cache libc6-compat` - - -## Install Globally - -A global install of `turbo` can be used in any project, and enables automatic workspace -selection based on the directory where you run `turbo`. - - - - ```bash - npm install turbo --global - ``` - - - ```bash - yarn global add turbo - ``` - - - ```bash - pnpm install turbo --global - ``` - - - -Once you have a globally installed copy of `turbo`, you will be able to run directly from workspace -directories. - -```bash -cd /apps/docs -turbo build -``` - -is equivalent to the [filtering syntax](../docs/core-concepts/monorepos/filtering): - -```bash -cd -turbo build --filter=docs -``` - -## Install Per Repository - -You may wish to pin the version of Turborepo used within a repository, especially [if you are -collaborating with other developers](../docs/core-concepts/remote-caching). In that case, add `turbo` as a dev dependency at the root -of the repository: - - - - ```bash - npm install turbo --dev - ``` - - - ```bash - yarn add turbo --dev --ignore-workspace-root-check - ``` - - - ```bash - pnpm add turbo --save-dev --ignore-workspace-root-check - ``` - - - -You can continue to use your global install of `turbo`, which will defer to your local version -if it exists. This allows you to get the best of both worlds: easy scoping to the directory you're working -in while maintaining a pinned version among your entire team. diff --git a/docs/pages/repo/docs/reference/_meta.json b/docs/pages/repo/docs/reference/_meta.json deleted file mode 100644 index 9ed1477..0000000 --- a/docs/pages/repo/docs/reference/_meta.json +++ /dev/null @@ -1,5 +0,0 @@ -{ - "configuration": "Configuration Options", - "command-line-reference": "CLI Usage", - "codemods": "Codemods" -} diff --git a/docs/pages/repo/docs/reference/codemods.mdx b/docs/pages/repo/docs/reference/codemods.mdx deleted file mode 100644 index ac4cbee..0000000 --- a/docs/pages/repo/docs/reference/codemods.mdx +++ /dev/null @@ -1,278 +0,0 @@ ---- -title: Turborepo Codemods -description: To make upgrading easier, Turborepo includes codemods and migration scripts. ---- - -import Callout from '../../../../components/Callout' - -# Turborepo Codemods - -Turborepo provides Codemod transformations and automatic migration scripts to help upgrade your Turborepo codebase when a feature is deprecated. - -Codemods are transformations that run on your codebase programmatically. This allows for a large amount of changes to be applied without having to manually go through every file. - -## Usage - -```sh -npx @turbo/codemod -``` - -- `transform` - name of transform, see available transforms below. -- `path` - files or directory to transform -- `--dry` - Do a dry-run, no code will be edited -- `--print` - Prints the changed output for comparison - -## Turborepo 1.x - -1. [add-package-manager](#add-package-manager) -2. [create-turbo-config](#create-turbo-config) -3. [migrate-env-var-dependencies](#migrate-env-var-dependencies) -4. [set-default-outputs](#set-default-outputs) - -### `add-package-manager` - - - Introduced in v1.1.0 - - -Transforms the root `package.json` so that `packageManager` key as the detected package manager (`yarn`, `npm`, `pnpm`) and version (e.g. `yarn@1.22.17`). This key is now [supported by Node.js](https://nodejs.org/dist/latest-v17.x/docs/api/packages.html#packagemanager) and is used by Turborepo for faster package manager detection (vs. inferring from just the filesystem alone). - -For example, for Yarn v1: - -```json -// Before -{ - "name": "turborepo-basic", - "version": "0.0.0", - "private": true, - "workspaces": ["apps/*", "packages/*"] - // ... -} -``` - -```diff -{ - "name": "turborepo-basic", - "version": "0.0.0", - "private": true, -+ "packageManager": "yarn@1.22.17", - "workspaces": [ - "apps/*", - "packages/*" - ] -} -``` - -#### Usage - -Go to your project: - -```sh -cd path-to-your-turborepo/ -``` - -Run the codemod: - -```sh -npx @turbo/codemod add-package-manager -``` - -### `create-turbo-config` - - - Introduced in v1.1.0 - - -Creates the `turbo.json` file at the root of your project based on the `"turbo"` key in `package.json`. -The `"turbo"` key is subsequently deleted from `package.json`. - -For example: - -```json -// Before, package.json -{ - "name": "Monorepo root", - "private": true, - "turbo": { - "pipeline": { - ... - } - }, - ... -} -``` - -```diff -// After, package.json -{ - "name": "Monorepo root", - "private": true, -- "turbo": { -- "pipeline": { -- ... -- } -- }, - ... -} - -// After, turbo.json -+{ -+ "$schema": "https://turbo.build/schema.json", -+ "pipeline": { -+ ... -+ } -+} -``` - -#### Usage - -Go to your project: - -```sh -cd path-to-your-turborepo/ -``` - -Run the codemod: - -```sh -npx @turbo/codemod create-turbo-config -``` - -### `migrate-env-var-dependencies` - - - Introduced in v1.5.0 - - -Migrates all environment variable dependencies in `turbo.json` from `dependsOn` and `globalDependencies` to `env` and `globalEnv` respectively. - -For example: - -```json -// Before, turbo.json -{ - "$schema": "https://turbo.build/schema.json", - "globalDependencies": [".env", "$CI_ENV"], - "pipeline": { - "build": { - "dependsOn": ["^build", "$API_BASE"], - "outputs": [".next/**", "!.next/cache/**"] - }, - "lint": {}, - "dev": { - "cache": false, - "persistent": true - } - } -} -``` - -```diff -// After, turbo.json -{ - "$schema": "https://turbo.build/schema.json", -- "globalDependencies": [".env", "$CI_ENV"], -+ "globalDependencies": [".env"], -+ "globalEnv": ["CI_ENV"], - "pipeline": { - "build": { -- "dependsOn": ["^build", "$API_BASE"], -+ "dependsOn": ["^build"], -+ "env": ["API_BASE"], - "outputs": [".next/**", "!.next/cache/**"], - }, - "lint": {}, - "dev": { - "cache": false, - "persistent": true - } - } -} -``` - -#### Usage - -Go to your project: - -```sh -cd path-to-your-turborepo/ -``` - -Run the codemod: - -```sh -npx @turbo/codemod migrate-env-var-dependencies -``` - -### `set-default-outputs` - - - Introduced in v1.7.0 - - -Migrates `turbo.json` outputs to include the previously inferred `dist/` and `build/`. - -For example: - -```json -// Before, turbo.json -{ - "$schema": "https://turbo.build/schema.json", - "globalDependencies": [".env"], - "globalEnv": ["CI_ENV"], - "pipeline": { - "build": { - "dependsOn": ["^build"], - "env": ["API_BASE"], - "outputs": [".next/**", "!.next/cache/**"] - }, - "lint": { - "outputs": [] - }, - "dev": { - "cache": false, - "persistent": true - } - } -} -``` - -```diff -// After, turbo.json -{ - "$schema": "https://turbo.build/schema.json", - "globalDependencies": [".env"], - "globalEnv": ["CI_ENV"], - "pipeline": { - "build": { - "dependsOn": ["^build"], - "env": ["API_BASE"], - "outputs": [".next/**", "!.next/cache/**"] - }, -- "lint": { -- "outputs": [] -- }, -+ "lint": {}, - "dev": { - "cache": false, - "persistent": true, -+ "outputs": ["dist/**", "build/**"] - } - } -} - -``` - -#### Usage - -Go to your project: - -```sh -cd path-to-your-turborepo/ -``` - -Run the codemod: - -```sh -npx @turbo/codemod set-default-outputs -``` diff --git a/docs/pages/repo/docs/reference/command-line-reference.mdx b/docs/pages/repo/docs/reference/command-line-reference.mdx deleted file mode 100644 index b1fdddf..0000000 --- a/docs/pages/repo/docs/reference/command-line-reference.mdx +++ /dev/null @@ -1,713 +0,0 @@ ---- -title: CLI Reference -description: Turborepo is a high-performance build system for JavaScript and TypeScript codebases. ---- - -import Callout from "../../../../components/Callout"; -import OuputModeTable from "../../../../components/output-mode-table.mdx"; - -# Command-Line Reference - -After [installing the `turbo`](/repo/docs/getting-started/add-to-project) package (or cloning a starter), you can start using Turborepo's command line interface (CLI) `turbo` to do all kinds of awesomeness in your monorepo. - -## Option Syntax - -Options can be passed to `turbo` in different ways. Options that require a value can be passed with an equals sign: - -```sh ---opt= ---opt="" -``` - -They can also be passed with a space between: - -```sh ---opt value ---opt "value with a space" -``` - -Boolean options can be enabled as follows: - -```sh -# To pass true ---opt - -# To pass false ---opt=false -``` - -## Global Arguments - -The following flags apply to all commands. - -#### `--color` - -Forces the use of color even when the output stream is not considered to be a TTY terminal. -This can be used to enable `turbo`'s color output for CI runners such as Github Actions which -have support for rendering color in their log output. - -```sh -turbo run build --color -``` - -Alternatively, you can also enable color using the `FORCE_COLOR` environment variable (borrowed -from the [supports-color nodejs package](https://www.npmjs.com/package/supports-color)). Note that -this may also enable additional colored output from the actual tasks themselves if -they use `supports-color` to determine whether or not to output with colored output. - -```sh -declare -x FORCE_COLOR=1 -turbo run build -``` - -#### `--no-color` - -Suppresses the use of color in the output when running `turbo` in an interactive / TTY session. - -```sh -turbo run build --no-color -``` - -Alternatively, you can also suppress color using the `FORCE_COLOR` environment variable (borrowed -from the [supports-color nodejs package](https://www.npmjs.com/package/supports-color)). - -```sh -declare -x FORCE_COLOR=0 -turbo run build -``` - -#### `--no-update-notifier` - -Disables the update notification. This notification will be automatically disabled when running in CI environments, but can also be disabled manually via this flag. - -```sh -turbo run build --no-update-notifier -``` - -Alternatively, you can also disable the update notification by using either the `TURBO_NO_UPDATE_NOTIFIER` environment variable, or the `NO_UPDATE_NOTIFIER` environment variable (borrowed from the [update-notifier nodejs package](https://github.com/yeoman/update-notifier)). - -```sh -declare -x TURBO_NO_UPDATE_NOTIFIER=1 -turbo run build -``` - -## `turbo run ` - -Run npm scripts across all workspaces in specified scope. Tasks must be specified in your `pipeline` configuration. - -`turbo run [options] [-- ]` - -`turbo` can run multiple tasks, and any arguments following `--` will be passed through -to the tasks to be executed. Note that these additional arguments will _not_ be passed to -any additional tasks that are run due to dependencies from the [pipeline](/repo/docs/reference/configuration#pipeline) configuration. - -### Options - -#### `--cache-dir` - -`type: string` - -Defaults to `./node_modules/.cache/turbo`. Specify local filesystem cache directory. Be sure to add this folder to your `.gitignore` if you change it from the default. - -```sh -turbo run build --cache-dir="./my-cache" -``` - -#### `--concurrency` - -`type: number | string` - -Defaults to `10`. Set/limit the max concurrency of task execution. This must be an integer greater than or equal to `1` or a percentage value like `50%`. Use `1` to force serial (i.e. one task at a time) execution. Use `100%` to use all available logical processors. This option is ignored if the [`--parallel`](#--parallel) flag is also passed. - -```sh -turbo run build --concurrency=50% -turbo run test --concurrency=1 -``` - -#### `--continue` - -Defaults to `false`. This flag tells `turbo` whether or not to continue with execution in the presence of an error (i.e. non-zero exit code from a task). -By default, specifying the `--parallel` flag will automatically set `--continue` to `true` unless explicitly set to `false`. -When `--continue` is `true`, `turbo` will exit with the highest exit code value encountered during execution. - -```sh -turbo run build --continue -``` - -#### `--cwd` - -Set the working directory of the command. - -```sh -turbo run build --cwd=./somewhere/else -``` - -#### `--deps` - - - `--deps` is deprecated in `1.2.x`. Please use - [`--filter`](/repo/docs/core-concepts/monorepos/filtering#include-dependents-of-matched-workspaces) - instead. - - -Defaults to `true`. Include dependent workspace consumers in the execution. - -```sh -turbo run build --deps -turbo run build --no-deps -``` - -**Example** - -Let's say you have workspaces A, B, C, and D where A depends on B and C depends on D. You run `turbo run build` for the first time and everything is built and cached. Then, you change a line of code in B. With the `--deps` flag on, running `turbo run build` will execute `build` in B and then A, but not in C and D because they are not impacted by the change. If you were to run `turbo run build --no-deps` instead, turbo will only run `build` in B. - -#### `--dry / --dry-run` - -Instead of executing tasks, display details about the affected workspaces and tasks that would be run. -Specify `--dry=json` to get the output in JSON format. - -Task details include: - -- `task`: The name of the task to be executed -- `package`: The workspace in which to run the task -- `hash`: The hash of the task, used for caching -- `directory`: The directory where the task will be run -- `command`: The actual command used to run the task -- `outputs`: Location of outputs from the task that will cached -- `logFile`: Location of the log file for the task run -- `dependencies`: Tasks that must run before this task -- `dependents`: Tasks that must be run after this task - -#### `--experimental-env-mode` - -`type: string` - - - **Warning**: This is an experimental flag, so its name and behavior can change. - - -Controls the available environment variables to your tasks. - -| option | description | -| ------ | ---------------------------------------------------------- | -| infer | infers strict mode or loose mode based on allowlist config | -| loose | allows all environment variables | -| strict | only allow declared variables | - -`PATH`, `SHELL`, and `SYSTEMROOT` are always available to all tasks. - -##### `infer` - -In infer mode, Turborepo will look for [`experimentalPassThroughEnv`][1] for -each task config, and [`experimentalGlobalPassThroughEnv`][2] in the root of the -`turbo.json` config. If either is defined, "strict" mode is inferred. If -neither is defined, then `loose` mode is inferred. - -In this mode, the value of `experimentalGlobalPassThroughEnv` and the flag's -value ("infer") will only be incorporated into the global hash if -`experimentalGlobalPassThroughEnv` is set. - -##### `loose` - -In loose mode, all environment variables are made available to the task. -The value of `experimentalGlobalPassThroughEnv` and the flag's value ("loose") -itself will be incorporated into the global hash. - -##### `strict` - -In strict mode, only environment variables specified in the following keys are -available to the task: - -- `env` and `experimentalPassThroughEnv` in each task configuration -- `globalEnv` and `experimentalGlobalPassThroughEnv` in the root of your config - -The value of `experimentalGlobalPassThroughEnv` and the flag's value ("strict") -itself will be incorporated into the global hash. - -If strict mode is specified or inferred, _all_ tasks are run in strict mode, -regardless of their configuration. - -#### `--filter` - -`type: string[]` - -Specify combinations of workspaces, directories, and git commits to act as entrypoints -for execution. - -Multiple filters can be combined to select distinct sets of targets. Additionally, filters -can also exclude targets. A target that matches any filter and is not explicitly excluded will -be in the final entrypoint selection. - -For more detailed information about the `--filter` flag and filtering, refer to the [dedicated page in our documentation](/repo/docs/core-concepts/monorepos/filtering). - -```sh -turbo run build --filter=my-pkg -turbo run test --filter=...^@scope/my-lib -turbo run build --filter=./apps/* --filter=!./apps/admin -``` - -#### `--graph` - -This command will generate an svg, png, jpg, pdf, json, html, or [other supported output formats](https://graphviz.org/doc/info/output.html) of the current task graph. -The output file format defaults to jpg, but can be controlled by specifying the filename's extension. - -If Graphviz is not installed, or no filename is provided, this command prints the dot graph to `stdout`. - -```sh -turbo run build --graph -turbo run build test lint --graph=my-graph.svg -turbo run build test lint --graph=my-json-graph.json -turbo run build test lint --graph=my-graph.pdf -turbo run build test lint --graph=my-graph.png -turbo run build test lint --graph=my-graph.html -turbo run build test lint --graph=my-graph.mermaid -``` - - - **Known Bug**: All possible pipeline task nodes will be added to the graph at - the moment, even if that pipeline task does not actually exist in a given - workspace. This has no impact on execution, it means that 1) the terminal - output may overstate the number of workspaces in which a task is running and - 2) your dot viz graph may contain additional nodes that represents tasks that - do not exist. - - -#### `--force` - -Ignore existing cached artifacts and forcibly re-execute all tasks (overwriting artifacts that overlap) - -```sh -turbo run build --force -``` - -The same behavior also be set via the `TURBO_FORCE=true` environment variable. - -#### `--global-deps` - -Specify glob of global filesystem dependencies to be hashed. Useful for .env and files in the root directory that impact multiple packages/apps. -Can be specified multiple times. - -```sh -turbo run build --global-deps=".env.*" --global-deps=".eslintrc" --global-deps="jest.config.js" -``` - -You can also specify these in your `turbo` configuration as `globalDependencies` key. - -#### `--ignore` - -`type: string[]` - -Ignore **files or directories** from impacting scope. Uses glob patterns under the hood. - -``` -turbo run build --ignore="apps/**/*" -turbo run build --ignore="packages/**/*" -turbo run build --ignore="packages/**/*" --ignore="\!/packages/not-this-one/**/*" -``` - -##### How multiple patterns work - -Positive patterns (e.g. `foo` or `*`) add to the results, while negative patterns (e.g. `!foo`) subtract from the results. - -Therefore a lone negation (e.g. `['!foo']`) will never match anything – use `['*', '!foo']` instead. - -##### Globbing patterns - -Just a quick overview. - -- `*` matches any number of characters, but not `/` -- `?` matches a single character, but not `/` -- `**` matches any number of characters, including `/`, as long as it's the only thing in a path part -- `{}` allows for a comma-separated list of "or" expressions -- `!` at the beginning of a pattern will negate the match - -#### `--include-dependencies` - - - `--include-dependencies` is deprecated in `1.2.x`. Please use - [`--filter`](/repo/docs/core-concepts/monorepos/filtering#include-dependencies-of-matched-workspaces) - instead. - - -Default `false`. When `true`, `turbo` will add any workspaces that the workspaces in the current execution _depend_ on (i.e. those declared in `dependencies` or `devDependencies`). - -This is useful when using `--filter` in CI as it guarantees that every dependency needed for the execution is actually executed. - -#### `--no-cache` - -Default `false`. Do not cache results of the task. This is useful for watch commands like `next dev` or `react-scripts start`. - -```shell -turbo run build --no-cache -turbo run dev --no-cache -``` - -#### `--no-daemon` - -Default `false`. `turbo` can run a standalone process in some cases to precalculate values used for determining what work needs to be done. -This standalone process (daemon) is an optimization, and not required for proper functioning of `turbo`. -Passing `--no-daemon` instructs `turbo` to avoid using or creating the standalone process. - -#### `--output-logs` - -`type: string` - -Set type of output logging. Defaults to "outputMode" for the task in `turbo.json`. - - - -**Example** - -```shell -turbo run build --output-logs=full -turbo run build --output-logs=new-only -turbo run build --output-logs=errors-only -turbo run build --output-logs=none -``` - -#### `--only` - -Default `false`. Restricts execution to include specified tasks only. This is very similar to how `lerna` and `pnpm` run tasks by default. - -Given this pipeline in `turbo.json`: - -```json -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["^build"] - } - } -} -``` - -```shell -turbo run test --only -``` - -Will execute _only_ the `test` tasks in each workspace. It will not `build`. - -#### `--parallel` - -Default `false`. Run commands in parallel across workspaces and ignore the task dependency graph. - - - The `--parallel` flag is typically used for "dev" or `--watch` mode tasks that don't exit. - Starting in `turbo@1.7`, we recommend configuring these tasks using the - [`persistent`](/repo/docs/reference/configuration#persistent) config instead. - - -```sh -turbo run lint --parallel --no-cache -turbo run dev --parallel --no-cache -``` - -#### `--remote-only` - -Default `false`. Ignore the local filesystem cache for all tasks. Only allow reading and caching artifacts using the remote cache. - -```shell -turbo run build --remote-only -``` - -The same behavior can also be set via the `TURBO_REMOTE_ONLY=true` environment variable. - -#### `--scope` - - - `--scope` is deprecated in `1.2.x`. Please use - [`--filter`](/repo/docs/core-concepts/monorepos/filtering#filter-by-package) instead. - - -`type: string[]` - -Specify/filter workspaces to act as entry points for execution. Globs against `package.json` `name` field (and not the file system.) - -```sh -turbo run lint --scope="@example/**" -turbo run dev --scope="@example/a" --scope="@example/b" --no-cache --no-deps -``` - -#### `--serial` - - - `serial` is deprecated in `0.5.3`.Please use - [`--concurrency=1`](#--concurrency) instead. - - -Executes all tasks serially (i.e. one-at-a-time). - -```sh -turbo run build --serial -``` - -#### `--since` - - - `--since` is deprecated in `1.2.x`. Please use - [`--filter`](/repo/docs/core-concepts/monorepos/filtering#filter-by-changed-workspaces) - instead. - - -Filter execution based on which workspaces have changed since a merge-base. - -``` -turbo run build --since=origin/main -``` - - - **Important**: This uses the `git diff ${target_branch}...` mechanism to - identify which workspaces have changed. There is an assumption that all the - input files for a workspace exist inside their respective workspace folders. - - -#### `--summarize` - -Generates a JSON file in `.turbo/runs` containing metadata about the run, including affected workspaces, -executed tasks (including their timings and hashes), expanded to the cache key based on your config -and all the files included in the cached artifact. This flag can be helpful to determine, among other -things: - -- How turbo interpreted your glob syntax for `inputs` and `outputs` -- What inputs changed between two task runs to produce a cache hit or miss -- How task timings changed over time - -#### `--token` - -A bearer token for remote caching. Useful for running in non-interactive shells (e.g. CI/CD) in combination with `--team` flags. - -```sh -turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx -``` - -You can also set the value of the current token by setting an environment variable named `TURBO_TOKEN`. The flag will take precedence over the environment variable if both are present. - -If you are using Remote Caching on Vercel and building your project on Vercel, this environment variable and flag are unnecessary because they are automatically set for you. Suppose you are using Remote Caching on Vercel but building in another CI provider like CircleCI or GitHub Actions. You can use a Vercel Personal Access Token as your `--token` or `TURBO_TOKEN`. If you are using a custom Remote Cache, this value will be used to send an HTTP Bearer token with requests to your custom Remote Cache. - -#### `--team` - -The slug of the remote cache team. Useful for running in non-interactive shells in combination with `--token` and `--team` flags. - -```sh -turbo run build --team=my-team -turbo run build --team=my-team --token=xxxxxxxxxxxxxxxxx -``` - -You can also set the value of the current team by setting an environment variable named `TURBO_TEAM`. The flag will take precedence over the environment variable if both are present. - -#### `--preflight` - -Only applicable when remote artifact caching is configured. Enables sending a preflight request before every cache artifact and analytics request. The follow-up upload and download will follow redirects. - -```sh -turbo run build --preflight -``` - -The same behavior can also be set via the `TURBO_PREFLIGHT=true` environment variable. - -#### `--trace` - -`type: string` - -To view CPU trace, outputs the trace to the given file, use `go tool trace [file]`. - - - **Important**: The trace viewer doesn't work under Windows Subsystem for - Linux. - - -```sh -turbo run build --trace="" -``` - -#### `--heap` - -`type: string` - -To view heap trace, outputs the trace to the given file, use `go tool pprof [file]` and type `top`. You can also drop it into [speedscope](https://www.speedscope.app/) and use the `left heavy` or `sandwich` view modes. - -```sh -turbo run build --heap="" -``` - -#### `--cpuprofile` - -`type: string` - -To view CPU profile, outputs the profile to the given file, drop the file into [speedscope](https://www.speedscope.app/). - - - **Important**: The CPU profiler doesn't work under Windows Subsystem for - Linux. The profiler has to be built for native Windows and run using the - command prompt instead. - - -```sh -turbo run build --cpuprofile="" -``` - -#### `--verbosity` - -To specify log level, use `--verbosity=` or `-v, -vv, -vvv`. - -- `Info `: `--verbosity=1`, or `-v` -- `Debug`: `--verbosity=2`, or `-vv` -- `Trace`: `--verbosity=3`, or `-vvv` - -```sh -turbo run build -v -turbo run build --verbosity=2 -turbo run build -vvv -``` - -## `turbo prune --scope=` - -Generate a sparse/partial monorepo with a pruned lockfile for a target workspace. - -This command will generate folder called `out` with the following inside of it: - -- The full source code of all internal workspaces that are needed to build the target -- A new pruned lockfile that only contains the pruned subset of the original root lockfile with the dependencies that are actually used by the workspaces in the pruned workspace. -- A copy of the root `package.json` - -``` -. # Folder full source code for all workspaces needed to build the target -├── package.json # The root `package.json` -├── packages -│ ├── ui -│ │ ├── package.json -│ │ ├── src -│ │ │ └── index.tsx -│ │ └── tsconfig.json -│ ├── shared -│ │ ├── package.json -│ │ ├── src -│ │ │ ├── __tests__ -│ │ │ │ ├── sum.test.ts -│ │ │ │ └── tsconfig.json -│ │ │ ├── index.ts -│ │ │ └── sum.ts -│ │ └── tsconfig.json -│ └── frontend -│ ├── next-env.d.ts -│ ├── next.config.js -│ ├── package.json -│ ├── src -│ │ └── pages -│ │ └── index.tsx -│ └── tsconfig.json -└── yarn.lock # The pruned lockfile for all targets in the subworkspace -``` - -### Options - -#### `--docker` - -`type: boolean` - -Default to `false`. Passing this flag will alter the outputted folder with the pruned workspace to make it easier to use with [Docker best practices / layer caching](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/). - -With the `--docker` flag. The `prune` command will generate folder called `out` with the following inside of it: - -- A folder `json` with the pruned workspace's `package.json`s -- A folder `full` with the pruned workspace's full source code, but only including the internal packages that are needed to build the target. -- A new pruned lockfile that only contains the pruned subset of the original root lockfile with the dependencies that are actually used by the packages in the pruned workspace. - -``` -. -├── full # Folder full source code for all package needed to build the target -│ ├── package.json -│ └── packages -│ ├── ui -│ │ ├── package.json -│ │ ├── src -│ │ │ └── index.tsx -│ │ └── tsconfig.json -│ ├── shared -│ │ ├── package.json -│ │ ├── src -│ │ │ ├── __tests__ -│ │ │ │ ├── sum.test.ts -│ │ │ │ └── tsconfig.json -│ │ │ ├── index.ts -│ │ │ └── sum.ts -│ │ └── tsconfig.json -│ └── frontend -│ ├── next-env.d.ts -│ ├── next.config.js -│ ├── package.json -│ ├── src -│ │ └── pages -│ │ └── index.tsx -│ └── tsconfig.json -├── json # Folder containing just package.jsons for all targets in the subworkspace -│ ├── package.json -│ └── packages -│ ├── ui -│ │ └── package.json -│ ├── shared -│ │ └── package.json -│ └── frontend -│ └── package.json -└── yarn.lock # The pruned lockfile for all targets in the subworkspace -``` - -## `turbo login` - -Connect machine to your Remote Cache provider. The default provider is [Vercel](https://vercel.com/). - -### Options - -#### `--url` - -`type: string` - -Defaults to `https://vercel.com/`. - -#### `--api` - -`type: string` - -Defaults to `https://vercel.com/api`. - -#### `--sso-team` - -`type: string` - -Connect to an sso-enabled Vercel team by providing your Team slug. - -``` -turbo login --sso-team= -``` - -## `turbo logout` - -Logs you out of your Vercel account. - -## `turbo link` - -Link the current directory to Remote Cache scope. The selected owner (either a user or and organization) will be able to share [cache artifacts](/repo/docs/core-concepts/caching) through [Remote Caching](/repo/docs/core-concepts/remote-caching). -You should run this command from the root of your monorepo. - -### Options - -#### `--api` - -`type: string` - -Defaults to `https://api.vercel.com` - -## `turbo unlink` - -Unlink the current directory from the Remote Cache. - -## `turbo bin` - -Get the path to the `turbo` binary. - -[1]: /repo/docs/refernce/configuration#experimentalPassThroughEnv -[2]: /repo/docs/refernce/configuration#experimentalGlobalPassThroughEnv diff --git a/docs/pages/repo/docs/reference/configuration.mdx b/docs/pages/repo/docs/reference/configuration.mdx deleted file mode 100644 index ef52d46..0000000 --- a/docs/pages/repo/docs/reference/configuration.mdx +++ /dev/null @@ -1,405 +0,0 @@ ---- -title: Configuration -description: Learn how to configure Turborepo through `turbo.json`. ---- - -import Callout from "../../../../components/Callout"; -import OutputModeTable from "../../../../components/output-mode-table.mdx"; -import Link from 'next/link' - -# Configuration Options (`turbo.json`) - -You can configure the behavior of `turbo` by adding a `turbo.json` file in your monorepo's root directory. - -## `globalDependencies` - -`type: string[]` - -A list of file globs for global hash dependencies. The contents of these files will be included in the global hashing algorithm and affect the hashes of all tasks. -This is useful for busting the cache based on `.env` files (not in Git) or any root level file that impacts workspace tasks (but are not represented in the traditional dependency graph (e.g. a root `tsconfig.json`, `jest.config.js`, `.eslintrc`, etc.)). - - -These must be relative paths from the location of `turbo.json`, and they should be valid for any machine where - this configuration might be used. For instance, it is not a good idea to reference files in one user's home directory. - - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - // ... omitted for brevity - }, - - "globalDependencies": [ - ".env", // contents will impact hashes of all tasks - "tsconfig.json" // contents will impact hashes of all tasks - ] -} -``` - -## `globalEnv` - -`type: string[]` - -A list of environment variables for implicit global hash dependencies. The contents of these environment variables will be included in the global hashing algorithm and affect the hashes of all tasks. - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - // ... omitted for brevity - }, - - "globalEnv": ["GITHUB_TOKEN"] // value will impact the hashes of all tasks -} -``` - -## `extends` - -`type: string[]` - -The `extends` key is only valid in Workspace Configurations. It will be -ignored in the root `turbo.json`. Read [the docs to learn more][1]. - -## `pipeline` - -An object representing the task dependency graph of your project. `turbo` interprets these conventions to properly schedule, execute, and cache the outputs of tasks in your project. - -Each key in the `pipeline` object is the name of a task that can be executed by `turbo run`. If `turbo` finds a workspace with a `package.json` `scripts` object with a matching key, it will apply the pipeline task configuration to that npm script during execution. This allows you to use `pipeline` to set conventions across your entire Turborepo. - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"] - }, - "test": { - "outputs": ["coverage/**"], - "dependsOn": ["build"], - "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"], - "outputMode": "full" - }, - "dev": { - "cache": false, - "persistent": true - } - } -} -``` - -### `dependsOn` - -`type: string[]` - -The list of tasks this task depends on. - -Prefixing an item in `dependsOn` with a `^` tells `turbo` that this pipeline task depends on the workspace's topological dependencies completing the task with the `^` prefix first (e.g. "a workspace's `build` tasks should only run once all of its `dependencies` and `devDependencies` have completed their own `build` commands"). - -Items in `dependsOn` without `^` prefix, express the relationships between tasks at the workspace level (e.g. "a workspace's `test` and `lint` commands depend on `build` being completed first"). - - - As of version 1.5, using `$` to declare environment variables in the `dependsOn` config is - deprecated. Use the `env` key instead. - - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - // "A workspace's `build` command depends on its dependencies' - // or devDependencies' `build` command being completed first" - "outputs": [".next/**", "!.next/cache/**", "dist/**"], - "dependsOn": ["^build"] - }, - "test": { - // "A workspace's `test` command depends on its own `lint` and - // `build` commands first being completed" - "dependsOn": ["lint", "build"] - }, - "deploy": { - // "A workspace's `deploy` command, depends on its own `build` - // and `test` commands first being completed" - "dependsOn": ["build", "test"] - }, - // A workspace's `lint` command has no dependencies - "lint": {} - } -} -``` - -### `env` - -`type: string[]` - -The list of environment variables a task depends on. - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"], - "env": ["SOMETHING_ELSE"], // value will impact the hashes of all build tasks - "outputs": ["dist/**", ".next/**", "!.next/cache/**"] - }, - "web#build": { - "dependsOn": ["^build"], - "env": ["STRIPE_SECRET_KEY"], // value will impact hash of only web's build task - "outputs": [".next/**", "!.next/cache/**"] - } - }, - "globalEnv": [ - "GITHUB_TOKEN" // value will impact the hashes of all tasks - ] -} -``` - - - When Turborepo detects a common frontend framework in a workspace, it will - automatically depend on environment variables that are going to be inlined in - your build. For example, if the `web` workspace contains a Next.js project, - you do not need to specify any environment variables that [start with - `NEXT_PUBLIC_`](https://nextjs.org/docs/basic-features/environment-variables#exposing-environment-variables-to-the-browser) - in the `dependsOn` config. Turborepo already knows that the build output will - change when the value of these environment variables change, so it will depend - on them automatically. See more in the [docs on - caching](/repo/docs/core-concepts/caching#automatic-environment-variable-inclusion). - - -### `outputs` - -`type: string[]` - -The set of glob patterns of a task's cacheable filesystem outputs. - -Note: `turbo` automatically logs `stderr`/`stdout` to `.turbo/run-.log`. This file is _always_ -treated as a cacheable artifact and never needs to be specified. - -Omitting this key or passing an empty array can be used to tell `turbo` that a task is a side-effect -and thus doesn't emit any filesystem artifacts (e.g. like a linter), but you still want to cache its -logs (and treat them like an artifact). - - - `outputs` globs must be specified as relative paths rooted at the workspace directory. - - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - // "Cache all files emitted to workspace's dist/** or .next - // directories by a `build` task" - "outputs": ["dist/**", ".next/**", "!.next/cache/**"], - "dependsOn": ["^build"] - }, - "test": { - // "Don't cache any artifacts of `test` tasks (aside from - // logs)" - "dependsOn": ["build"] - }, - "test:ci": { - // "Cache the coverage report of a `test:ci` command" - "outputs": ["coverage/**"], - "dependsOn": ["build"] - }, - "dev": { - // Never cache anything (including logs) emitted by a - // `dev` task - "cache": false, - "persistent": true - } - } -} -``` - -### `cache` - -`type: boolean` - -Defaults to `true`. Whether or not to cache the task [`outputs`](#outputs). Setting `cache` to false is useful for daemon or long-running "watch" or development mode tasks you don't want to cache. - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "outputs": [".svelte-kit/**", "dist/**"], - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["build"] - }, - "dev": { - "cache": false, - "persistent": true - } - } -} -``` - -### `inputs` - -`type: string[]` - -Defaults to `[]`. Tells `turbo` the set of files to consider when determining if a workspace has changed for a particular task. -Setting this to a list of globs will cause the task to only be rerun when files matching those globs have -changed. This can be helpful if you want to, for example, skip running tests unless a source file changed. - -Specifying `[]` will cause the task to be rerun when any file in the workspace changes. - - - `inputs` globs must be specified as relative paths rooted at the workspace directory. - - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - // ... omitted for brevity - - "test": { - // A workspace's `test` task depends on that workspace's - // own `build` task being completed first. - "dependsOn": ["build"], - "outputs": [".next/**", "!.next/cache/**"], - // A workspace's `test` task should only be rerun when - // either a `.tsx` or `.ts` file has changed. - "inputs": ["src/**/*.tsx", "src/**/*.ts", "test/**/*.ts"] - } - } -} -``` - - - Note: `turbo.json` is *always* considered an input. If you modify - `turbo.json`, all caches are invalidated. - - -### `outputMode` - -`type: "full" | "hash-only" | "new-only" | "errors-only" | "none"` - -Set type of output logging. - - - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"], - "outputs": [".svelte-kit/**", "dist/**"], - "outputMode": "new-only" - }, - "test": { - "dependsOn": ["build"] - } - } -} -``` - -### `persistent` - -`type: boolean` - -Label a task as `persistent` if it is a long-running process, such as a dev server or `--watch` mode. -Turbo will prevent other tasks from depending on persistent tasks. Without setting this -config, if any other task depends on `dev`, it will never run, because `dev` never exits. With this -option, `turbo` can warn you about an invalid configuration. - -**Example** - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "dev": { - "persistent": true - } - } -} -``` - -[1]: /repo/docs/core-concepts/monorepos/configuring-workspaces - -## Experimental - -### `experimentalGlobalPassThroughEnv` - -This goes at the root of your configuration. - -`type: string[]` - -An allowlist of environment variables that should be made available to all tasks -but should not contribute to the task's cache key. Using this key opts all tasks -into strict environment variable mode. - -Changing this list will contribute to the global cache key, but the value of each -variable will not. - -**Example** - -`AWS_SECRET_KEY` and `GITHUB_TOKEN` are available to all tasks in `strict` [env mode][r-cli-env-mode]. - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "experimentalGlobalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"], - "pipeline": { - // ...task definitions... - } -} -``` - -### `experimentalPassThroughEnv` - -`type: string[]` - -This config goes inside each task definition in the [`pipeline`][r-config-pipeline]. - -An allowlist of environment variables that should be made available to this task -but should not contribute to the task's cache key. Using this key opts this task -into strict environment variable mode. - -Changing this list will contribute to the task's cache key, but the value of each -variable will not. - -**Example** - -`AWS_SECRET_KEY` and `GITHUB_TOKEN` are available to the `build` task, but not to the `lint` task -in `strict` [env mode][r-cli-env-mode]. - -```jsonc -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "experimentalPassThroughEnv": ["AWS_SECRET_KEY", "GITHUB_TOKEN"] - }, - "lint": {}, - } -} -``` - -[r-config-pipeline]: #pipeline -[r-cli-env-mode]: /repo/docs/reference/command-line-reference#--experimental-env-mode diff --git a/docs/pages/repo/docs/troubleshooting.mdx b/docs/pages/repo/docs/troubleshooting.mdx deleted file mode 100644 index dfa3256..0000000 --- a/docs/pages/repo/docs/troubleshooting.mdx +++ /dev/null @@ -1,172 +0,0 @@ ---- -title: Troubleshooting Runs -description: This guide aims to help you debug issues with your Turborepo builds and configuration. ---- - -# Troubleshooting Runs - -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. - -## Enable Verbose Logs - -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. - -## Check the Run Summary - -The [--summarize][r-summarize] flag generates and saves metadata about your `turbo run` -as a JSON file in `.turbo/runs`. You can use it to compare subsequent runs, inspect -the contents of the cached artifact, and the inputs to the hash for a task. - -## Check your Configuration - -### 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 - -In general, you should expect that when you run `turbo run` twice in a row, you should get a -cache hit on the second run. If this isn't happening, run both builds again with the [`--summarize` -flag][r-summarize] and compare the generated Run Summaries to each other. In most cases, the -comparison should show why the second run did not get a cache hit. - -You can also ask: - -- 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][d-config-outputs] correctly specified 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] - - [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? - -[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 -[r-summarize]: /repo/docs/reference/command-line-reference#--summarize diff --git a/docs/pages/repo/docs/upgrading-to-v1.mdx b/docs/pages/repo/docs/upgrading-to-v1.mdx deleted file mode 100644 index 3ed2de3..0000000 --- a/docs/pages/repo/docs/upgrading-to-v1.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: Upgrading to v1 -description: Learn how to upgrade to Turborepo v1, now open-source and part of Vercel. ---- - -# Upgrading to Turborepo v1.x - -Turborepo has been acquired by Vercel! With this announcement, **Vercel is open sourcing the `turbo` CLI and offering Remote Caching for free on all accounts during the transition period.** - -Existing Turborepo customers should upgrade their `turbo` CLI to v1.x as soon as possible and migrate to Vercel (instructions below). Earlier versions of `turbo` CLI prior to 1.x will no longer be maintained going forward. New account creation on beta.turborepo.com has been disabled. The beta.turborepo.com dashboard and remote caching service will be shutdown on January 15th, 2022 and older versions will not be installable. - -**All existing Remote Cache artifacts will also be deleted at this time**. - -Below is a step-by-step migration guide for existing Turborepo users. If you get stuck, please reach out in the community [Discord](https://turbo.build/discord) or file an issue on [GitHub](https://github.com/vercel/turbo). Thank you again for your continued support as we begin this awesome new chapter of Turborepo together. - ---- - -## 1. Cleaning up - -For good hygiene, ensure you logout of `turbo` to remove old credentials: - -```sh -yarn turbo logout -``` - -If it exists, also delete the `.turbo` directory from the root of your monorepo: - -```sh -rm -rf .turbo -``` - -## 2. Install the latest release of `turbo` - -Install the latest version version of `turbo`: - -```sh -yarn add turbo --save-dev --ignore-workspace-root-check -``` - -## 3. Setup Remote Caching - -As mentioned, Turborepo now provides zero-config Remote Caching through [Vercel](https://vercel.com/?utm_source=turbo.build&utm_medium=referral&utm_campaign=docs-link). Remote Caching is free for all Vercel plans during this transition period. Each Vercel account has a shared Remote Cache. This cache is shared across all environments (Development, Preview, and Production). - -**Important**: turborepo.com allowed multiple caches (i.e. projects) per team (denoted through `--project` flag). With v1.x caching on Vercel, each Vercel account (user or team) has a single shared Remote Cache. If you were actively using multiple turborepo.com projects for your team, please let us know in [Discord](https://turbo.build/discord). - -Please note that we are not migrating cache artifacts to Vercel. We apologize for the slower builds during your migration as you rehydrate your remote cache on Vercel or custom cache infra. - -## 4. Local Development - -If you were using Remote Caching for local development, upgrading will take a minute or two. To get started, login to the Vercel CLI: - -```sh -npx turbo login -``` - -Now we can set up Remote Caching through Vercel by running: - -```sh -npx turbo link -``` - -Follow the prompts and select the Vercel account (user or team) to wish to connect to. - -### On Vercel - -- If you already used Turborepo and Vercel together, remove `TURBO_TOKEN`, `TURBO_TEAM`, and `TURBO_PROJECT` environment variables from all projects. These are now automatically set on your behalf by Vercel. - -- Remove the usage of `--team`, `--token`, and `--project` CLI flags in your Vercel project settings and/or `package.json` scripts. - -### On other CI/CD - -- Replace your turborepo.com personal access token with a new [Vercel personal access token](https://vercel.com/account/tokens) and update `TURBO_TOKEN` environment variable or equivalent usage of the `--token` CLI flag. -- Remove the `TURBO_PROJECT` environment variable and remove all usage of the `--project` CLI flag. This has been deprecated. -- Update the value of the `TURBO_TEAM` environment variable and `--team` CLI flag to be your Vercel account slug (i.e. `https://vercel.com/`). - -### Getting Help - -If you are having difficulty upgrading please file an issue on [GitHub](https://github.com/vercel/turbo). If you are having difficulty with your remote caching on Vercel, please reach out in [Discord](https://turbo.build/discord). diff --git a/docs/pages/repo/index.mdx b/docs/pages/repo/index.mdx deleted file mode 100644 index fa22190..0000000 --- a/docs/pages/repo/index.mdx +++ /dev/null @@ -1,7 +0,0 @@ ---- -description: Turborepo is a high-performance build system for JavaScript and TypeScript codebases. ---- - -import TurborepoHome from "../../components/pages/repo-home"; - - diff --git a/docs/pages/showcase.mdx b/docs/pages/showcase.mdx index 5cef553..011183d 100644 --- a/docs/pages/showcase.mdx +++ b/docs/pages/showcase.mdx @@ -2,7 +2,7 @@ headeronly: true searchable: false layout: full -description: "Turborepo by Vercel is the one of the fastest growing build systems in the frontend ecosystem. It's trusted by thousands of developers in production including teams at Vercel, AWS, Netflix, Microsoft, Disney, and more." +description: "插件市场" --- import Showcase from "../components/pages/showcase"; diff --git a/docs/pages/terms.mdx b/docs/pages/terms.mdx index 89eb14b..1f890e2 100644 --- a/docs/pages/terms.mdx +++ b/docs/pages/terms.mdx @@ -20,7 +20,7 @@ Vercel grants you a limited, personal, non-exclusive and non-transferable licens ## Privacy Policy -Your use of this Site is governed by our Privacy Policy, which is available at https://turborepo.org/privacy (the "Privacy Policy"). +Your use of this Site is governed by our Privacy Policy, which is available at https://hydroroll.retrofor.space/privacy (the "Privacy Policy"). ## Third Party Content diff --git a/docs/public/images/docs/AI/jared-signature-dark.svg b/docs/public/images/docs/AI/jared-signature-dark.svg new file mode 100644 index 0000000..eec1dbe --- /dev/null +++ b/docs/public/images/docs/AI/jared-signature-dark.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/public/images/docs/AI/jared-signature-light.svg b/docs/public/images/docs/AI/jared-signature-light.svg new file mode 100644 index 0000000..fb64f21 --- /dev/null +++ b/docs/public/images/docs/AI/jared-signature-light.svg @@ -0,0 +1,12 @@ + + + + + + + + + \ No newline at end of file diff --git a/docs/public/images/docs/AI/repo-hero-circles-dark.svg b/docs/public/images/docs/AI/repo-hero-circles-dark.svg new file mode 100644 index 0000000..6533be5 --- /dev/null +++ b/docs/public/images/docs/AI/repo-hero-circles-dark.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/public/images/docs/AI/repo-hero-circles-light.svg b/docs/public/images/docs/AI/repo-hero-circles-light.svg new file mode 100644 index 0000000..48c16ee --- /dev/null +++ b/docs/public/images/docs/AI/repo-hero-circles-light.svg @@ -0,0 +1,14 @@ + + + + + + + + + \ No newline at end of file diff --git a/docs/public/images/docs/AI/repo-hero-logo-dark.svg b/docs/public/images/docs/AI/repo-hero-logo-dark.svg new file mode 100644 index 0000000..2f9aa1f --- /dev/null +++ b/docs/public/images/docs/AI/repo-hero-logo-dark.svg @@ -0,0 +1,32 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/public/images/docs/AI/repo-hero-logo-light.svg b/docs/public/images/docs/AI/repo-hero-logo-light.svg new file mode 100644 index 0000000..ed2b023 --- /dev/null +++ b/docs/public/images/docs/AI/repo-hero-logo-light.svg @@ -0,0 +1,21 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/public/images/docs/TRPG/instruments-dark.png b/docs/public/images/docs/TRPG/instruments-dark.png new file mode 100644 index 0000000..7a32205 Binary files /dev/null and b/docs/public/images/docs/TRPG/instruments-dark.png differ diff --git a/docs/public/images/docs/TRPG/instruments-light.png b/docs/public/images/docs/TRPG/instruments-light.png new file mode 100644 index 0000000..bc090f2 Binary files /dev/null and b/docs/public/images/docs/TRPG/instruments-light.png differ diff --git a/docs/public/images/docs/TRPG/tobias-signature-dark.svg b/docs/public/images/docs/TRPG/tobias-signature-dark.svg new file mode 100644 index 0000000..0afa6de --- /dev/null +++ b/docs/public/images/docs/TRPG/tobias-signature-dark.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/public/images/docs/TRPG/tobias-signature-light.svg b/docs/public/images/docs/TRPG/tobias-signature-light.svg new file mode 100644 index 0000000..016f81c --- /dev/null +++ b/docs/public/images/docs/TRPG/tobias-signature-light.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/public/images/docs/TRPG/turbo-benchmark-icon-dark.svg b/docs/public/images/docs/TRPG/turbo-benchmark-icon-dark.svg new file mode 100644 index 0000000..1feb88e --- /dev/null +++ b/docs/public/images/docs/TRPG/turbo-benchmark-icon-dark.svg @@ -0,0 +1,15 @@ + + + + + + + + + + diff --git a/docs/public/images/docs/TRPG/turbo-benchmark-icon-light.svg b/docs/public/images/docs/TRPG/turbo-benchmark-icon-light.svg new file mode 100644 index 0000000..935f66e --- /dev/null +++ b/docs/public/images/docs/TRPG/turbo-benchmark-icon-light.svg @@ -0,0 +1,15 @@ + + + + + + + + + + diff --git a/docs/public/images/docs/TRPG/turbo-engine-first-run.png b/docs/public/images/docs/TRPG/turbo-engine-first-run.png new file mode 100644 index 0000000..d49cf90 Binary files /dev/null and b/docs/public/images/docs/TRPG/turbo-engine-first-run.png differ diff --git a/docs/public/images/docs/TRPG/turbo-engine-second-run.png b/docs/public/images/docs/TRPG/turbo-engine-second-run.png new file mode 100644 index 0000000..df250c4 Binary files /dev/null and b/docs/public/images/docs/TRPG/turbo-engine-second-run.png differ diff --git a/docs/public/images/docs/TRPG/turbopack-hero-hexagons-dark.svg b/docs/public/images/docs/TRPG/turbopack-hero-hexagons-dark.svg new file mode 100644 index 0000000..4b897b6 --- /dev/null +++ b/docs/public/images/docs/TRPG/turbopack-hero-hexagons-dark.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + + + + + diff --git a/docs/public/images/docs/TRPG/turbopack-hero-hexagons-light.svg b/docs/public/images/docs/TRPG/turbopack-hero-hexagons-light.svg new file mode 100644 index 0000000..ae5effe --- /dev/null +++ b/docs/public/images/docs/TRPG/turbopack-hero-hexagons-light.svg @@ -0,0 +1,13 @@ + + + + + + + + diff --git a/docs/public/images/docs/TRPG/turbopack-hero-logo-dark.svg b/docs/public/images/docs/TRPG/turbopack-hero-logo-dark.svg new file mode 100644 index 0000000..544c730 --- /dev/null +++ b/docs/public/images/docs/TRPG/turbopack-hero-logo-dark.svg @@ -0,0 +1,45 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/public/images/docs/TRPG/turbopack-hero-logo-light.svg b/docs/public/images/docs/TRPG/turbopack-hero-logo-light.svg new file mode 100644 index 0000000..9271703 --- /dev/null +++ b/docs/public/images/docs/TRPG/turbopack-hero-logo-light.svg @@ -0,0 +1,37 @@ + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/public/images/docs/pack/instruments-dark.png b/docs/public/images/docs/pack/instruments-dark.png deleted file mode 100644 index 7a32205..0000000 Binary files a/docs/public/images/docs/pack/instruments-dark.png and /dev/null differ diff --git a/docs/public/images/docs/pack/instruments-light.png b/docs/public/images/docs/pack/instruments-light.png deleted file mode 100644 index bc090f2..0000000 Binary files a/docs/public/images/docs/pack/instruments-light.png and /dev/null differ diff --git a/docs/public/images/docs/pack/tobias-signature-dark.svg b/docs/public/images/docs/pack/tobias-signature-dark.svg deleted file mode 100644 index 0afa6de..0000000 --- a/docs/public/images/docs/pack/tobias-signature-dark.svg +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/public/images/docs/pack/tobias-signature-light.svg b/docs/public/images/docs/pack/tobias-signature-light.svg deleted file mode 100644 index 016f81c..0000000 --- a/docs/public/images/docs/pack/tobias-signature-light.svg +++ /dev/null @@ -1,26 +0,0 @@ - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/public/images/docs/pack/turbo-benchmark-icon-dark.svg b/docs/public/images/docs/pack/turbo-benchmark-icon-dark.svg deleted file mode 100644 index 1feb88e..0000000 --- a/docs/public/images/docs/pack/turbo-benchmark-icon-dark.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - - - - - diff --git a/docs/public/images/docs/pack/turbo-benchmark-icon-light.svg b/docs/public/images/docs/pack/turbo-benchmark-icon-light.svg deleted file mode 100644 index 935f66e..0000000 --- a/docs/public/images/docs/pack/turbo-benchmark-icon-light.svg +++ /dev/null @@ -1,15 +0,0 @@ - - - - - - - - - - diff --git a/docs/public/images/docs/pack/turbo-engine-first-run.png b/docs/public/images/docs/pack/turbo-engine-first-run.png deleted file mode 100644 index d49cf90..0000000 Binary files a/docs/public/images/docs/pack/turbo-engine-first-run.png and /dev/null differ diff --git a/docs/public/images/docs/pack/turbo-engine-second-run.png b/docs/public/images/docs/pack/turbo-engine-second-run.png deleted file mode 100644 index df250c4..0000000 Binary files a/docs/public/images/docs/pack/turbo-engine-second-run.png and /dev/null differ diff --git a/docs/public/images/docs/pack/turbopack-hero-hexagons-dark.svg b/docs/public/images/docs/pack/turbopack-hero-hexagons-dark.svg deleted file mode 100644 index 4b897b6..0000000 --- a/docs/public/images/docs/pack/turbopack-hero-hexagons-dark.svg +++ /dev/null @@ -1,25 +0,0 @@ - - - - - - - - - - - - - - - - - diff --git a/docs/public/images/docs/pack/turbopack-hero-hexagons-light.svg b/docs/public/images/docs/pack/turbopack-hero-hexagons-light.svg deleted file mode 100644 index ae5effe..0000000 --- a/docs/public/images/docs/pack/turbopack-hero-hexagons-light.svg +++ /dev/null @@ -1,13 +0,0 @@ - - - - - - - - diff --git a/docs/public/images/docs/pack/turbopack-hero-logo-dark.svg b/docs/public/images/docs/pack/turbopack-hero-logo-dark.svg deleted file mode 100644 index 544c730..0000000 --- a/docs/public/images/docs/pack/turbopack-hero-logo-dark.svg +++ /dev/null @@ -1,45 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/public/images/docs/pack/turbopack-hero-logo-light.svg b/docs/public/images/docs/pack/turbopack-hero-logo-light.svg deleted file mode 100644 index 9271703..0000000 --- a/docs/public/images/docs/pack/turbopack-hero-logo-light.svg +++ /dev/null @@ -1,37 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/public/images/docs/repo/jared-signature-dark.svg b/docs/public/images/docs/repo/jared-signature-dark.svg deleted file mode 100644 index eec1dbe..0000000 --- a/docs/public/images/docs/repo/jared-signature-dark.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/public/images/docs/repo/jared-signature-light.svg b/docs/public/images/docs/repo/jared-signature-light.svg deleted file mode 100644 index fb64f21..0000000 --- a/docs/public/images/docs/repo/jared-signature-light.svg +++ /dev/null @@ -1,12 +0,0 @@ - - - - - - - - - \ No newline at end of file diff --git a/docs/public/images/docs/repo/repo-hero-circles-dark.svg b/docs/public/images/docs/repo/repo-hero-circles-dark.svg deleted file mode 100644 index 6533be5..0000000 --- a/docs/public/images/docs/repo/repo-hero-circles-dark.svg +++ /dev/null @@ -1,17 +0,0 @@ - - - - - - - - - - - - - - - - - \ No newline at end of file diff --git a/docs/public/images/docs/repo/repo-hero-circles-light.svg b/docs/public/images/docs/repo/repo-hero-circles-light.svg deleted file mode 100644 index 48c16ee..0000000 --- a/docs/public/images/docs/repo/repo-hero-circles-light.svg +++ /dev/null @@ -1,14 +0,0 @@ - - - - - - - - - \ No newline at end of file diff --git a/docs/public/images/docs/repo/repo-hero-logo-dark.svg b/docs/public/images/docs/repo/repo-hero-logo-dark.svg deleted file mode 100644 index 2f9aa1f..0000000 --- a/docs/public/images/docs/repo/repo-hero-logo-dark.svg +++ /dev/null @@ -1,32 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/public/images/docs/repo/repo-hero-logo-light.svg b/docs/public/images/docs/repo/repo-hero-logo-light.svg deleted file mode 100644 index ed2b023..0000000 --- a/docs/public/images/docs/repo/repo-hero-logo-light.svg +++ /dev/null @@ -1,21 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - diff --git a/docs/sentry.properties b/docs/sentry.properties index cbe2bba..82216e7 100644 --- a/docs/sentry.properties +++ b/docs/sentry.properties @@ -1,4 +1,3 @@ defaults.url=https://sentry.io/ -defaults.org=vercel -defaults.project=turborepo - +defaults.org=retrofor +defaults.project=HydroRoll \ No newline at end of file -- cgit v1.2.3-70-g09d2