diff --git a/docs/pages/docs/core-concepts/caching.mdx b/docs/pages/docs/core-concepts/caching.mdx
index 8164449c2789e..8bc97b36777f4 100644
--- a/docs/pages/docs/core-concepts/caching.mdx
+++ b/docs/pages/docs/core-concepts/caching.mdx
@@ -189,7 +189,7 @@ Otherwise, you could ship a cached build with the wrong environment variables!
You can control `turbo`'s caching behavior based on
the values of environment variables:
-- Including environment variables in a `dependsOn` in your `pipeline` definition prefixed by a `$` will impact the cache fingerprint on a per-task or per-workspace-task basis.
+- Including environment variables in the `env` key in your `pipeline` definition will impact the cache fingerprint on a per-task or per-workspace-task basis.
- The value of any environment variable that includes `THASH` in its name will impact the cache fingerprint of _all_ tasks.
```jsonc
@@ -197,22 +197,20 @@ the values of environment variables:
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"build": {
- "dependsOn": [
- "^build",
- // env vars will impact hashes of all "build" tasks
- "$SOME_ENV_VAR",
- ],
+ "dependsOn": ["^build"],
+ // env vars will impact hashes of all "build" tasks
+ "env": ["SOME_ENV_VAR"],
"outputs": ["dist/**"]
},
// override settings for the "build" task for the "web" app
"web#build": {
- "dependsOn": [
- "^build",
+ "dependsOn": ["^build"],
+ "env": [
// env vars that will impact the hash of "build" task for only "web" app
- "$STRIPE_SECRET_KEY",
- "$NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
- "$NEXT_PUBLIC_ANALYTICS_ID",
+ "STRIPE_SECRET_KEY",
+ "NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
+ "NEXT_PUBLIC_ANALYTICS_ID"
],
"outputs": [".next/**"],
},
@@ -220,38 +218,38 @@ the values of environment variables:
}
```
+
+ Declaring environment variables in the `dependsOn` config with a `$` prefix is deprecated.
+
+
To alter the cache for _all_ tasks, you can declare environment variables in the
-`globalDependencies` array:
+`globalEnv` array:
```diff
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"build": {
- "dependsOn": [
- "^build",
- // env vars will impact hashes of all "build" tasks
- "$SOME_ENV_VAR",
- ],
+ "dependsOn": ["^build"],
+ // env vars will impact hashes of all "build" tasks
+ "env": ["SOME_ENV_VAR"],
"outputs": ["dist/**"]
},
// override settings for the "build" task for the "web" app
"web#build": {
- "dependsOn": [
- "^build",
+ "dependsOn": ["^build"],
+ "env": [
// env vars that will impact the hash of "build" task for only "web" app
- "$STRIPE_SECRET_KEY",
- "$NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
- "$NEXT_PUBLIC_ANALYTICS_ID",
+ "STRIPE_SECRET_KEY",
+ "NEXT_PUBLIC_STRIPE_PUBLIC_KEY",
+ "NEXT_PUBLIC_ANALYTICS_ID"
],
"outputs": [".next/**"],
},
},
-+ "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,
++ "globalEnv": [
++ "GITHUB_TOKEN" // env var that will impact the hashes of all tasks,
+ ]
}
```
@@ -268,9 +266,9 @@ To help ensure correct caching across environments Turborepo 1.4+ will automatic
{
"pipeline": {
"build": {
- "dependsOn": [
- "^build"
-- "$NEXT_PUBLIC_EXAMPLE_ENV_VAR"
+ "dependsOn": ["^build"],
+ "env": [
+- "NEXT_PUBLIC_EXAMPLE_ENV_VAR"
]
}
}
diff --git a/docs/pages/docs/reference/codemods.mdx b/docs/pages/docs/reference/codemods.mdx
index c61f65e4eafcb..e8cb88c1d51c0 100644
--- a/docs/pages/docs/reference/codemods.mdx
+++ b/docs/pages/docs/reference/codemods.mdx
@@ -125,3 +125,67 @@ Run the codemod:
```sh
npx @turbo/codemod create-turbo-config
```
+
+### `migrate-env-var-dependencies`
+
+Migrates all environment variable dependencies in `turbo.json` from `dependsOn` and `globalDependencies` to `env` and `globalEnv` respecively.
+
+For example:
+
+```json
+// Before, turbo.json
+{
+ "$schema": "https://turborepo.org/schema.json",
+ "globalDependencies": [".env", "$CI_ENV"],
+ "pipeline": {
+ "build": {
+ "dependsOn": ["^build", "$API_BASE"],
+ "outputs": [".next/**"]
+ },
+ "lint": {
+ "outputs": []
+ },
+ "dev": {
+ "cache": false
+ }
+ }
+}
+
+```
+
+````diff
+// After, turbo.json
+{
+ "$schema": "https://turborepo.org/schema.json",
+- "globalDependencies": [".env", "$CI_ENV"],
++ "globalDependencies": [".env"],
++ "globalEnv": ["CI_ENV"],
+ "pipeline": {
+ "build": {
+- "dependsOn": ["^build", "$API_BASE"],
++ "dependsOn": ["^build"],
++ "env": ["API_BASE"],
+ "outputs": [".next/**"],
+ },
+ "lint": {
+ "outputs": []
+ },
+ "dev": {
+ "cache": false
+ }
+ }
+}
+
+#### Usage
+
+Go to your project:
+
+```sh
+cd path-to-your-turborepo/
+````
+
+Run the codemod:
+
+```sh
+npx @turbo/codemod migrate-env-var-dependencies
+```
diff --git a/docs/pages/docs/reference/configuration.mdx b/docs/pages/docs/reference/configuration.mdx
index ac367f230010a..44e6e480af1a4 100644
--- a/docs/pages/docs/reference/configuration.mdx
+++ b/docs/pages/docs/reference/configuration.mdx
@@ -29,8 +29,8 @@ This is useful for busting the cache based on `.env` files (not in Git), environ
"globalDependencies": [
".env", // contents will impact hashes of all tasks
"tsconfig.json", // contents will impact hashes of all tasks
- "$GITHUB_TOKEN"// value will impact the hashes of all tasks
- ]
+ ],
+ "globalEnv": ["GITHUB_TOKEN"] // value will impact the hashes of all tasks
}
```
@@ -64,7 +64,7 @@ Each key in the `pipeline` object is the name of a task that can be executed by
`type: string[]`
-The list of tasks and environment variables that this task depends on.
+The list of tasks this task depends on.
Prefixing an item in `dependsOn` with a `^` tells `turbo` that this pipeline task depends on the workspace's topological dependencies completing the task with the `^` prefix first (e.g. "a workspace's `build` tasks should only run once all of its `dependencies` and `devDependencies` have completed their own `build` commands").
@@ -72,7 +72,12 @@ Items in `dependsOn` without `^` prefix, express the relationships between tasks
Prefixing an item in `dependsOn` with a `$` tells `turbo` that this pipeline task depends on the value of that environment variable.
-**Example: Basics**
+
+ Using `$` to declare environment variables in the `dependsOn` config is deprecated. Use the
+ `env` key instead.
+
+
+**Example**
```jsonc
{
@@ -99,29 +104,31 @@ Prefixing an item in `dependsOn` with a `$` tells `turbo` that this pipeline tas
}
```
-**Example: Environment Variables and Tasks**
+### `env`
+
+`type: string[]`
+
+The list of environment variables a task depends on.
+
+**Example**
```jsonc
{
"$schema": "https://turborepo.org/schema.json",
"pipeline": {
"build": {
- "dependsOn": [
- "^build",
- "$SOMETHING_ELSE" // value will impact the hashes of all build tasks
- ],
+ "dependsOn": ["^build"],
+ "env": ["SOMETHING_ELSE"], // value will impact the hashes of all build tasks
"outputs": ["dist/**", ".next/**"]
},
"web#build": {
- "dependsOn": [
- "^build",
- "$STRIPE_SECRET_KEY", // value will impact hash of only web's build task
- ],
+ "dependsOn": ["^build"],
+ "env": ["STRIPE_SECRET_KEY"], // value will impact hash of only web's build task
"outputs": [".next/**"]
}
},
- "globalDependencies": [
- "$GITHUB_TOKEN"// value will impact the hashes of all tasks
+ "globalEnv": [
+ "GITHUB_TOKEN"// value will impact the hashes of all tasks
]
}
```
diff --git a/examples/with-docker/turbo.json b/examples/with-docker/turbo.json
index 3b477afa314b2..dc9daf1bf5dba 100644
--- a/examples/with-docker/turbo.json
+++ b/examples/with-docker/turbo.json
@@ -3,7 +3,8 @@
"pipeline": {
"build": {
"outputs": ["dist/**", ".next/**", "public/dist/**"],
- "dependsOn": ["^build", "$NEXT_PUBLIC_API_HOST"]
+ "dependsOn": ["^build"],
+ "env": ["NEXT_PUBLIC_API_HOST"]
},
"test": {
"outputs": ["coverage/**"],