Skip to content

Commit

Permalink
Document global turbo package inference behavior (vercel#3535)
Browse files Browse the repository at this point in the history
 - adds package inference to the docs on filtering workspaces
 - adds package inference to the `dev` topic in the handbook, which AFAICT is where we introduce the concept of filtering.
  • Loading branch information
Greg Soltis authored Feb 1, 2023

Verified

This commit was signed with the committer’s verified signature.
thesamesam Sam James
1 parent 89d0100 commit 4b72b43
Showing 2 changed files with 24 additions and 6 deletions.
10 changes: 9 additions & 1 deletion docs/pages/repo/docs/core-concepts/monorepos/filtering.mdx
Original file line number Diff line number Diff line change
@@ -8,7 +8,7 @@ import HeartIcon from "@heroicons/react/solid/HeartIcon";

# Filtering Workspaces

A monorepo can contain hundreds, or thousands, of workspaces. By default, running `turbo run test` will execute the `test` task in **all available workspaces**.
A monorepo can contain hundreds, or thousands, of workspaces. By default, running `turbo run test` from the root of the repository will execute the `test` task in **all available workspaces**.

![Without using a filter, test will be run across all packages](/images/docs/no-filter.png)

@@ -191,6 +191,14 @@ turbo run build --filter=!@foo/bar
turbo run build --filter=./apps/* --filter=!admin
```

### Via global `turbo`

If you are using a globally installed version of `turbo`, running from within a workspace automatically
filters to that workspace's directory. That means running `turbo run test --filter={./packages/shared}` from the root of the repository is equivalent to
running `cd packages/shared && turbo run test`.

Running with an explicitly named workspace will always work from anywhere in the repository: `turbo run test --filter=shared`.

<Callout
type="idea"
icon={<HeartIcon className="mt-1 h-5 w-5 text-gray-400" aria-hidden="true" />}
20 changes: 15 additions & 5 deletions docs/pages/repo/docs/handbook/dev.mdx
Original file line number Diff line number Diff line change
@@ -95,14 +95,23 @@ This means that users of your `dev` task _don't need to worry about codegen or m

## Running `dev` only in certain workspaces

To run a `dev` task in only certain workspaces, you should use the [`--filter` syntax](/repo/docs/core-concepts/monorepos/filtering). For example:
Let's assume you want to run the `dev` task in the `docs` workspace, located at `<root>/apps/docs`.
`turbo` can infer the workspace from your directory, so if you run:

```bash
cd <root>/apps/docs
turbo run dev
```

`turbo` will automatically pick up that you're in the `docs` workspace and run the `dev` task.

To run the same task from any other location in the repository, use [`--filter` syntax](/repo/docs/core-concepts/monorepos/filtering).
For example:

```bash
turbo run dev --filter docs
```

Will only run `dev` in the workspace named `docs`.

## Using environment variables

While developing, you'll often need to use environment variables. These let you customize the behavior of your program - for instance, pointing to a different `DATABASE_URL` in development and production.
@@ -111,8 +120,9 @@ We recommend using a library called [`dotenv-cli`](https://www.npmjs.com/package

<Callout type="info">
We want every dev to have a great experience using Turbo. The approach documented below does **not** live up to those standards.

We're working on a first-class solution to this problem - but while you wait, here's the next-best solution.

We're working on a first-class solution to this problem - but while you wait, here's the next-best solution.

</Callout>

### Tutorial

0 comments on commit 4b72b43

Please sign in to comment.