diff options
| author | 2023-04-28 13:25:43 +0800 | |
|---|---|---|
| committer | 2023-04-28 13:25:43 +0800 | |
| commit | 30232223986c46c68b3587b28a46549f7bd5e743 (patch) | |
| tree | e5ce402985a5de2eb1896da600c3595bf5fec8e4 /docs | |
| parent | ce9321354d13b1152a91804ab46b1fdaac905d1d (diff) | |
| download | HydroRoll-30232223986c46c68b3587b28a46549f7bd5e743.tar.gz HydroRoll-30232223986c46c68b3587b28a46549f7bd5e743.zip | |
Diffstat (limited to 'docs')
35 files changed, 24 insertions, 2109 deletions
diff --git a/docs/content/team.ts b/docs/content/team.ts index 0130589..7f4b27e 100644 --- a/docs/content/team.ts +++ b/docs/content/team.ts @@ -1,72 +1,8 @@ const TURBO_TEAM: Record<string, AuthorDetails> = { - jaredpalmer: { - name: "Jared Palmer", - twitterUsername: "jaredpalmer", - picture: "/images/people/jaredpalmer.jpeg", - }, - gaspargarcia: { - name: "Gaspar Garcia", - twitterUsername: "gaspargarcia_", - picture: "/images/people/gaspargarcia.jpeg", - }, - becca__z: { - name: "Becca Z.", - twitterUsername: "becca__z", - picture: "/images/people/becca__z.jpeg", - }, - gregsoltis: { - name: "Greg Soltis", - twitterUsername: "gsoltis", - picture: "/images/people/gregsoltis.jpeg", - }, - nathanhammond: { - name: "Nathan Hammond", - twitterUsername: "nathanhammond", - picture: "/images/people/nathanhammond.png", - }, - tomknickman: { - name: "Tom Knickman", - twitterUsername: "tknickman", - picture: "/images/people/tomknickman.jpeg", - }, - mehulkar: { - name: "Mehul Kar", - twitterUsername: "mehulkar", - picture: "/images/people/mehulkar.jpeg", - }, - mattpocock: { - name: "Matt Pocock", - twitterUsername: "mattpocockuk", - picture: "/images/people/mattpocock.jpeg", - }, - tobiaskoppers: { - name: "Tobias Koppers", - twitterUsername: "wSokra", - picture: "/images/people/tobiaskoppers-avatar.jpg", - }, - alexkirsz: { - name: "Alex Kirszenberg", - twitterUsername: "alexkirsz", - picture: "/images/people/alexkirsz.jpg", - }, - anthonyshew: { - name: "Anthony Schew", - twitterUsername: "anthonysheww", - picture: "/images/people/anthonyshew.png", - }, - nicholasyang: { - name: "Nicholas Yang", - twitterUsername: "nicholaslyang", - picture: "/images/people/nicholasyang.png", - }, - chrisolszewski: { - name: "Chris Olszewski", - picture: "/images/people/chrisolszewski.jpg", - }, - alexanderlyon: { - name: "Alexander Lyon", - twitterUsername: "_arlyon", - picture: "/images/people/alexanderlyon.jpg", + HsiangNianian: { + name: "简律纯", + twitterUsername: "HsiangNianian", + picture: "/images/people/HsiangNianian.jpg", }, }; diff --git a/docs/pages/blog/_meta.json b/docs/pages/blog/_meta.json index 3de89ce..1bdc4e4 100644 --- a/docs/pages/blog/_meta.json +++ b/docs/pages/blog/_meta.json @@ -3,24 +3,11 @@ "//": "Hide all the links from the sidebar or navbar, and disable ToC and Sidebar for these pages.", "display": "hidden", "theme": { - "toc": false, - "sidebar": false, + "toc": true, + "sidebar": true, "pagination": false, "typesetting": "article" } }, - "turbo-1-9-0": "Turborepo 1.9", - "turbo-1-8-0": "Turborepo 1.8", - "turbo-1-7-0": "Turborepo 1.7", - "turbopack-benchmarks": "Turbopack Performance Benchmarks", - "turbo-1-6-0": "Turborepo 1.6", - "turbo-1-5-0": "Turborepo 1.5", - "turbo-1-4-0": "Turborepo 1.4", - "turbo-1-3-0": "Turborepo 1.3", - "turbo-1-2-0": "Turborepo 1.2", - "turbo-1-1-0": "Turborepo 1.1", - "joining-vercel": "Joining Vercel", - "saml-sso-now-available": "SAML SSO now available", - "you-might-not-need-typescript-project-references": "You might not need TypeScript project references", - "turbo-0-4-0": "Turborepo 0.4.0" + "hydroroll-0-1-3": "HydroRoll'水系 0.1.3" } diff --git a/docs/pages/blog/hydroroll-0-1-3.mdx b/docs/pages/blog/hydroroll-0-1-3.mdx new file mode 100644 index 0000000..8358dfd --- /dev/null +++ b/docs/pages/blog/hydroroll-0-1-3.mdx @@ -0,0 +1,17 @@ +--- +title: HydroRoll 0.1.3 +date: 2023/04/28 +description: 水系0.1.3发布 +tag: dev story +ogImage: /images/blog/joining-vercel/twitter-card.png +--- + +# Turborepo 0.4.0 + +import { Authors } from "../../components/Authors"; + +<Authors authors={["HsiangNianian"]} /> + +我很高兴能够发布 `v0.1.3` 版本的水系库, 这对我来说是个严峻的挑战——因为我的生活非常忙碌, 节奏很快——因此我也需要一些帮手来协助我, 让我欣慰的是, 我的朋友们大多数都非常支持我编写这样一个骰系系统。 + +是的, 他们非常支持我。
\ No newline at end of file diff --git a/docs/pages/blog/joining-vercel.mdx b/docs/pages/blog/joining-vercel.mdx deleted file mode 100644 index f84ec49..0000000 --- a/docs/pages/blog/joining-vercel.mdx +++ /dev/null @@ -1,23 +0,0 @@ ---- -title: Turborepo is joining Vercel -date: 2021/12/09 -description: Turborepo is joining Vercel to make the web even faster. -tag: web development -ogImage: /images/blog/joining-vercel/twitter-card.png ---- - -# Turborepo is joining Vercel - -import { Authors } from "../../components/Authors"; - -<Authors authors={["jaredpalmer"]} /> - -Turborepo has been acquired by Vercel and the Turborepo CLI is now open-source! Also, Turborepo now provides zero-config remote caching through [Vercel](https://vercel.com/?utm_source=turbo.build&utm_medium=referral&utm_campaign=docs-link)! - -beta.turborepo.com and its remote caching service will be shut down on January 15th, 2022 and older versions of the `turbo` CLI will not be installable. Learn more about how to upgrade your CLI and migrate to Vercel [here](/repo/docs/upgrading-to-v1). - -This is a milestone moment for the project and for all of you who have supported and adopted Turborepo. With Vercel's infrastructure and team backing, I'll expand on the capabilities of Turborepo and build out a team focused on improving their world-class build system. I can't wait to bring you along for this [next chapter](https://vercel.com/blog/vercel-acquires-turborepo). - -Join me this [Friday, December 10 at 4:00 p.m. ET | 9:00 p.m GMT for a livestream Q&A](https://www.youtube.com/watch?v=YX5yoApjI3M) with Vercel's Head of Developer Relations, Lee Robinson. We'll go over what's in store for Turborepo and Vercel as we work toward improving the developer experience together. - -This is just the beginning. We're about to embark on a world of even faster builds, even more flexibility, and even better workflows. Thanks for joining us on this amazing journey. diff --git a/docs/pages/blog/saml-sso-now-available.mdx b/docs/pages/blog/saml-sso-now-available.mdx deleted file mode 100644 index 0014cfc..0000000 --- a/docs/pages/blog/saml-sso-now-available.mdx +++ /dev/null @@ -1,52 +0,0 @@ ---- -title: SAML SSO is now available -date: 2021/08/03 -description: SAML Single Sign-on (SSO) is now available to Enterprise customers thanks to our friends over at WorkOS. -tag: web development -ogImage: /images/blog/saml-sso-now-available/twitter-card.png ---- - -# SAML SSO is now available - -import { Authors } from "../../components/Authors"; - -<Authors authors={["jaredpalmer"]} /> - -Thanks to our friends over at [WorkOS](https://workos.com/), in addition to GitHub, Gitlab, and Passwordless auth, Turborepo now supports Single Sign-on (SSO) from the following SAML providers for enterprise customers: - -- AD FS SAML -- Auth0 SAML -- Azure AD SAML -- CyberArk SAML -- Generic SAML -- G Suite OAuth -- G Suite SAML -- JumpCloud SAML -- Microsoft OAuth -- Okta SAML -- OneLogin SAML -- OpenID Connect -- PingFederate SAML -- PingOne SAML -- Shibboleth -- VMWare SAML - -We also support SCIM (a.k.a. "Directory Sync") via: - -- Azure AD SCIM -- BambooHR -- G Suite -- Gusto -- Hibob -- Okta SCIM v1.1 -- Okta SCIM v2.0 -- Rippling -- SCIM v1.1 -- SCIM v2.0 -- Workday - -If you're team in interested in activating SAML SSO, please contact us [turborepo@vercel.com](mailto:turborepo@vercel.com). - -## What's next? - -We take security extremely seriously. And while SSO is certainly a must in 2021, we are also currently undergoing a third-party SOC 2 Type 2 examination as well. Last but not least, we are adding biometric/U2F access controls and audit logs this fall. Stay tuned for updates. diff --git a/docs/pages/blog/turbo-0-4-0.mdx b/docs/pages/blog/turbo-0-4-0.mdx deleted file mode 100644 index c4b92ba..0000000 --- a/docs/pages/blog/turbo-0-4-0.mdx +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Turborepo 0.4.0 -date: 2021/04/02 -description: Turborepo 0.4.0 introduces 10x faster hashing, pruned workspaces with sparse installs, a new pipeline configuration API, and improved cache control. -tag: web development -ogImage: /images/blog/joining-vercel/twitter-card.png ---- - -# Turborepo 0.4.0 - -import { Authors } from "../../components/Authors"; - -<Authors authors={["jaredpalmer"]} /> - -I'm excited to announce the release of Turborepo v0.4.0! - -- **10x faster**: `turbo` has been rewritten from the ground up in Go to make it even more blazing fast -- **Smarter hashing**: Improved hashing algorithm now considers resolved dependencies instead of just the contents of the entire root lockfile -- **Partial lockfiles / sparse installs**: Generate a pruned subset of your root lockfile and monorepo that includes only the necessary packages needed for a given target -- **Fine-grained scheduling**: Improved task orchestration and options via `pipeline` configuration -- **Better cache control**: You can now specify cache outputs on a per-task basis - -## Rewritten in Go - -Although I initially prototyped `turbo` in TypeScript, it became clear that certain items on the roadmap would require better performance. After around a month or so of work, I'm excited to finally release Go version of the `turbo` CLI. Not only does it boot in a milliseconds, but the new Go implementation is somewhere between 10x and 100x faster at hashing than the Node.js implementation. With this new foundation (and some features you're about to read about), Turborepo can now scale to intergalactic sized projects while remaining blazing fast all thanks to Go's awesome concurrency controls. - -## Better Hashing - -Not only is hashing faster in v0.4.0, but also _a lot_ smarter. - -The major change is that `turbo` no longer includes the hash of the contents of the root lockfile in its hasher (the algorithm responsible for determining if a given task exists in the cache or needs to be executed). Instead, `turbo` now hashes the set of the resolved versions of a package's `dependencies` and `devDependencies` based on the root lockfile. - -The old behavior would explode the cache whenever the root lockfile changed in any way. With this new behavior, changing the lockfile will only bust the cache for those package's impacted by the added/changed/removed dependencies. While this sounds complicated, again all it means is that when you install/remove/update dependencies from npm, only those packages that are actually impacted by the changes will need to be rebuilt. - -## Experimental: Pruned Workspaces - -One of our biggest customer pain points/requests has been improving Docker build times when working with large Yarn Workspaces (or really any workspace implementation). The core issue is that workspaces' best feature--reducing your monorepo to a single lockfile--is also its worst when it comes to Docker layer caching. - -To help articulate the problem and how `turbo` now solves it, let's look at an example. - -Say we have a monorepo with Yarn workspaces that includes a set of packages called `frontend`, `admin`, `ui`, and `backend`. Let's also assume that `frontend` and `admin` are Next.js applications that both depend on the same internal React component library package `ui`. Now let's also say that `backend` contains an Express TypeScript REST API that doesn't really share much code with any other part of our monorepo. - -Here's what the Dockerfile for the `frontend` Next.js app might look like: - -```docker {7} -FROM node:alpine AS base -RUN apk update -WORKDIR /app - -# Add lockfile and package.jsons -FROM base AS builder -COPY *.json yarn.lock ./ -COPY packages/ui/*.json ./packages/ui/ -COPY packages/frontend/*.json ./packages/frontend/ -RUN yarn install - -# Copy source files -COPY packages/ui/ ./packages/ui/ -COPY packages/frontend/ ./packages/frontend/ - -# Build -RUN yarn --cwd=packages/ui/ build -RUN yarn --cwd=packages/frontend/ build - -# Start the Frontend Next.js application -EXPOSE 3000 -RUN ['yarn', '--cwd', 'packages/frontend', 'start'] -``` - -While this works, there are some things that could be a lot better: - -- You manually `COPY` in the internal packages and files needed to build the target app and need to remember which need to be built first. -- You `COPY` the root `yarn.lock` lockfile into the correct position very early in the Dockerfile, but this lockfile is the lockfile for the _entire_ monorepo. - -This last issue is especially painful as your monorepo gets larger and larger because any change to this lockfile triggers a nearly full rebuild regardless of whether or not the app is actually impacted by the new/changed dependencies. - -....until now. - -With the all new `turbo prune` command, you can now fix this nightmare by deterministically generating a sparse/partial monorepo with a pruned lockfile for a target package--without installing your `node_modules`. - -Let's look at how to use `turbo prune` inside of Docker. - -```docker {11,16} -FROM node:alpine AS base -RUN apk update && apk add git - -## Globally install `turbo` -RUN npm i -g turbo - -# Prune the workspace for the `frontend` app -FROM base as pruner -WORKDIR /app -COPY . . -RUN turbo prune --scope=frontend --docker - -# Add pruned lockfile and package.json's of the pruned subworkspace -FROM base AS installer -WORKDIR /app -COPY --from=pruner /app/out/json/ . -COPY --from=pruner /app/out/yarn.lock ./yarn.lock -# Install only the deps needed to build the target -RUN yarn install - -# Copy source code of pruned subworkspace and build -FROM base as builder -WORKDIR /app -COPY --from=pruner /app/.git ./.git -COPY --from=pruner /app/out/full/ . -COPY --from=installer /app/ . -RUN turbo run build --scope=frontend - -# Start the app -FROM builder as runner -EXPOSE 3000 -RUN ['yarn', '--cwd', 'packages/frontend', 'start'] -``` - -So what exactly is the output of the `turbo prune`? A folder called `out` with the following inside of it: - -- A folder `json` with the pruned workspace's package.jsons -- 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. - -Thanks to the above, Docker can now be set up to only rebuild each application when there is a real reason to do so. So `frontend` will only rebuild when its source or dependencies (either internal or from npm) have actually changed. Same same for `admin` and `backend`. Changes to `ui`, either to its source code or dependencies, will trigger rebuilds of both `frontend` and `admin`, but _not_ `backend`. - -While this example seems trivial, just imagine if each app takes up to 20 minutes to build and deploy. These savings really start to add up quickly, especially on large teams. - -## Pipelines - -To give you even more control over your Turborepo, we've added `pipeline` to `turbo`'s configuration. This new field in lets you specify how the npm scripts in your monorepo relate to each other as well as some additional per-task options. `turbo` then uses this information to optimally schedule your tasks in your monorepo, collapsing waterfalls that would otherwise exist. - -Here's how it works: - -```json -// <root>/package.json -{ - "turbo": { - "pipeline": { - "build": { - // This `^` tells `turbo` that this pipeline target relies on a topological target being completed. - // In english, this reads as: "this package's `build` command depends on its dependencies' or - // devDependencies' `build` command being completed" - "dependsOn": ["^build"] - }, - "test": { - // `dependsOn` without `^` can be used to express the relationships between tasks at the package level. - // In English, this reads as: "this package's `test` command depends on its `lint` and `build` command first being completed" - "dependsOn": ["lint", "build"] - }, - "lint": {}, - "dev": {} - } - } -} -``` - -The above config would then be interpreted by `turbo` to optimally schedule execution. - -What's that actually mean? In the past (like Lerna and Nx), `turbo` could only run tasks in topological order. With the addition of pipelines, `turbo` now constructs a topological "action" graph in addition to the actual dependency graph which it uses to determine the order in which tasks should be executed with maximum concurrency. The end result is that you no longer waste idle CPU time waiting around for stuff to finish (i.e. no more waterfalls). - - - -## Improved Cache Control - -Thanks to `pipeline`, we now have a great place to open up `turbo`'s cache behavior on a per-task basis. - -Building on the example from above, you can now set cache output conventions across your entire monorepo like so: - -```json -// <root>/package.json -{ - "turbo": { - "pipeline": { - "build": { - // Cache anything in dist or .next directories emitted by a `build` command - "outputs": ["dist/**", ".next/**", "!.next/cache/**"] - "dependsOn": ["^build"] - }, - "test": { - // Cache the test coverage report - "outputs": ["coverage/**"], - "dependsOn": ["lint", "build"] - }, - "dev": { - // Never cache the `dev` command - "cache": false - }, - "lint": {}, - } - } -} -``` - -_Note: Right now, `pipeline` exists at the project level, -but in later releases these will be overridable on per-package basis._ - -## What's Next? - -I know this was a lot, but there's even more to come. Here's what's up next on the Turborepo roadmap. - -- A landing page! -- [Remote caching w/ `@turborepo/server`](https://twitter.com/jaredpalmer/status/1359627800840462341) -- Build scans, telemetry, and metrics and dependency and task graph visualization -- [Desktop Console UI](https://twitter.com/jaredpalmer/status/1360315387372572672) -- Intelligent `watch` mode -- Official build rules for TypeScript, React, Jest, Node.js, Docker, Kubernetes, and more - -## Credits - -- [Iheanyi Ekechukwu](https://twitter.com/kwuchu) for guiding me through the Go ecosystem -- [Miguel Oller](https://twitter.com/ollermi) and the team from [Makeswift](https://www.makeswift.com/) for iterating on the new `prune` command diff --git a/docs/pages/blog/turbo-1-1-0.mdx b/docs/pages/blog/turbo-1-1-0.mdx deleted file mode 100644 index d111a09..0000000 --- a/docs/pages/blog/turbo-1-1-0.mdx +++ /dev/null @@ -1,141 +0,0 @@ ---- -title: Turborepo 1.1 -date: 2022/01/31 -description: Turborepo 1.1 introduces automatic migrations, turbo.json configuration, environment variable dependencies, partial Yarn v2 support, and more! -tag: web development -ogImage: /images/blog/turbo-1-1-0/twitter-card.png ---- - -# Turborepo 1.1 - -import { Authors } from "../../components/Authors"; - -<Authors authors={["jaredpalmer", "becca__z", "gaspargarcia", "gregsoltis"]} /> - -Since releasing Turborepo v1.0 in mid-December, we've seen incredible adoption: - -- 5.5k+ GitHub Stars -- 70k+ weekly npm downloads -- 65+ OSS contributors -- In production at [Vercel](https://github.com/vercel/next.js), [AWS](https://github.com/aws-amplify/amplify-ui), [PayPal](https://twitter.com/jaredpalmer/status/1485617973477978121), [Twilio](https://github.com/twilio-labs/function-templates), [Contentful](https://github.com/contentful/forma-36), [Miro](https://github.com/miroapp/app-examples), [Framer](https://github.com/framer/motion), [Discord.js](https://github.com/discordjs/discord.js), [Rocket.chat](https://github.com/RocketChat/fuselage), [Astro.build](https://github.com/withastro/astro) -- 585+ members of the [Turborepo Community Discord](https://turbo.build/discord) - - - -We're further improving build performance and caching with Turborepo v1.1, featuring: - -- [**Automatic Migrations:**](#automatic-migrations) Official idempotent migration scripts to assist with upgrading. -- [**`turbo.json` Support:**](#turbojson-support) Turborepo configuration now lives in its own file. -- [**Faster Package Manager Detection:**](#faster-package-manager-detection) Turborepo now respects the `packageManager` key in the root `package.json`. -- [**Environment Variable Dependencies:**](#environment-variable-dependencies) Define how environment variables impact global and task-specific caching. -- [**Partial Support for Yarn v2+:**](#partial-yarn-v2v3-support) Support for yarn v2+ with `nodeLinker: "node-modules"`. - -Update today by running `npm install turbo@latest`. After running `turbo`, you'll see instructions about how to use `@turbo/codemod` to run automatic migrations for `v1.1`. - -## Automatic Migrations - -Turborepo now provides idempotent code transformations and automatic migration scripts (a.k.a "codemods") to help upgrade your Turborepo codebase when a feature is deprecated or will be deprecated in the future. - -Codemods are transformations that run on your codebase programmatically. This saves you time by applying a large number of changes to your code automatically, without having to manually go through and edit every file. - -### Usage - -```bash -npx @turbo/codemod <transform> <path> -``` - -- `transform` - the name of transform, [see available transforms in the docs](/repo/docs/reference/codemods#turborepo-1x). -- `path` - files or directory to transform. -- `--dry` - Do a dry run, no code will be edited. -- `--print` - Prints the changed output for comparison. - -For more information about specific transforms, check out the [new Codemods documentation](/repo/docs/reference/codemods#turborepo-1x). - -## `turbo.json` Support - -Turborepo configuration is now defined in a `turbo.json` file in the root of your monorepo. This is an improvement over having a `turbo` key in `package.json` for those who want to quickly jump straight to their Turborepo configuration in their code editors. - -To automatically migrate from your current configuration in `package.json`, check out a new branch, navigate to the root of your monorepo and run the following codemod: - -```bash -npx @turbo/codemod create-turbo-config . -``` - -For more information on this transformation, [check out the documentation](/repo/docs/reference/codemods#create-turbo-config). - -## Faster Package Manager Detection - -Turborepo now supports the recently established `packageManager` field in `package.json` for faster package manager detection. Previously, `turbo` would check for specific files to infer this information. To automatically set this field, check out a new branch, navigate to the root of your monorepo and run: - -```bash -npx @turbo/codemod add-package-manager . -``` - -For more information on this transformation, [check out the documentation](/repo/docs/reference/codemods#add-package-manager). - -## Environment Variable Dependencies - -When you use `turbo` with tools that inline environment variables at build time (e.g. Next.js or Create React App), it is important you tell `turbo` about it to avoid shipping a cached artifact with the wrong environment variables. - -You can now control `turbo`'s [cache fingerprinting (a.k.a. hashing)](/repo/docs/core-concepts/caching#hashing) behavior based on the values of both environment variables and the contents of files: - -- Including environment variables in a `dependsOn` in your `pipeline` definition prefixed by a `$` will impact the cache fingerprint on a per-task or per-package-task basis. -- Including environment variables in `globalDependencies` list prefixed by a `$` will impact the cache fingerprint of _all_ tasks. -- Including files or globs of files in `globalDependencies` will impact the cache fingerprint of _all_ tasks. -- The value of any environment variable that includes `THASH` in its name will impact the cache fingerprint of _all_ tasks. - -```jsonc -{ - "pipeline": { - "build": { - "dependsOn": { - "^build" - // env vars will impact hashes of all "build" tasks - "$SOME_ENV_VAR" - }, - "outputs": ["dist/**"] - }, - "web#build": { // override settings for the "build" task for the "web" app - "dependsOn": [ - "^build", - // 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/**"], - }, - "docs#build": { // override settings for the "build" task for the "docs" app - "dependsOn": [ - "^build", - // 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/**"], - } - }, - "globalDependencies": [ - "$GITHUB_TOKEN"// env var that will impact the hashes of all tasks, - "tsconfig.json" // file contents will impact the hashes of all tasks, - ".env.*" // glob file contents will impact the hashes of all tasks, - ] -} -``` - -Note: In most monorepos, you don't often use environment variables in shared packages, but mostly in applications. Thus, to get higher cache hit rates, you should only include environment variables in the app-specific tasks where they are used/inlined. - -For more information, read the [caching and hashing documentation](/repo/docs/core-concepts/caching). - -## Partial Yarn v2/v3 support - -In addition to Yarn v1, npm, and pnpm package managers, Turborepo now supports Yarn v2+ with [`nodeLinker: "node-modules"` set in `.yarnrc.yml`](https://yarnpkg.com/configuration/yarnrc#nodeLinker). This key tells Yarn v2+ to mimic Yarn v1's `node_modules` installation behavior. Yarn v2+ Plug'n'Play (a.k.a. "PnP") is not currently supported. - -## What's next? - -[Since our launch](/blog/joining-vercel), Turborepo has focused on seamless incremental adoption/migration and speeding up CI/CD. We are committed to both of those values, but now we'll also be focusing on improving Turborepo's day-to-day ergonomics for local development and observability. We're really excited about this next chapter and will be sharing more details soon. - -## We're hiring! - -The Turborepo team at [Vercel](https://vercel.com/) is hiring! We're specifically looking for full time [Senior Full Stack Software Engineers](https://vercel.com/careers) and [Senior DevOps/Infrastructure Engineers](https://vercel.com/careers) to help us make Turborepo even better. diff --git a/docs/pages/blog/turbo-1-2-0.mdx b/docs/pages/blog/turbo-1-2-0.mdx deleted file mode 100644 index 1b49f6f..0000000 --- a/docs/pages/blog/turbo-1-2-0.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: Turborepo 1.2 -date: 2022/04/08 -description: Turborepo 1.2 introduces improved task filtering, artifact signing and integrity, human-readable and JSON dry runs, and more! -tag: web development -ogImage: /images/blog/turbo-1-2-0/twitter-card.png ---- - -# Turborepo 1.2 - -import { Authors } from "../../components/Authors"; -import Date from "../../components/blog/Date"; - -<Date> - Friday, April 8th, 2022 -</Date> - -<Authors authors={["jaredpalmer", "becca__z", "gaspargarcia", "gregsoltis"]} /> - -Since releasing Turborepo v1.1 in late January, we've seen incredible adoption and community growth: - -- **6.5k+** [GitHub Stars](https://github.com/vercel/turbo) -- **140k+** weekly npm downloads (doubling since our [last blog post for v1.1](/blog/turbo-1-1-0)) -- **95+** OSS contributors -- **900+** members of the [Turborepo Community Discord](https://turbo.build/discord) -- **1.6 years** of Time Saved through Remote Caching on Vercel, saving more than 2.5 months every week - -We've further improved ergonomics, observability, and security with Turborepo v1.2 featuring: - -- [**New Task Filtering API**](#new-task-filtering-api): `--filter` adds more powerful task filtering capabilities to `turbo run` -- [**Human-readable and JSON dry runs**](#debug-and-automate-with---dry-run): `--dry-run` flag can print out information about a `turbo run` without executing any tasks, in both human and JSON-parse friendly formats -- [**Improved Internal Scheduler and Graph**](#improved-internal-scheduler-and-graph): We refactored `turbo` 's internal scheduler and graph to be more ergonomic and predictable -- [**Enhanced Remote Cache Security**](#cache-outputs-integrity-and-signature-verification): Cryptographically sign remote cache artifacts with your own secret key - -Update today by running `npm install turbo@latest`. After running `turbo run` for the first time, you'll see instructions about how to use `@turbo/codemod` to run automatic migrations for `v1.2`. - -## New Task Filtering API - -We are excited to release one of our most requested features: the ability to expressively filter tasks through a `--filter` flag. The `--filter` flag is the much more powerful successor to the current combination of `--scope`, `--include-dependencies`, `--since`, and `--no-deps` flags. - -With `--filter` you can tell `turbo` to restrict executing commands to a subset of matched packages in your monorepo based on name, folder, or even if it has changed since a git commit ref. - -Take a look at some examples of what you can accomplish with the new `--filter` command: - -- `--filter=<package_name>` - match by exact package name or glob pattern -- `--filter=...<package_name>`- match by package name/glob and include all dependent packages of matches -- `--filter=...^<package_name>`- match by package name/glob and include all dependent packages of matches, but exclude the matches themselves -- `--filter=<package_name>...` - match by package name/glob and include all the matched packages' dependencies -- `--filter=<package_name>^...` - match by package name/glob and include all matched package dependencies, but exclude the matches themselves -- `--filter={./path/to/package}` - match by path or filesystem glob pattern -- `--filter=[origin/main]` - match by changed packages since a git commit ref - -You can use multiple filters together to get even more granular filtering as well as combine each part of the above patterns `{}`, `[]` , `^` , and `...` to express more complex behavior. - -For example, if you had an app located in `./apps/web` directory with local packages used as dependencies, and a Turborepo pipeline where `test` depends on `^build` topologically, running: - -```sh -turbo run test --filter={./apps/web}[HEAD^1]^... -``` - -would tell `turbo` to ensure dependencies are built and to run the `test` script in all of the local dependencies of the app located in `./apps/web`, not including that app itself, if the app has changed since HEAD^1. - -For more details and examples, refer to the new [filtering documentation](/repo/docs/core-concepts/monorepos/filtering). - -## Debug and Automate with `--dry-run` - -You can now see the impact of `turbo run` without actually executing any commands by appending either `--dry-run` or `--dry-run=json` to any `turbo run` command. This will result in either human or JSON output. - -Dry runs are incredibly useful for two situations: - -- Debugging and testing run options -- Using `turbo` filtering and task graphs for building automations - -import { Bleed } from "nextra-theme-docs"; - -<Bleed> - <div className="lg:rounded-xl overflow-hidden"> -  - </div> -</Bleed> - -We hope that this will improve visibility into what `turbo` is doing, speeding up debugging, and make it easier to leverage `turbo` in dynamic CI/CD systems. - -## Improved Internal Scheduler and Graph - -When using `turbo run`, every `package.json` task is added to an internal graph to map dependencies based on the inferred relationships defined in your Turborepo `pipeline`. This task graph allows Turborepo to efficiently schedule incremental concurrent task running and cache task outputs for later use. - -We have made major improvements to the internal task scheduler and resulting graph structure, resulting in better performance and a better developer experience. For example, in many cases, you will no longer need to use `--include-dependencies`. Instead, after specifying your task entry points, the new and improved graph will automatically handle this graph resolution on your behalf. - -## Cache Outputs Integrity and Signature Verification - -You can now configure Turborepo to sign remote cache outputs using HMAC-SHA256 with a secret key before uploading them to the Remote Cache. When Turborepo downloads signed cache artifacts, it will now verify the artifact's integrity and authenticity. Any artifact that fails to verify will be ignored, discarded, and treated as a cache miss by Turborepo. - -To enable this feature, set the `remoteCache` options in your `turbo.json` config file 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](https://turbo.build/schema.json)", - "remoteCache": { - // Indicates if signature verification is enabled. - "signature": true - } -} -``` - -## Other bug fixes and improvements - -- `--sso-team` flag now enables teams with SAML tokens to log in through `turbo login` with correct team permissions -- `--log-output` flag allows you to control what logs are printed to the terminal, and when, allowing you to focus only on what's new -- `FORCE_COLOR` environment variable is now supported -- `TURBO_FORCE=true` environment variable will now force execution -- `--remote-only` and `TURBO_REMOTE_ONLY=true` will tell `turbo` to only use Remote Caching -- We now show `>>> FULL TURBO` when there's at least one task attempted -- Yarn v2+ with Plug'n'Play (PnP linker) is supported for the `turbo run` command, but `turbo prune` is still not fully supported -- Fixed regression with chrome tracing if `--profile` is specified -- You can now set concurrency by percentage of CPUs with `--concurrency=50%` - -## We're hiring! - -The Turborepo team at [Vercel](https://vercel.com/) is hiring! We're up to five core team members already this year and are looking to hire even more. We're specifically looking for full-time [Senior Build Systems Engineers](https://vercel.com/careers). - -## What's next? - -Along with seamless incremental adoption/migration and speeding up CI/CD, we've been focusing on improving Turborepo's day-to-day ergonomics, security, and observability. The new `--filter` flag, signed artifacts, and dry runs are important steps toward those goals. - -Next up, we'll be focusing an enhanced local development experience, codebase automations, and overall CLI performance. - -## Thank you, contributors - -Turborepo is the result of the combined work of over 95 individual developers and our core team. - -This release was brought to you by the contributions of: @gsoltis09, @jaredpalmer, @gaspar09, @shuding, @rajatkulkarni95, @VanTanev, @Kikobeats, @tknickman, @thebanjomatic, @chelkyl, @elado, @finn-orsini, @becca, @weyert, @ekosz diff --git a/docs/pages/blog/turbo-1-3-0.mdx b/docs/pages/blog/turbo-1-3-0.mdx deleted file mode 100644 index f84b57e..0000000 --- a/docs/pages/blog/turbo-1-3-0.mdx +++ /dev/null @@ -1,202 +0,0 @@ ---- -title: Turborepo 1.3 -date: 2022/06/23 -description: Turborepo 1.3 introduces restricted hash inputs, root script running and caching, new CI/CD Recipes, and more! -tag: web development -ogImage: /images/blog/turbo-1-3-0/twitter-card.png ---- - -# Turborepo 1.3 - -import { Authors } from "../../components/Authors"; -import Callout from "../../components/Callout"; -import Date from "../../components/blog/Date"; - -<Date> - Thursday, June 23rd, 2022 -</Date> - -<Authors - authors={[ - "gregsoltis", - "nathanhammond", - "tomknickman", - "jaredpalmer", - "gaspargarcia", - "becca__z", - ]} -/> - -With Turborepo 1.3 we are bringing improved caching and flexibility which includes: - -- [**Restricted hash inputs:**](#pipeline-inputs) Specify the files in a package folder that impact caching with `inputs`. -- [**Root script running and caching:**](#run-and-cache-scripts-from-the-root-of-your-monorepo) Run and cache `package.json` scripts from the root of the monorepo. -- [**New CI/CD Recipes:**](#new-cicd-recipes) We added recipes for using Turborepo with popular CI providers. - -Update today by running `npm install turbo@latest`. - -## Pipeline `inputs` - -In addition to [environment variables, dependencies, and pipeline configurations,](/repo/docs/core-concepts/caching#hashing) `turbo` will consider all non-gitignored files in package folder when calculating each `package.json` script's hash fingerprint (the key that `turbo` uses to index its cache and to determine if a script needs to be re-executed). **With Turborepo 1.3+, you can now specify globs of `inputs` in your `turbo.json` `pipeline` to control which files are relevant for a particular script for caching.** This means that you can now express the following in `turbo.json` - -- Ignore changes to all markdown files in a package or app's folder. -- Don't bother rebuilding an app if only its test files have changed. -- Only re-run tests if either source files or test files have been changed in a package or folder. -- and more. - -Let's walk through a concrete example: imagine we have a monorepo with a Next.js application for a documentation website in `./apps/docs-site`, some packages, and some markdown files in the root of the monorepo in a `./docs` folder. - -```sh filename="Example monorepo" -. -├── docs/ -│ ├── api-reference.md -│ ├── getting-started.md -│ └── intro.md -├── apps/ -│ ├── docs-site/ -│ │ ├── components/ -│ │ ├── pages/ -│ │ │ └── [slug].js -│ │ ├── README.md -│ │ └── package.json -│ └── web-site/ -│ ├── pages/ -│ ├── README.md -│ └── package.json -├── packages/ -│ ├── configs/ -│ └── ui/ -├── package.json -└── turbo.json -``` - -Let's assume that the Next.js `docs-site` renders the markdown files from the `./docs` folder. We can now set up the `build` script in the app's `package.json` to use `inputs` in `turbo.json` to better specify exactly which files are relevant (and which should impact caching) as follows: - -```jsonc filename="./turbo.json" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - // ... omitted for brevity - "build": { - "dependsOn": ["^build"], - "outputs": [".next/**", "!.next/cache/**", "dist/**"] - }, - "docs#build": { - "dependsOn": ["^build"], - "outputs": [".next/**", "!.next/cache/**"], - // Define set of relevant globs which impact caching of docs site - // builds - "inputs": [ - "../../docs/**/*.md", - "pages/**", - "components/**", - "package.json" - ] - } - } -} -``` - -Note: Like `outputs`, `inputs` are defined relative to the related `package.json` , but they can be outside of a given folder (`e.g. ../../docs/**`). - -## Run and cache scripts from the root of your monorepo - -As of 1.3, **`turbo` can now run and cache scripts from the `package.json` file at the root of the monorepo**, which will help significantly when migrating to Turborepo. - -To set this up, specify a root script in your `pipeline` configuration in your `turbo.json` using the form `"//#<script>": {...}`. The `//` tells `turbo` that the script is relative to the root of the monorepo and not each workspace package. - -There are 2 important things to note about root scripts and execution scope: - -- If you already have `"build": {...}` in your `pipeline`, but want to include the `build` script defined in the monorepo's root `package.json` file when running `turbo run build`, you may opt the root into the execution's scope by also including `"//#build": {...}` in your configuration as well. -- Conversely, you _do not_ need to define a generic `"my-script": {...}` entry if all you need is `"//#my-script": {...}`. - -A sample pipeline that defines the root script `check-examples` and opts the root into `test` might look like: - -```json filename="./package.json" -{ - "name": "my-turborepo", - "private": true, - "scripts": { - "test": "echo 'test!'", - "check-examples": "./check-examples.sh" - }, - "devDependencies": { - "turbo": "latest" - } -} -``` - -```jsonc filename="./turbo.json" highlight="20" -{ - "$schema": "https://turbo.build/schema.json", - "pipeline": { - "build": { - "dependsOn": ["^build"] - }, - "test": { - "dependsOn": ["^build"], - "outputs": [] - }, - // This will cause the "test" script from all workspace package.json's - // AND the root package.json to be included when "turbo run test" is run - "//#test": { - "dependsOn": [], - "outputs": [] - }, - // This will cause the "check-examples" script in the root package.json - // to be run when "turbo run check-examples" is run. Since a general - // "check-examples" script is not defined in the pipeline, only the root - // package.json's "check-examples" script will be included - // when "turbo run check-examples" is run - "//#check-examples": { - "dependsOn": [], - "outputs": [], - "inputs": [ - "examples/**/*.ts", - "examples/**/*.tsx", - "examples/**/*.json", - "examples/**/*.js", - "examples/**/*.yaml", - "cli/**/*.ts", - "./scripts/run-example.sh" - ] - } - } -} -``` - -Note: We suggest specifying `inputs` whenever declaring a root task in your `pipeline` to improve caching. - -## New CI/CD Recipes - -We added recipes for using Turborepo and Remote Caching with: - -- [CircleCI](/repo/docs/ci/circleci) -- [GitHub Actions](/repo/docs/ci/github-actions) -- [Gitlab CI](/repo/docs/ci/gitlabci) -- [Travis CI](/repo/docs/ci/travisci) - -If there are other recipes you would like to see here please let us know by opening up a [GitHub Discussion](https://github.com/vercel/turbo/discussions/categories/ideas). - -## Other Bug Fixes and Improvements - -- Improved git operations and hashing -- Better cycle detection in dependency graph analysis -- Added support for Windows ARM 64-bit architectures -- Improved Remote Cache error logging -- Added Storybook to the Design System example - -## Community - -Since releasing [Turborepo v1.2 in early April](/blog/turbo-1-2-0), we've seen incredible adoption and community growth: - -- [8.1k+ GitHub Stars](https://github.com/vercel/turbo) -- 275k+ weekly NPM downloads (up ~2x) -- 1,200+ members of the [Turborepo Community Discord](https://turbo.build/discord) -- 5.8 years of compute time saved through Remote Caching on Vercel (up ~5x), saving +7 months per week now - -Turborepo is the result of the combined work of over 136 contributors including our core team. - -This release was brought to you by the contributions of: @gsoltis, @nathanhammond, @tknickman, @jaredpalmer, @zvictor, @ObliviousHarmony, @O4epegb, @rafaeltab, @mcmontseny, @bertspaan, @Jastor11, and @enBonnet - -Thank you for your continued support, feedback, and collaboration with us to make Turborepo your build tool of choice. diff --git a/docs/pages/blog/turbo-1-4-0.mdx b/docs/pages/blog/turbo-1-4-0.mdx deleted file mode 100644 index b599def..0000000 --- a/docs/pages/blog/turbo-1-4-0.mdx +++ /dev/null @@ -1,139 +0,0 @@ ---- -title: Turborepo 1.4 -date: 2022/08/09 -description: Turborepo 1.4 has new examples, automatically includes environment variables, and more! -tag: web development -ogImage: /images/blog/turbo-1-4-0/twitter-card.png ---- - -# Turborepo 1.4 - -import { Authors } from "../../components/Authors"; -import Callout from "../../components/Callout"; -import Date from "../../components/blog/Date"; - -<Date> - Tuesday, August 9th, 2022 -</Date> - -<Authors - authors={[ - "gregsoltis", - "nathanhammond", - "tomknickman", - "anthonyshew", - "jaredpalmer", - "mehulkar", - ]} -/> - -Turborepo 1.4 brings: - -- [**Automatic environment variable inclusion:**](#automatic-environment-variable-inclusion) We'll automatically infer popular framework environment variables for you. No need to declare them yourself in `turbo.json`. -- [**`eslint-config-turbo`:**](#eslint-config-turbo) Enhanced feedback with a new ESLint plugin. -- [**New framework and library examples:**](#new-framework-and-library-examples) New starters and examples requested by the community. - -Update today by running `npm install turbo@latest`. - -## Automatic environment variable inclusion - -To help ensure correct caching across environments Turborepo will now automatically infer and include public environment variables when calculating cache keys for apps built with Astro, Create React App, Gatsby, Next.js, Nuxt, SvelteKit, Vite, Vue, and more. You can safely remove framework-specific public environment variables from `turbo.json` if you manually declared them. - -```diff filename="turbo.json" -{ - "pipeline": { - "build": { - "dependsOn": [ - "^build" -- // Include build time public inlined environment variables that -- // are different in development and production, so that -- // Turborepo does not use the same cached build -- // across environments -- "$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. Additionally, 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": { - "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. - -This improvement in hash specificity by framework is a significant step toward optimal, safe, and correct caching. - -## `eslint-config-turbo` - -We've also created a new ESLint config for further in-editor assistance to help ensure your Turborepo cache can be correctly shared across every environment. While our new hashing algorithm should cover most situations with most frameworks, this ESLint config will provide in-editor feedback for teams using other build time inlined environment variables that are not framework-prefixed but impact build outputs (i.e. caching), and teams using their own 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": ["next/core-web-vitals", "turbo"] -} -``` - -If you prefer more control over the rules - use can install and configure the `eslint-plugin-turbo` _plugin_ directly by first adding it to plugins and then configuring the desired rules: - -```jsonc -{ - "extends": ["next/core-web-vitals"], - "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`. - -As of 1.4.x, we now include `eslint-config-turbo` in all of our examples and in new projects generated via `npx create-turbo`. - -Learn more about ESLint configs and plugins in the [ESLint docs](https://eslint.org/docs/latest/). - -## New framework and library examples - -Based on your feedback and suggestions, we've created new examples to integrate Turborepo into your workflow: - -- [Svelte](https://github.com/vercel/turbo/tree/main/examples/with-svelte) -- [Docker](https://github.com/vercel/turbo/tree/main/examples/with-docker) -- [Create React App](https://github.com/vercel/turbo/tree/main/examples/with-create-react-app) -- [React Native](https://github.com/vercel/turbo/tree/main/examples/with-react-native-web) -- [Prisma](https://github.com/vercel/turbo/tree/main/examples/with-prisma) -- [Tailwind](https://github.com/vercel/turbo/tree/main/examples/with-tailwind) -- … [and more!](https://github.com/vercel/turbo/tree/main/examples) - -## Other bug fixes and improvements - -- Allow both sides of git comparison ([#1442](https://github.com/vercel/turbo/pull/1442)) -- Properly rebuild packages that share a name prefix ([#1538](https://github.com/vercel/turbo/pull/1538)) -- Cache files with the correct file permissions ([#1429](https://github.com/vercel/turbo/pull/1429)) - -## Community - -Since releasing [Turborepo v1.3 in June](https://turbo.build/blog/turbo-1-3-0), we've seen incredible adoption and community growth: - -- [8.65k+ GitHub Stars](https://github.com/vercel/turbo) -- 365k weekly NPM downloads, up 2x since late April -- 10 years of compute time saved through Remote Caching on Vercel, saving 10 months per week - -Turborepo is the result of the combined work of all of our contributors including our core team. - -This release was brought to you by the contributions of: @B2o5T, @chitchu, @elis, @gsoltis, @harshcut, @jaredpalmer, @kocisov, @nathanhammond, @neolivz, @NuroDev, @oneezy, @samouri, @shayc, @StevenMatchett, @tknickman, @trevorr, @zsoldosp, and more! - -Thank you for your continued support, feedback, and collaboration to make Turborepo your build tool of choice. diff --git a/docs/pages/blog/turbo-1-5-0.mdx b/docs/pages/blog/turbo-1-5-0.mdx deleted file mode 100644 index ed33779..0000000 --- a/docs/pages/blog/turbo-1-5-0.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: Turborepo 1.5 -date: 2022/09/19 -description: Turborepo 1.5 brings the Monorepo Handbook, drops the 'run' command, improves pruning, and much more! -tag: web development -ogImage: /images/blog/turbo-1-5-0/twitter-card.png ---- - -# Turborepo 1.5 - -import { Authors } from "../../components/Authors"; -import Callout from "../../components/Callout"; -import Date from "../../components/blog/Date"; - -<Date> - Monday, September 19th, 2022 -</Date> - -<Authors - authors={[ - "mattpocock", - "gregsoltis", - "nathanhammond", - "tomknickman", - "anthonyshew", - "jaredpalmer", - "mehulkar", - "chrisolszewski", - ]} -/> - -Turborepo 1.5 is a **huge leap forward for our documentation and DX**, as well as bringing big improvements to `turbo prune`: - -- [**The Monorepo Handbook**](#the-monorepo-handbook): We've built the missing manual for your monorepo - a guide on workspaces, code sharing, integrating common tools and much more. -- [**Drop the `run`**](#drop-the-run): `turbo run <task>` can now be shortened to `turbo <task>` -- [**`turbo prune` now supports pnpm and yarn 2+**](#prune-now-supported-on-pnpm-and-yarn-2): Pruning your monorepo is now supported in `pnpm` and `yarn@berry`. -- [**Improved environment variables in `turbo.json`**](#environment-variables-in-turbojson): Environment variables are now first-class citizens in your Turborepo pipeline configuration. -- [**Changes to `package.json` hashing**](#changes-to-packagejson-hashing): We've improved how we hash `package.json` when running tasks. - -Update today by running `npm install turbo@latest`. - -## The Monorepo Handbook - -Setting up a monorepo for the first time often means navigating a lot of new concepts. You'll need to understand workspaces, package installation, sharing code and dependency management - and a lot more. - -This often meant that folks who wanted to set up a monorepo from scratch had to piece information together from different documentation sites. First `pnpm`, then `tsup`, then back to `changesets`, then back to Turborepo for dessert. - -We want to fill this gap with [the Monorepo Handbook](/repo/docs/handbook). We've built guides on how to integrate all the tools you'll need to make ship happen with your monorepo, including guides on: - -- [Installing Packages](/repo/docs/handbook/package-installation) -- [Linting](/repo/docs/handbook/linting) -- [Development Tasks](/repo/docs/handbook/dev) -- [Building Apps](/repo/docs/handbook/building-your-app) -- [Publishing Packages](/repo/docs/handbook/publishing-packages) - -## Drop the `run` - -<iframe - className="max-w-xl h-72 sm:h-96 w-full mt-6" - src="https://www.youtube.com/embed/PEgk2v6KntY" - title="YouTube video player" - frameborder="0" - allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" -></iframe> - -You can now run tasks with the Turborepo CLI using `turbo <task>`. - -```diff -- turbo run build -+ turbo build - - -- turbo run lint build test -+ turbo lint build test -``` - -If your task name conflicts with a built-in `turbo` subcommand, we'll run our subcommand instead. That means you shouldn't name your tasks things like `prune`, `run`, or `login` - since those are built-in subcommands. - -`turbo run <task>` will continue to work, and there are no plans to deprecate it. - -## Prune now supported on pnpm and yarn 2+ - -We're delighted to announce that [`turbo prune`](/repo/docs/reference/command-line-reference#turbo-prune---scopetarget) now supports in pnpm, yarn, and yarn 2+. - -You can use `turbo prune` to create a pruned subset of your monorepo with a dedicated lockfile--with the correct dependencies needed for a given target application and its dependencies. This is especially useful for using efficiently Turborepo within a Docker image. - -As part of the new handbook, we've also added a section on using `turbo prune` to [build docker images](/repo/docs/handbook/deploying-with-docker). - -Check out our previous [blog on prune](/blog/turbo-0-4-0#experimental-pruned-workspaces) to learn more. - -## Environment variables in `turbo.json` - -We've introduced two new keys to `turbo.json` - `env` and `globalEnv`. These allow environment variables to be configured _separately_ from tasks: - -```diff filename="turbo.json" -{ - "globalDependencies": [ -- "$DATABASE_URL" - ], -+ "globalEnv": [ -+ "DATABASE_URL" -+ ], - "pipeline": { - "build": { - "dependsOn": [ -- "$BUILD_ENV" - ], -+ "env": [ -+ "BUILD_ENV" -+ ] - } - } -} -``` - -`globalEnv` and `env` allow you to specify a list of environment variables _without_ `$` prefixes. This makes the configuration file significantly easier to read. Read more [in our updated docs](/repo/docs/core-concepts/caching#altering-caching-based-on-environment-variables). - -To help migrate from the previous syntax, we've prepared a codemod. You can run `npx @turbo/codemod migrate-env-var-dependencies`. - -This work builds on the [automatic env variable detection](/blog/turbo-1-4-0) we added in 1.4.0. - -## Changes to `package.json` hashing - -The `package.json` file in each workspace is now _always_ considered an input for tasks in that workspace. This means that if you change the _definition_ for a task in `package.json`, we want to invalidate any caches from the previous definition. - -This also counts for the `package.json` in the root. Changes to the root `package.json` will invalidate tasks in the root workspace. - -This helps make Turborepo's cache a bit smarter, and less likely to trip up when task definitions change. - -## Community - -Since releasing [Turborepo v1.4 in August](/blog/turbo-1-4-0), we've seen incredible adoption and community growth: - -- [9.5k+ GitHub Stars](https://github.com/vercel/turbo) -- [440k weekly NPM downloads](https://www.npmjs.com/package/turbo) -- 15 years of compute time saved through [Remote Caching on Vercel](https://vercel.com/docs/concepts/monorepos/remote-caching), saving over a 1 year per week, up 2x since July - -Turborepo is the result of the combined work of all of our contributors including our core team. - -This release was brought to you by the contributions of: @7flash, @afady, @alexander-young, @atilafassina, @bguedes-moz, @bobaaaaa, @brunojppb, @chris-olszewski, @DoctorJohn, @erj826, @futantan, @gsoltis, @HosseinAgha, @ivov, @jaredpalmer, @joelhooks, @knownasnaffy, @laurentlucian, @leerob, @MarceloAlves, @mattpocock, @mauricekleine, @mehulkar, @Misikir, @nareshbhatia, @nathanhammond, @pakaponk, @PhentomPT, @renovate, @ruisaraiva19, @samuelhorn, @shemayas, @shuding, @t-i-0414, @theurgi, @tknickman, @yanmao-cc, and more! - -Thank you for your continued support, feedback, and collaboration to make Turborepo your build tool of choice. diff --git a/docs/pages/blog/turbo-1-6-0.mdx b/docs/pages/blog/turbo-1-6-0.mdx deleted file mode 100644 index 295f312..0000000 --- a/docs/pages/blog/turbo-1-6-0.mdx +++ /dev/null @@ -1,223 +0,0 @@ ---- -title: Turborepo 1.6 -date: 2022/10/21 -description: Turborepo 1.6 lets you use Turborepo in non-monorepos, prune for npm, and improves cache performance. -tag: "web development" -ogImage: /images/blog/turbo-1-6-0/twitter-card.png ---- - -import { Tabs, Tab } from '../../components/Tabs' - -# Turborepo 1.6 - -import { Authors } from '../../components/Authors' -import Callout from '../../components/Callout' -import Date from "../../components/blog/Date"; - -<Date> - Friday, October 21st, 2022 -</Date> - -<Authors authors={[ - 'mattpocock', - 'gregsoltis', - 'nathanhammond', - 'tomknickman', - 'anthonyshew', - 'jaredpalmer', - 'mehulkar', - 'chrisolszewski' -]} /> - -Turborepo 1.6 changes the game for Turborepo - you can now use it in **any project**. - -- [**Turborepo in non-monorepos**](#any-codebase-can-use-turborepo): Seeing slow builds on your project? You can now use Turborepo to speed up builds in any codebase with a `package.json`. -- [**`turbo prune` now supports npm**](#prune-now-supported-on-npm): Pruning your monorepo is now supported in monorepos using `npm`, completing support for all major workspace managers. -- [**Faster caching**](#performance-improvements-in-the-cache): We've improved the way we handle local file writes, meaning a big speed-up of Turborepo's cache. - -Update today by running `npm install turbo@latest`. - -## Any codebase can use Turborepo - -Turborepo helps speed up tasks in your codebase. Until now, we'd built Turborepo specifically for monorepos - codebases which contain multiple applications and packages. - -Turborepo is fantastic in monorepos because they have so many tasks to handle. Each package and app needs to be built, linted, and tested. - -But we got to thinking: lots of codebases that _aren't_ monorepos run plenty of tasks. Most CI/CD processes do a lot of duplicated work that would benefit from a [cache](/repo/docs/core-concepts/caching). - -So we're excited to announce that **any codebase can now use Turborepo**. - -Try it out now by [starting from the example](https://github.com/vercel/turbo/tree/main/examples/non-monorepo), or by adding Turborepo to an existing project: - -### Add Turborepo to your project - -1. **Install `turbo`:** - -<Tabs items={['npm', 'yarn', 'pnpm']} storageKey="selected-pkg-manager"> - <Tab> - ```bash - npm install turbo --save-dev - ``` - </Tab> - <Tab> - ```bash - yarn add turbo --dev - ``` - </Tab> - <Tab> - ```bash - pnpm install turbo --save-dev - ``` - </Tab> -</Tabs> - -2. **Add a `turbo.json` file at the base of your new repository:** - -<Tabs items={['Next.js', 'Vite']} storageKey="selected-framework"> - <Tab> -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": [".next/**", "!.next/cache/**"] - }, - "lint": { - "outputs": [] - } - } -} -``` - </Tab> - <Tab> -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": ["dist/**"] - }, - "lint": { - "outputs": [] - } - } -} -``` - -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 enables `turbo` to schedule them separately. - - </Tab> -</Tabs> - -3. **Try running `build` and `lint` with `turbo`:** - -```bash -turbo build lint -``` - -Congratulations - **you just ran your first build with `turbo`**. You can try: - -- Running through the full [Quickstart](/repo/docs). -- Check out our updated [Core Concepts docs](/repo/docs/core-concepts/caching) to understand what makes Turborepo special. - -## When should I use Turborepo? - -Turborepo being available for non-monorepos opens up a lot of new use cases. But when is it at its best? - -### When scripts depend on each other - -You should use `turbo` to run your `package.json` scripts. If you've got multiple scripts which all rely on each other, you can express them as Turborepo tasks: - -```json filename="turbo.json" -{ - "pipeline": { - "build": { - "outputs": ["dist/**"] - }, - "lint": { - // 'build' should be run before 'lint' - "dependsOn": ["build"] - }, - "test": { - // 'build' should be run before 'test' - "dependsOn": ["build"] - } - } -} -``` - -Then, you can run: - -```sh -turbo run lint test -``` - -Because you've said that `build` should be run before `lint` and `test`, it'll _automatically run `build` for you_ when you run `lint` or `test`. - -Not only that, but it'll figure out the optimal schedule for you. Head to our core concepts doc on [optimizing for speed](/repo/docs/core-concepts/monorepos/running-tasks#most-tools-dont-optimize-for-speed). - -### When you want to run tasks in parallel - -Imagine you're running a [Next.js](https://nextjs.org/) app, and also running the [Tailwind CLI](https://tailwindcss.com/docs/installation). You might have two scripts - `dev` and `dev:css`: - -```json filename="package.json" -{ - "scripts": { - "dev": "next", - "dev:css": "tailwindcss -i ./src/input.css -o ./dist/output.css --watch" - } -} -``` - -Without anything being added to your `turbo.json`, you can run: - -```sh -turbo run dev dev:css -``` - -Just like tools like [`concurrently`](https://www.npmjs.com/package/concurrently), Turborepo will automatically run the two scripts in parallel. - -This is extremely useful for dev mode, but can also be used to speed up tasks on CI - imagine you have multiple scripts to run: - -```sh -turbo run lint unit:test e2e:test integration:test -``` - -Turborepo will figure out the fastest possible way to run all your tasks in parallel. - -## Prune now supported on npm - -Over the last several releases, we've been adding support for [`turbo prune`](/repo/docs/reference/command-line-reference#turbo-prune---scopetarget) on different workspace managers. This has been a challenge - `turbo prune` creates a subset of your monorepo, including pruning the dependencies in your lockfile. This means we've had to implement logic for each workspace manager separately. - -We're delighted to announce that `turbo prune` now works for `npm`, completing support for all major package managers. This means that if your monorepo uses `npm`, `yarn`, `yarn 2+` or `pnpm`, you'll be able to deploy to Docker with ease. - -Check out our previous [blog on `turbo prune`](/blog/turbo-0-4-0#experimental-pruned-workspaces) to learn more. - -## Performance improvements in the cache - -Before 1.6, Turborepo's local cache was a recursive copy of files on the system to another place on disk. This was _slow_. It meant that for every file that we needed to cache, we'd need to perform six system calls: open, read, and close on the source file; open, write, and close on the destination file. - -In 1.6, we've cut that nearly in half. Now, when creating a cache, we create a single `.tar` file (_one_ open), we write to it in 1mb chunks (_batched_ writes), and then close it (_one_ close). The halving of system calls _also_ happens on the way back out of cache. - -And we didn't stop there. Over the past month we've invested significantly in our build toolchain to enable CGO which unlocks usage of best-in-class libraries written in C. This enabled us to adopt [Zstandard](https://facebook.github.io/zstd/)'s `libzstd` for compression which gets us an algorithmic 3x performance improvement for compression. - -After all of these changes we're regularly seeing performance improvements of more than 2x on local cache creation and more than 3x on remote cache creation. This gets even better the bigger your repository is, or the slower your device is (looking at you, CI). This means we've been able to deliver performance wins precisely to those who needed it the most. diff --git a/docs/pages/blog/turbo-1-7-0.mdx b/docs/pages/blog/turbo-1-7-0.mdx deleted file mode 100644 index e0ffecf..0000000 --- a/docs/pages/blog/turbo-1-7-0.mdx +++ /dev/null @@ -1,150 +0,0 @@ ---- -title: Turborepo 1.7 -date: 2023/01/11 -description: Turborepo 1.7 focuses on improving developer experience by bringing more clarity to your tasks. -tag: "web development" -ogImage: /images/blog/turbo-1-7-0/twitter-card.png ---- - -import { Tabs, Tab } from '../../components/Tabs' - -# Turborepo 1.7 - -import { Authors } from '../../components/Authors' -import Badge from '../../components/Badge' -import Date from "../../components/blog/Date"; - -<Date> - Wednesday, January 11th, 2023 -</Date> - -<Authors authors={[ - 'gregsoltis', - 'nathanhammond', - 'tomknickman', - 'anthonyshew', - 'jaredpalmer', - 'mehulkar', - 'chrisolszewski', - 'nicholasyang' -]} /> - -Turborepo 1.7 focuses on improving developer experience by bringing more clarity to your tasks: - -- [**Improved support for long running tasks**](#schedule-your-long-running-tasks-with-confidence): Use `persistent: true` to mark non-terminating tasks so that `turbo` can alert you if you have dependencies on them. -- [**Better clarity for outputs**](#declare-your-outputs-for-improved-clarity): You'll now always need to declare your task outputs, improving transparency to what your tasks will cache. -- [**Globally installable**](#global-turbo): Install once, use everywhere. Turborepo can now be installed globally, and ran from any directory, not just from your repo root. -- [**“Error only” output mode**](#errors-only-output-mode-for-quieter-logs): Quiet your output logs to only show when a task fails. - -Update today by running `npm install turbo@latest`, or by [installing globally](#global-turbo) <Badge>NEW</Badge> and running the [`set-default-outputs`](/repo/docs/reference/codemods#set-default-outputs) codemod. - -## Schedule your long-running tasks with confidence - -To avoid misconfigurations that could result in tasks that never run, you can now tell Turborepo about tasks that won't exit on their own (like `dev` scripts) with a `persistent: true` [configuration option](/repo/docs/reference/configuration#persistent). When this config is set on a task, Turborepo will ensure no other task can depend on this task. This is useful for `dev` tasks or test runners with `--watch` flags. - -```diff -{ - "pipeline": { - "dev": { -+ "persistent": true - } - } -} -``` - -Previously, if `Task B` depended on a persistent `Task A`, `Task B` would never execute, because `Task A` never exited. By declaring `Task A` as `persistent`, Turborepo will prevent this error scenario from happening. - -Before this release, we had been recommending the use of `turbo run <task> --parallel` for persistent tasks. With `--parallel`, `turbo` would ignore your dependency graph and execute all your tasks at once. - -While `--parallel` did provide a helpful escape hatch, it meant that users had to tell Turborepo **_how_** to run their tasks rather than declaring **_what_** a task is. - -Rather than throwing away your entire topological dependency graph, it's much more precise for Turborepo to keep your dependency graph while guaranteeing that you don't depend on a process that won't exit with `persistent: true`. - -## Global `turbo` - -You can now run your Turborepo tasks from anywhere in your project once you've installed `turbo` globally. To do so, use: - -<Tabs items={['npm', 'yarn', 'pnpm']} storageKey="selected-pkg-manager"> - <Tab> - ```bash - npm install turbo --global - ``` - </Tab> - <Tab> - ```bash - yarn global add turbo - ``` - </Tab> - <Tab> - ```bash - pnpm install turbo --global - ``` - </Tab> -</Tabs> - -`turbo` will now work in any project. To find your local `turbo` version, `turbo` will walk through a few steps, always looking upward from your current directory: - -1. Find the nearest turbo.json. -2. If one is not found, find the first `package.json` with a `workspaces` property. -3. If one is not found, find the first `package.json`. - -Your globally installed version of `turbo` will only be used when a locally installed version of `turbo` does not exist or cannot be found. - - - -`turbo --version` and `turbo bin` will show you the version and binary location, respectively, of the copy of `turbo` that will execute your tasks. -Additionally, running with `-vv` or `--verbosity=2` will always show if your local, or global `turbo` is being used. - -```bash -turbo --version --verbosity=2 -2023-01-11T10:49:04.042-0500 [DEBUG] turborepo_lib::shim: No local turbo binary found at: /Users/knickman/Developer/vercel/my-awesome-monorepo/node_modules/.bin/turbo -2023-01-11T10:49:04.042-0500 [DEBUG] turborepo_lib::shim: Running command as global turbo -1.7.0 -``` - -## Declare your `outputs` for improved clarity - -Previously, if you did not specify an `outputs` key for a task, Turborepo would automatically attempt to cache all files in the `dist/` and `build/` directories. - -This worked well for `build` tasks of specific frameworks, but this implicit behavior did not scale well as it applied to _all_ tasks. We've found that, across the many developers, teams, projects, and codebases using Turborepo, the assumption to automatically cache `dist/` and `build/` directories was causing problems for users. - -In version 1.7, this behavior is removed and you will now need to explicitly tell turborepo what to cache. - -```diff -{ - "pipeline": { - "build": { -+ "outputs": ["dist/**", "build/**"] - } - } -} -``` - -If you were relying on the default cache output in Turborepo versions below 1.7, you can get the same behavior by running the [`@turbo/codemod set-default-outputs`](/repo/docs/reference/codemods#set-default-outputs) codemod: - -```bash -npx @turbo/codemod set-default-outputs -``` - -Also note that you will no longer need to specify `outputs: []` because not caching anything is now the default behavior. The codemod will also remove this configuration from your tasks. - -## “Errors only” output mode for quieter logs - -To bring visibility to errors, community member [@dobesv](https://github.com/dobesv) contributed [a solution to only show errors instead of all logs from a task run](https://github.com/vercel/turbo/pull/2588). While debugging a pipeline, `--output-logs=errors-only` can be used to keep your signal-to-noise ratio high so you can focus on ensuring successful runs for your pipelines. -This can be used as a [configuration option](/repo/docs/reference/configuration#outputmode) or as a [CLI flag](/repo/docs/reference/command-line-reference#--output-logs) - -```bash -turbo build --output-logs=errors-only -``` - -## Community - -Since releasing [Turborepo v1.6](/blog/turbo-1-6-0) and merging with [Turbopack](https://turbo.build/pack), we've seen incredible adoption and community growth: - -- [18.7k+ GitHub Stars](https://github.com/vercel/turbo) -- [750k weekly NPM downloads](https://www.npmjs.com/package/turbo) -- 30 years of compute time saved through [Remote Caching on Vercel](https://vercel.com/docs/concepts/monorepos/remote-caching) - -Turborepo is the result of the combined work of all of our contributors including our core team. - -Thank you for your continued support, feedback, and collaboration to make Turborepo your build tool of choice. diff --git a/docs/pages/blog/turbo-1-8-0.mdx b/docs/pages/blog/turbo-1-8-0.mdx deleted file mode 100644 index d533fc1..0000000 --- a/docs/pages/blog/turbo-1-8-0.mdx +++ /dev/null @@ -1,119 +0,0 @@ ---- -title: Turborepo 1.8 -date: 2023/02/22 -description: Turborepo 1.8 brings better flexibility and more control to your codebase by improving turbo's understanding of your workspaces. -tag: "web development" -ogImage: /images/blog/turbo-1-8-0/twitter-card.png ---- - -import { Tabs, Tab } from '../../components/Tabs' - -# Turborepo 1.8 - -import { Authors } from '../../components/Authors' -import Badge from '../../components/Badge' -import Date from "../../components/blog/Date"; - -<Date> - Wednesday, February 22th, 2023 -</Date> - -<Authors authors={[ - 'gregsoltis', - 'nathanhammond', - 'tomknickman', - 'anthonyshew', - 'jaredpalmer', - 'mehulkar', - 'chrisolszewski', - 'nicholasyang', - 'alexanderlyon' -]} /> - -Turborepo 1.8 brings better flexibility and more control to your codebase by improving `turbo`'s understanding of your workspaces. - -- [**Workspace Configurations**](#workspace-configurations): You can now add a `turbo.json` configuration file in a workspace to override the root configuration in your repository. -- [**Automatic Workspace Scoping**](#automatic-workspace-scoping): Global `turbo` now automatically infers your current workspace so that it only runs that workspace’s tasks. -- [**Easier Migrations**](#easier-migrations): Automatically migrate to new versions of `turbo` with `npx @turbo/codemod migrate`. - -Update today by running `npx @turbo/codemod migrate`. - -## Workspace Configurations - -In workspace directories, you can now add a `turbo.json` to: - -- add tasks specific to that workspace -- override configuration for tasks - -This will enable teams to scale ownership of the projects in their monorepos by moving away from global configuration to fine-grain contol over tasks in workspaces. - -For example, imagine your monorepo has a Next.js app and a SvelteKit app, and you want to use Turborepo to cache outputs of the `build` task. The Next.js `build` script creates a `.next` directory, whereas SvelteKit creates a `.svelte-kit` directory. Instead of adding both build directories in your root `outputs`, you can define the `outputs` key in the workspace instead: - -```jsonc filename="turbo.json" -{ - "pipeline": { - "build": { - "dependsOn": ["^codegen"], - // no need to define outputs here! - } - } -} -``` - -```jsonc filename="apps/my-nextjs-app/turbo.json" -{ - "extends": ["//"], - "pipeline": { - "build": { - // dependsOn is inherited from root - "outputs": [".next/**", "!.next/cache/**"] - } - } -} -``` - -```jsonc filename="apps/my-sveltekit-app/turbo.json" -{ - "extends": ["//"], - "pipeline": { - "build": { - // dependsOn is inherited from root - "outputs": [".svelte-kit/**"] - } - } -} -``` - -The `extends` key in the Workspace Configurations enables workspace owners to use the best of the root `turbo.json` and customize the parts that makes their app different (The `"//"` sigil will look familiar if you’re used to [defining tasks to run from your root](/repo/docs/core-concepts/monorepos/running-tasks#running-tasks-from-the-root)). - -Keys that **are** declared will replace the key from the root if those keys exist, overriding what is defined in your root configuration. Keys that **are not** declared are inherited from the root config. - -In the example above, `outputs` is customized for both apps, while `dependsOn` is configured by the root `turbo.json` and remains `"^codegen"`. - -[Learn more in the docs](/repo/docs/core-concepts/monorepos/configuring-workspaces). - -## Automatic Workspace Scoping - -In [Turborepo v1.7](/blog/turbo-1-7-0), `turbo` became globally installable, giving you the power to run your tasks from anywhere in your codebase. However, `turbo` would still run tasks from the root, running tasks in other workspaces that you may not have intended to run. - -With 1.8, `turbo` will automatically detect the workspace you are in and generate [the `--filter` syntax](/repo/docs/reference/command-line-reference#--filter) to scope your task to that workspace. - -As an example, if your current directory is `apps/admin` and you use the `turbo build` command, `turbo` will run `turbo build --filter=admin` under the hood, focusing on the workspace that you are working on. - -## Easier Migrations - -Manually running individual codemods in the correct order is no longer required when upgrading Turborepo versions. `@turbo/codemod` now provides a simple `migrate` command which both upgrades your repo to the specified version (`latest` by default) of `turbo`, _and_ runs any codemods required. - -Try it out now with `npx @turbo/codemod migrate`. - -## Community - -Since releasing [Turborepo v1.7](/blog/turbo-1-7-0) we've seen incredible adoption and community growth: - -- [19.6k+ GitHub Stars](https://github.com/vercel/turbo) -- [987k weekly NPM downloads](https://www.npmjs.com/package/turbo) -- 42 years of compute time saved through [Remote Caching on Vercel](https://vercel.com/docs/concepts/monorepos/remote-caching) - -Turborepo is the result of the combined work of all of its contributors, including our core team. - -Thank you for your continued support, feedback, and collaboration to make Turborepo your build tool of choice. diff --git a/docs/pages/blog/turbo-1-9-0.mdx b/docs/pages/blog/turbo-1-9-0.mdx deleted file mode 100644 index b370cd8..0000000 --- a/docs/pages/blog/turbo-1-9-0.mdx +++ /dev/null @@ -1,121 +0,0 @@ ---- -title: Turborepo 1.9 -date: 2023/04/11 -description: Turborepo 1.9 focuses on improving observability for your task runs to better understand your caching behavior. -tag: "web development" -ogImage: /images/blog/turbo-1-9-0/twitter-card.png ---- - -# Turborepo 1.9 - -import { Authors } from '../../components/Authors' -import Badge from '../../components/Badge' -import Date from "../../components/blog/Date"; - -<Date> - Monday, April 11th, 2023 -</Date> - -<Authors authors={[ - 'gregsoltis', - 'nathanhammond', - 'tomknickman', - 'anthonyshew', - 'jaredpalmer', - 'mehulkar', - 'chrisolszewski', - 'nicholasyang', - 'alexanderlyon' -]} /> - -Turborepo 1.9 focuses on improving observability for your task runs to better understand your caching behavior: - -- [**Run Summaries**](#view-and-compare-task-runs): Use the `--summarize` flag to generate a summary of your task to compare against previous runs. -- [**Easier Starters**](#bring-your-own-starter): Use the `--example` flag with `npx create-turbo` to start from official Turborepo examples or custom repositories. -- [**Strict Environments** <Badge>Experimental</Badge>](#strict-environments-experimental): Try enabling strict mode to restrict the environment variables your tasks have access to. - -Update today by running `npx @turbo/codemod migrate`. - -## View and compare task runs - -You can now produce a JSON summary of your task run using the `--summarize` flag: - -```bash -turbo build --summarize -``` - -When this flag is enabled, Turborepo will generate a summary in `.turbo/runs/` that contains all the information necessary to understand how `turbo` interpreted your your task's configuration and code. - -```bash -Tasks: 3 successful, 3 total -Cached: 0 cached, 3 total -Time: 1.707s -Summary: /Users/acme/projects/acme/.turbo/runs/2Nn3X6nWDhP9ag8BnmivWRxHpHC.json -``` - -You can then compare summaries using your favorite JSON diffing tool to understand why you got a cache hit or a cache miss. - -Learn more in the [docs](/repo/docs/reference/command-line-reference#--summarize) to learn more. - -## Bring your own starter - -`create-turbo` now supports starting a new project from any of the official [Turborepo examples](https://github.com/vercel/turbo/tree/main/examples). Get started with an example using a single command: - -```bash -npx create-turbo@latest -e kitchen-sink -``` - -In your terminal UI, choose your preferred package manager and `create-turbo` will automatically convert the chosen example to your package manager of choice. - -Additionally, you can use `create-turbo` with custom repository sources, allowing you to re-use your own custom starter or another starter from around the community: - -```bash -npx create-turbo -e https://github.com/your-org/turbo-starter -``` - -## Strict Environments <Badge>Experimental</Badge> - -You can now use the `--experimental-env-mode=strict` flag to restrict the environment variables your tasks have access to. Your tasks will only be aware of the variables you explicitly state, creating a safer caching environment. - -In `strict` mode, Turborepo will pass environment variables declared in: - -- `globalEnv` and `experimentalGlobalPassThroughEnv` to all tasks -- `env` and `experimentalPassThroughEnv` for each task - -```json -{ - // Available to all tasks - "experimentalGlobalPassThroughEnv": ["GLOBAL_VAR_1"], - - // Available to all tasks and invalidates caches - "globalEnv": ["GLOBAL_VAR_2"], - - "pipeline": { - "build": { - // Only available to `build` tasks - "experimentalPassThroughEnv": ["VAR_1"], - - // Available to `build` task and invalidates caches - "env": ["VAR_2"] - } - } -} -``` - -In `strict` mode, this configuration will only expose four environment variables to your `build` tasks, helping you catch missing variables earlier in the development process. - -`--experimental-env-mode` also supports `loose` and `infer`. - -Learn more in the [docs](/repo/docs/reference/command-line-reference#--experimental-env-mode). - -## Community - -Since releasing [Turborepo v1.8](/blog/turbo-1-8-0) we've seen incredible adoption and community growth: - -- [20.5k+ GitHub Stars](https://github.com/vercel/turbo) -- [1.1M weekly NPM downloads](https://www.npmjs.com/package/turbo) -- 64 years of compute time saved through [Remote Caching on Vercel](https://vercel.com/docs/concepts/monorepos/remote-caching) - -Turborepo is the result of the combined work of all of its contributors, including our core team. - -Thank you for your continued support, feedback, and collaboration to make Turborepo your build tool of choice. diff --git a/docs/pages/blog/turbopack-benchmarks.mdx b/docs/pages/blog/turbopack-benchmarks.mdx deleted file mode 100644 index e6a0818..0000000 --- a/docs/pages/blog/turbopack-benchmarks.mdx +++ /dev/null @@ -1,275 +0,0 @@ ---- -title: "Turbopack Performance Benchmarks" -date: 2022/10/31 -description: "Benchmarking Turbopack performance against Vite and webpack." -tag: "web development" -ogImage: "/images/blog/turbopack-benchmarks/twitter-card.png" ---- - -import { DEFAULT_BARS, HMR_BARS } from '../../components/pages/pack-home/PackBenchmarks' -import { DocsBenchmarksGraph } from '../../components/pages/pack-home/DocsBenchmarksGraph'; -import { Tabs, Tab } from '../../components/Tabs' -import { ThemedImageFigure } from '../../components/image/ThemedImageFigure' -import { Authors } from '../../components/Authors' -import Callout from '../../components/Callout' -import Date from "../../components/blog/Date"; - -# Turbopack Performance Benchmarks - -<Date update={<>Thursday, December 22nd, 2022</>}> - Monday, October 31st, 2022 -</Date> - -<Authors authors={[ 'tobiaskoppers', 'alexkirsz' ]} /> - -<p className="text-gray-500 mt-6 uppercase text-sm tracking-wider">Summary</p> - -- We are thankful for the work of the entire OSS ecosystem and the incredible interest and reception from the [Turbopack release](https://vercel.com/blog/turbopack). We look forward to continuing our collaboration with and integration into the broader Web ecosystem of tooling and frameworks. -- In this article, you will find our methodology and documentation supporting the benchmarks that show **Turbopack is [much faster](#bench) than existing non-incremental approaches.** -- **Turbopack** and [**Next.js 13.0.1**](https://github.com/vercel/next.js/releases/tag/v13.0.1) are out addressing a regression that snuck in prior to public release and after the initial benchmarks were taken. We also fixed an incorrect rounding bug on our website (`0.01s` → `15ms`). We appreciate [Evan You](https://twitter.com/youyuxi)'s work that helped us identify and [correct this](https://github.com/vercel/turbo/pull/2516). -- We are excited to continue to evolve the incremental build architecture of Turbopack. We believe that there are still significant performance wins on the table. - -<hr className="mt-8 w-full border-gray-400 authors border-opacity-20"/> - -At [Next.js Conf](https://nextjs.org), [we announced](https://www.youtube.com/watch?v=NiknNI_0J48) our latest open-source project: Turbopack, an incremental bundler and build system optimized for JavaScript and TypeScript, written in Rust. - -The project began as an exploration to improve webpack’s performance and create ways for it to more easily integrate with tooling moving forward. In doing so, the team realized that a greater effort was necessary. While we saw opportunities for better performance, the premise of a new architecture that could scale to the largest projects in the world was inspiring. - -In this post, we will explore why Turbopack is so fast, how its incremental engine works, and benchmark it against existing approaches. - -## Why is Turbopack _blazing_ fast? - -Turbopack’s speed comes from its incremental computation engine. Similar to trends we have seen in frontend state libraries, computational work is split into reactive functions that enable Turbopack to apply updates to an existing compilation without going through a full graph recomputation and bundling lifecycle. - -This does not work like traditional caching where you look up a result from a cache before an operation and then decide whether or not to use it. That would be too slow. - -Instead, Turbopack skips work altogether for cached results and only recomputes affected parts of its internal dependency graph of functions. This makes updates independent of the size of the whole compilation, and eliminates the usual overhead of traditional caching. - -## Benchmarking Turbopack, webpack, and Vite - -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 are 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. - -<ThemedImageFigure - borderRadius={false} - dark={{ - source: '/images/blog/turbopack-benchmarks/triangle-dark.png', - height: 600, - width: 1200 - }} - light={{ - source: '/images/blog/turbopack-benchmarks/triangle-light.png', - height: 600, - width: 1200 - }} - captionSpacing={-12} - caption="This image is a screenshot of the test application we run our benchmarks on. It depicts a Sierpiński triangle where each single triangle is its own component, separated in its own file. In this example, there are 3,000 triangles being rendered to the screen." -/> - -### 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. - -Based on feedback and collaboration with the Vite team, we used the [SWC plugin](https://github.com/vitejs/vite-plugin-react-swc) with Vite in replacement for the [default Babel plugin](https://github.com/vitejs/vite-plugin-react) for improved performance in this benchmark. - -<DocsBenchmarksGraph category="cold" bars={DEFAULT_BARS} /> - -<ThemedImageFigure - borderRadius={true} - dark={{ - source: '/images/blog/turbopack-benchmarks/bench_startup_dark.svg', - height: 720, - width: 1960 - }} - light={{ - source: '/images/blog/turbopack-benchmarks/bench_startup_light.svg', - height: 720, - width: 1960 - }} - captionSpacing={24} - caption="Startup time by module count. Benchmark data generated from 16” MacBook Pro 2021, M1 Max, 32GB RAM, macOS 13.0.1 (22A400)." -/> - -#### 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. - -<DocsBenchmarksGraph category="file_change" bars={HMR_BARS} /> - -<ThemedImageFigure - borderRadius={true} - dark={{ - source: '/images/blog/turbopack-benchmarks/bench_hmr_to_commit_dark.svg', - height: 720, - width: 1960 - }} - light={{ - source: '/images/blog/turbopack-benchmarks/bench_hmr_to_commit_light.svg', - height: 720, - width: 1960 - }} - captionSpacing={24} - caption="Turbopack, Next.js (webpack), and Vite HMR by module count. Benchmark data generated from 16” MacBook Pro 2021, M1 Max, 32GB RAM, macOS 13.0.1 (22A400)." -/> - -<a id="bench"/> - -<ThemedImageFigure - borderRadius={true} - dark={{ - source: '/images/blog/turbopack-benchmarks/bench_hmr_to_commit_turbopack_vite_dark.svg', - height: 720, - width: 1960 - }} - light={{ - source: '/images/blog/turbopack-benchmarks/bench_hmr_to_commit_turbopack_vite_light.svg', - height: 720, - width: 1960 - }} - captionSpacing={24} - caption="Turbopack and Vite HMR by module count. Benchmark data generated from 16” MacBook Pro 2021, M1 Max, 32GB RAM, macOS 13.0.1 (22A400)." -/> - -The takeaway: Turbopack performance is a function of **the size of an update**, not the size of an application. - -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 -``` - -As a reminder, Vite is using the official [SWC plugin](https://github.com/vitejs/vite-plugin-react-swc) for these benchmarks, which is not the default configuration. - -Visit the [Turbopack benchmark documentation](/pack/docs/benchmarks) to run the benchmarks yourself. If you have questions about the benchmark, please open an [issue on GitHub](https://github.com/vercel/turbo/issues). - -## The future of the open-source Web - -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. - -Our goal is to create a system of open source tooling that helps to build the future of the Web—powered by Turbopack. We are creating a reusable piece of architecture that will make both development and warm production builds faster for everyone. - -For Turbopack’s alpha, we are including it in Next.js 13. But, in time, [we hope that Turbopack will power other frameworks and builders](https://twitter.com/youyuxi/status/1585040276447690752?s=20&t=YV0ASkHl5twCWQvJF5jpwg) as a seamless, low-level, incremental engine to build great developer experiences with. - -We look forward to being a part of the community bringing developers better tooling so that they can continue to deliver better experiences to end users. If you would like to learn more about Turbopack benchmarks, visit [turbo.build](https://turbo.build/). To try out Turbopack in Next.js 13, visit [nextjs.org](https://nextjs.org/docs/advanced-features/turbopack). - ---- - -## Update (2022/12/22) - -When we first released Turbopack, we made some claims about its performance relative to previous Next.js versions (11 and 12), and relative to Vite. These numbers were computed with our benchmark suite, which was publicly available on the [turbo repository](https://github.com/vercel/turbo), but we hadn’t written up much about them, nor had we provided clear instructions on how to run them. - -After collaborating with Vite’s core contributor [Evan You](https://github.com/yyx990803), we released this blog post explaining our methodology and we updated our website to provide instructions on how to run the benchmarks. - -Based on the outcome of our collaboration with Vite, here are some clarifications we have made to the benchmarks above on our testing methodology: - -### Raw HMR vs. React Refresh - -In the numbers we initially published, we were measuring the time between a file change and the update being run in the browser, but not the time it takes for React Refresh to re-render the update (`hmr_to_eval`). - -We had another benchmark which included React Refresh (`hmr_to_commit`) which we elected not to use because we thought it mostly accounted for React overhead—an additional 30ms. However, this assumption turned out to be wrong, and the issue was [within Next.js’ update handling code](https://github.com/vercel/next.js/pull/42350). - -On the other hand, Vite’s `hmr_to_eval` and `hmr_to_commit` numbers were much closer together (no 30ms difference), and [this brought up suspicion that our benchmark methodology was flawed and that we weren’t measuring the right thing](https://github.com/yyx990803/vite-vs-next-turbo-hmr/discussions/8). - -This blog post has been updated to include React Refresh numbers. - -### Root vs. Leaf - -[Evan You’s benchmark application](https://github.com/yyx990803/vite-vs-next-turbo-hmr) is composed of a single, very large file with a thousand imports, and a thousand very small files. The shape of our benchmark is different – it represents a tree of files, with each file importing 0 or 3 other files, trying to mimic an average application. Evan helped us find a regression when editing large, root files in his benchmark. The cause for this was [quickly identified and fixed by Tobias](https://github.com/vercel/turbo/commit/a11422fdf6b1b3cde9072d90aab6d9eebfacb591) and was released in Next 13.0.1. - -We have adapted our HMR benchmarks to samples modules uniformly at all depths, and we have updated this blog post and our documentation to include more details about this process. - -### SWC vs. Babel - -When we initially released the benchmarks, we were using the official Vite React plugin which uses Babel under the hood. Turbopack itself uses SWC, [which is much faster than Babel](https://swc.rs/blog/perf-swc-vs-babel). Evan You suggested that for a more accurate comparison, we should change Vite’s benchmark to use the SWC plugin instead of the default Babel experience. - -While SWC does improve Vite’s startup performance significantly, it only shows a small difference in HMR updates (\<10%). It should be noted that the React Refresh implementations between the plugins are different, hence this might not be measuring SWC’s effect but some other implementation detail. - -We have updated our benchmarks to run Vite with the official SWC plugin. - -### File Watcher Differences - -Every OS provide its own APIs for watching files. On macOS, Turbopack uses [FSEvents](https://developer.apple.com/documentation/coreservices/file_system_events), which have shown to have [~12ms latency](https://twitter.com/devongovett/status/1586599130494746625) for reporting updates. We have considered using [kqueue](https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2) instead, which has much lower latency. However, since it is not a drop-in replacement, and brings its lot of drawbacks, this is still in the exploratory stage and not a priority. - -Expect to see different numbers on Linux, where [inotify](https://man7.org/linux/man-pages/man7/inotify.7.html) is the standard monitoring mechanism. - -### Improving our Methodology - -Our benchmarks originally only sampled 1 HMR update from 10 different instances of each bundler running in isolation, for a total of 10 sampled updates, and reported the mean time. Before sampling each update, bundler instances were warmed up by running 5 updates. - -Sampling so few updates meant high variance from one measurement to the next, and this was particularly significant in Vite’s HMR benchmark, where single updates could take anywhere between 80 and 300ms. - -We have since refactored our benchmarking architecture to measure a variable number of updates per bundler instance, which results in anywhere between 400 and 4000 sampled updates per bundler. We have also increased the number of warmup updates to 10. - -Finally, instead of measuring the mean of all samples, we are measuring the slope of the linear regression line. - -This change has improved the soundness of our results. It also brings Vite’s numbers down to an **almost constant 100ms at any application size**, while we were previously measuring 200+ms updates for larger applications of over 10,000 modules. - -### Conclusion - -We are now measuring Turbopack to be consistently 5x faster than Vite for HMR, over all application sizes, after collaborating with the Vite team on the benchmarks. We have updated all of our benchmarks to reflect our new methodology. diff --git a/docs/pages/blog/you-might-not-need-typescript-project-references.mdx b/docs/pages/blog/you-might-not-need-typescript-project-references.mdx deleted file mode 100644 index 5874d98..0000000 --- a/docs/pages/blog/you-might-not-need-typescript-project-references.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: You might not need TypeScript project references -date: 2021/04/23 -description: As it turns out, you might not even references or even an interim TypeScript build step with a pattern I am about to show you, which I dub "internal packages." -tag: web development -ogImage: /images/blog/you-might-not-need-typescript-project-references/twitter-card.png ---- - -# You might not need TypeScript project references - -import { Authors } from "../../components/Authors"; -import Callout from "../../components/Callout"; - -<Authors authors={['jaredpalmer']} /> - -If you've worked in a larger TypeScript codebase or monorepo, you are likely familiar with [project references](https://www.typescriptlang.org/docs/handbook/project-references.html). They are indeed fairly powerful. - -When you reference a project in your `tsconfig.json`, new things happen: - -- Importing modules from a referenced project will instead load its output declaration file (`.d.ts`) -- If the referenced project produces an `outFile`, the output file `.d.ts` file’s declarations will be visible in this project -- Running build mode (`tsc -b`) will automatically build the referenced project if it hasn't been built but is needed -- By separating into multiple projects, you can greatly improve the speed of typechecking and compiling, reduce memory usage when using an editor, and improve enforcement of the logical groupings of your program. - -Sounds awesome! Right?! Well...maybe. Once you add references to your project you now need to continuously update them whenever you add or remove packages. That kinda blows. - -Well...what if you didn't need to? - -## "Internal" TypeScript Packages - -As it turns out, you might not even need references or even an interim TypeScript build step with a pattern I am about to show you, which I dub "internal packages." - -**An "internal package" is a TypeScript package without a `tsconfig.json` with _both_ its `types` and `main` fields in its `package.json` pointing to the package's untranspiled entry point (e.g. `./src/index.tsx`).** - -```json -{ - "name": "@sample/my-internal-package" - "main": "./src/index.ts" - "types": "./src/index.ts", // yes, this works! - "dependencies": { - ... - }, - "devDependencies": { - ... - } -} -``` - -As it turns out, the TypeScript Language Server (in VSCode) and Type Checker can treat both a raw `.ts` or `.tsx` file as its own valid type declaration. This last sentence is obvious once you read it twice. What isn't so obvious, though, is that you can point the `types` field directly to raw source code. - -Once you do this, this package can then be used _without_ project references or a TypeScript build step (either via `tsc` or `esbuild` etc) as long as you adhere to 2 rules: - -- **The consuming application of an internal package must transpile and typecheck it.** -- **You should never publish an internal package to npm.** - -As far as I can tell, this internal package pattern works with all yarn/npm/pnpm workspace implementations regardless of whether you are using Turborepo or some other tool. I have personally tested this pattern with several different meta frameworks (see below), but I'm sure that it works with others as well. - -### Next.js - -Next.js 13 can automatically transpile and bundle dependencies from local packages (like monorepos) or from external dependencies (`node_modules`). - -```js -/** @type {import('next').NextConfig} */ -const nextConfig = { - transpilePackages: ['@acme/ui', 'lodash-es'], -}; - -module.exports = nextConfig; -``` - -<Callout type="info">As of Next.js 13.1, you no longer need the `next-transpile-modules` package. For more information, visit the Next.js [Built-in module transpilation](https://nextjs.org/blog/next-13-1#built-in-module-transpilation-stable) blog post.</Callout> - -### Vite - -Internal packages just work. No extra config is needed. - -### React Native - -If you use [Expo](https://expo.dev/) and use the [`expo-yarn-workspaces`](https://github.com/expo/expo/tree/master/packages/expo-yarn-workspaces) or [`@turborepo/adapter-expo`](https://www.npmjs.com/package/@turborepo/adapter-expo) package, you can use internal packages as long as you are targeting iOS or Android. When you run Expo for these platforms, all of `node_modules` are automatically transpiled with [Metro](https://facebook.github.io/metro/). However, if you are targeting Expo for web, internal packages will not work because `node_modules` are oddly not transpiled for web. - -_I reached out to the Expo team about this inconsistency. They are aware of it. It's a legacy wart I'm told._ - -## The beauty of this pattern - -This pattern rocks because it saves you from extra needless or duplicative build steps. It also gives you all the editor benefits of project references, but without any configuration. - -## Caveats - -When you use an internal package, it's kind of like telling the consuming application that you have another source directory—which has pros and cons. As your consuming application(s) grow, adding more internal packages is identical to adding more source code to that consuming application. Thus, when you add more source code, there is more code to transpile/bundle/typecheck...so this can result in slower builds of the consuming application (as there is just more work to do) but potentially faster (and less complicated) overall build time. When/if overall build time begins to suffer, you might decide to convert your larger internal packages back into "regular" packages with `.d.ts` files and with normal TypeScript build steps. - -As previously mentioned, this pattern actually has very little to do with Turborepo. It's just super duper awesome and I think you should be aware of it. As we are actively working on preset package build rules (i.e. "builders") for Turborepo, we'll using the internal package pattern to skip build steps. - -## Speaking of long build times... - -Shameless plug here. If you are reading this post, and you're struggling with slow build and test times, I'd love to show you how Turborepo can help. I guarantee that Turborepo will cut your monorepo's build time by 50% or more. [You can request a live demo right here.](https://vercel.com/contact/sales?utm_source=turbo.build&utm_medium=referral&utm_campaign=blog-project-references) diff --git a/docs/public/background_or_logo.png b/docs/public/background_or_logo.png Binary files differnew file mode 100644 index 0000000..d1f933e --- /dev/null +++ b/docs/public/background_or_logo.png diff --git a/docs/public/images/people/HsiangNianian.jpg b/docs/public/images/people/HsiangNianian.jpg Binary files differnew file mode 100644 index 0000000..78c5593 --- /dev/null +++ b/docs/public/images/people/HsiangNianian.jpg diff --git a/docs/public/images/people/alexanderlyon.jpg b/docs/public/images/people/alexanderlyon.jpg Binary files differdeleted file mode 100644 index 040db94..0000000 --- a/docs/public/images/people/alexanderlyon.jpg +++ /dev/null diff --git a/docs/public/images/people/alexkirsz.jpg b/docs/public/images/people/alexkirsz.jpg Binary files differdeleted file mode 100644 index 03a1852..0000000 --- a/docs/public/images/people/alexkirsz.jpg +++ /dev/null diff --git a/docs/public/images/people/anthonyshew.png b/docs/public/images/people/anthonyshew.png Binary files differdeleted file mode 100644 index 42193ef..0000000 --- a/docs/public/images/people/anthonyshew.png +++ /dev/null diff --git a/docs/public/images/people/becca__z.jpeg b/docs/public/images/people/becca__z.jpeg Binary files differdeleted file mode 100644 index 8adc343..0000000 --- a/docs/public/images/people/becca__z.jpeg +++ /dev/null diff --git a/docs/public/images/people/chrisolszewski.jpg b/docs/public/images/people/chrisolszewski.jpg Binary files differdeleted file mode 100644 index aff0834..0000000 --- a/docs/public/images/people/chrisolszewski.jpg +++ /dev/null diff --git a/docs/public/images/people/empty.jpeg b/docs/public/images/people/empty.jpeg Binary files differdeleted file mode 100644 index 86b83e5..0000000 --- a/docs/public/images/people/empty.jpeg +++ /dev/null diff --git a/docs/public/images/people/gaspargarcia.jpeg b/docs/public/images/people/gaspargarcia.jpeg Binary files differdeleted file mode 100644 index a33f4a8..0000000 --- a/docs/public/images/people/gaspargarcia.jpeg +++ /dev/null diff --git a/docs/public/images/people/gregsoltis.jpeg b/docs/public/images/people/gregsoltis.jpeg Binary files differdeleted file mode 100644 index ed52e8a..0000000 --- a/docs/public/images/people/gregsoltis.jpeg +++ /dev/null diff --git a/docs/public/images/people/jaredpalmer.jpeg b/docs/public/images/people/jaredpalmer.jpeg Binary files differdeleted file mode 100644 index e715baf..0000000 --- a/docs/public/images/people/jaredpalmer.jpeg +++ /dev/null diff --git a/docs/public/images/people/mattpocock.jpeg b/docs/public/images/people/mattpocock.jpeg Binary files differdeleted file mode 100644 index 7ad8142..0000000 --- a/docs/public/images/people/mattpocock.jpeg +++ /dev/null diff --git a/docs/public/images/people/mehulkar.jpeg b/docs/public/images/people/mehulkar.jpeg Binary files differdeleted file mode 100644 index 5cf730d..0000000 --- a/docs/public/images/people/mehulkar.jpeg +++ /dev/null diff --git a/docs/public/images/people/nathanhammond.png b/docs/public/images/people/nathanhammond.png Binary files differdeleted file mode 100644 index 929d5e3..0000000 --- a/docs/public/images/people/nathanhammond.png +++ /dev/null diff --git a/docs/public/images/people/nicholasyang.png b/docs/public/images/people/nicholasyang.png Binary files differdeleted file mode 100644 index e0ed3d8..0000000 --- a/docs/public/images/people/nicholasyang.png +++ /dev/null diff --git a/docs/public/images/people/tobiaskoppers-avatar.jpg b/docs/public/images/people/tobiaskoppers-avatar.jpg Binary files differdeleted file mode 100644 index ce881ed..0000000 --- a/docs/public/images/people/tobiaskoppers-avatar.jpg +++ /dev/null diff --git a/docs/public/images/people/tobiaskoppers.jpg b/docs/public/images/people/tobiaskoppers.jpg Binary files differdeleted file mode 100644 index 5cbe8b1..0000000 --- a/docs/public/images/people/tobiaskoppers.jpg +++ /dev/null diff --git a/docs/public/images/people/tomknickman.jpeg b/docs/public/images/people/tomknickman.jpeg Binary files differdeleted file mode 100644 index 938efa4..0000000 --- a/docs/public/images/people/tomknickman.jpeg +++ /dev/null |
