From 821de905bc0d0d69f636d349a3a75adb8e712adb Mon Sep 17 00:00:00 2001 From: Anthony Shew Date: Tue, 23 Sep 2025 17:09:40 -0700 Subject: [PATCH 1/5] docs: update schema.json --- packages/turbo-types/schemas/schema.json | 50 +++++++++------------ packages/turbo-types/schemas/schema.v2.json | 49 +++++++++----------- 2 files changed, 43 insertions(+), 56 deletions(-) diff --git a/packages/turbo-types/schemas/schema.json b/packages/turbo-types/schemas/schema.json index 1543b141f5e4b..a6330365660d6 100644 --- a/packages/turbo-types/schemas/schema.json +++ b/packages/turbo-types/schemas/schema.json @@ -105,15 +105,25 @@ }, "futureFlags": { "type": "object", - "additionalProperties": {}, - "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.", + "properties": { + "turboExtendsKeyword": { + "type": "boolean", + "description": "Enable `$TURBO_EXTENDS$`\n\nWhen enabled, allows using `$TURBO_EXTENDS$` in array fields. This will change the default behavior of overriding the field to instead append.", + "default": false + }, + "nonRootExtends": { + "type": "boolean", + "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first.", + "default": false + } + }, + "additionalProperties": false, + "description": "Opt into experimental features, beta features, and breaking changes prior to major releases.", "default": {} } }, "additionalProperties": false, - "required": [ - "tasks" - ] + "required": ["tasks"] }, "Pipeline": { "type": "object", @@ -206,13 +216,7 @@ }, "OutputLogs": { "type": "string", - "enum": [ - "full", - "hash-only", - "new-only", - "errors-only", - "none" - ] + "enum": ["full", "hash-only", "new-only", "errors-only", "none"] }, "RemoteCache": { "type": "object", @@ -265,10 +269,7 @@ }, "UI": { "type": "string", - "enum": [ - "tui", - "stream" - ] + "enum": ["tui", "stream"] }, "RelativeUnixPath": { "type": "string", @@ -276,10 +277,7 @@ }, "EnvMode": { "type": "string", - "enum": [ - "strict", - "loose" - ] + "enum": ["strict", "loose"] }, "RootBoundariesConfig": { "type": "object", @@ -357,9 +355,7 @@ "type": "string" }, "description": "This key is only available in Workspace Configs and cannot be used in your root turbo.json.\n\nTells turbo to extend your root `turbo.json` and overrides with the keys provided in your Workspace Configs.\n\nCurrently, only the \"//\" value is allowed.", - "default": [ - "//" - ] + "default": ["//"] }, "tags": { "type": "array", @@ -373,10 +369,7 @@ "description": "Configuration for `turbo boundaries` that is specific to this package" } }, - "required": [ - "extends", - "tasks" - ], + "required": ["extends", "tasks"], "additionalProperties": false, "description": "A `turbo.json` file in a package in the monorepo (not the root)" }, @@ -394,4 +387,5 @@ "additionalProperties": false } } -} \ No newline at end of file +} + diff --git a/packages/turbo-types/schemas/schema.v2.json b/packages/turbo-types/schemas/schema.v2.json index 1543b141f5e4b..77c47546cfabf 100644 --- a/packages/turbo-types/schemas/schema.v2.json +++ b/packages/turbo-types/schemas/schema.v2.json @@ -105,15 +105,25 @@ }, "futureFlags": { "type": "object", - "additionalProperties": {}, - "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.", + "properties": { + "turboExtendsKeyword": { + "type": "boolean", + "description": "Enable `$TURBO_EXTENDS$`\n\nWhen enabled, allows using `$TURBO_EXTENDS$` in array fields. This will change the default behavior of overriding the field to instead append.", + "default": false + }, + "nonRootExtends": { + "type": "boolean", + "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first.", + "default": false + } + }, + "additionalProperties": false, + "description": "Opt into experimental features, beta features, and breaking changes prior to major releases.", "default": {} } }, "additionalProperties": false, - "required": [ - "tasks" - ] + "required": ["tasks"] }, "Pipeline": { "type": "object", @@ -206,13 +216,7 @@ }, "OutputLogs": { "type": "string", - "enum": [ - "full", - "hash-only", - "new-only", - "errors-only", - "none" - ] + "enum": ["full", "hash-only", "new-only", "errors-only", "none"] }, "RemoteCache": { "type": "object", @@ -265,10 +269,7 @@ }, "UI": { "type": "string", - "enum": [ - "tui", - "stream" - ] + "enum": ["tui", "stream"] }, "RelativeUnixPath": { "type": "string", @@ -276,10 +277,7 @@ }, "EnvMode": { "type": "string", - "enum": [ - "strict", - "loose" - ] + "enum": ["strict", "loose"] }, "RootBoundariesConfig": { "type": "object", @@ -357,9 +355,7 @@ "type": "string" }, "description": "This key is only available in Workspace Configs and cannot be used in your root turbo.json.\n\nTells turbo to extend your root `turbo.json` and overrides with the keys provided in your Workspace Configs.\n\nCurrently, only the \"//\" value is allowed.", - "default": [ - "//" - ] + "default": ["//"] }, "tags": { "type": "array", @@ -373,10 +369,7 @@ "description": "Configuration for `turbo boundaries` that is specific to this package" } }, - "required": [ - "extends", - "tasks" - ], + "required": ["extends", "tasks"], "additionalProperties": false, "description": "A `turbo.json` file in a package in the monorepo (not the root)" }, @@ -394,4 +387,4 @@ "additionalProperties": false } } -} \ No newline at end of file +} From ec1b1597a40f8a9bb38dbd23af8d79b6462cb38a Mon Sep 17 00:00:00 2001 From: Anthony Shew Date: Tue, 23 Sep 2025 17:23:07 -0700 Subject: [PATCH 2/5] WIP c79cd --- packages/turbo-types/schemas/schema.json | 50 ++++++++++++++------- packages/turbo-types/schemas/schema.v2.json | 49 ++++++++++++++------ packages/turbo-types/src/types/config-v2.ts | 16 ++++++- 3 files changed, 85 insertions(+), 30 deletions(-) diff --git a/packages/turbo-types/schemas/schema.json b/packages/turbo-types/schemas/schema.json index a6330365660d6..03ea59da6b20c 100644 --- a/packages/turbo-types/schemas/schema.json +++ b/packages/turbo-types/schemas/schema.json @@ -106,24 +106,28 @@ "futureFlags": { "type": "object", "properties": { - "turboExtendsKeyword": { + "turbo_extends_keyword": { "type": "boolean", - "description": "Enable `$TURBO_EXTENDS$`\n\nWhen enabled, allows using `$TURBO_EXTENDS$` in array fields. This will change the default behavior of overriding the field to instead append.", - "default": false + "description": "Enable `$TURBO_EXTENDS$`\n\n When enabled, allows using `$TURBO_EXTENDS$` in array fields. This will change the default behavior of overriding the field to instead append." }, - "nonRootExtends": { + "non_root_extends": { "type": "boolean", - "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first.", - "default": false + "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first." } }, + "required": [ + "turbo_extends_keyword", + "non_root_extends" + ], "additionalProperties": false, - "description": "Opt into experimental features, beta features, and breaking changes prior to major releases.", + "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.", "default": {} } }, "additionalProperties": false, - "required": ["tasks"] + "required": [ + "tasks" + ] }, "Pipeline": { "type": "object", @@ -216,7 +220,13 @@ }, "OutputLogs": { "type": "string", - "enum": ["full", "hash-only", "new-only", "errors-only", "none"] + "enum": [ + "full", + "hash-only", + "new-only", + "errors-only", + "none" + ] }, "RemoteCache": { "type": "object", @@ -269,7 +279,10 @@ }, "UI": { "type": "string", - "enum": ["tui", "stream"] + "enum": [ + "tui", + "stream" + ] }, "RelativeUnixPath": { "type": "string", @@ -277,7 +290,10 @@ }, "EnvMode": { "type": "string", - "enum": ["strict", "loose"] + "enum": [ + "strict", + "loose" + ] }, "RootBoundariesConfig": { "type": "object", @@ -355,7 +371,9 @@ "type": "string" }, "description": "This key is only available in Workspace Configs and cannot be used in your root turbo.json.\n\nTells turbo to extend your root `turbo.json` and overrides with the keys provided in your Workspace Configs.\n\nCurrently, only the \"//\" value is allowed.", - "default": ["//"] + "default": [ + "//" + ] }, "tags": { "type": "array", @@ -369,7 +387,10 @@ "description": "Configuration for `turbo boundaries` that is specific to this package" } }, - "required": ["extends", "tasks"], + "required": [ + "extends", + "tasks" + ], "additionalProperties": false, "description": "A `turbo.json` file in a package in the monorepo (not the root)" }, @@ -387,5 +408,4 @@ "additionalProperties": false } } -} - +} \ No newline at end of file diff --git a/packages/turbo-types/schemas/schema.v2.json b/packages/turbo-types/schemas/schema.v2.json index 77c47546cfabf..03ea59da6b20c 100644 --- a/packages/turbo-types/schemas/schema.v2.json +++ b/packages/turbo-types/schemas/schema.v2.json @@ -106,24 +106,28 @@ "futureFlags": { "type": "object", "properties": { - "turboExtendsKeyword": { + "turbo_extends_keyword": { "type": "boolean", - "description": "Enable `$TURBO_EXTENDS$`\n\nWhen enabled, allows using `$TURBO_EXTENDS$` in array fields. This will change the default behavior of overriding the field to instead append.", - "default": false + "description": "Enable `$TURBO_EXTENDS$`\n\n When enabled, allows using `$TURBO_EXTENDS$` in array fields. This will change the default behavior of overriding the field to instead append." }, - "nonRootExtends": { + "non_root_extends": { "type": "boolean", - "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first.", - "default": false + "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first." } }, + "required": [ + "turbo_extends_keyword", + "non_root_extends" + ], "additionalProperties": false, - "description": "Opt into experimental features, beta features, and breaking changes prior to major releases.", + "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.", "default": {} } }, "additionalProperties": false, - "required": ["tasks"] + "required": [ + "tasks" + ] }, "Pipeline": { "type": "object", @@ -216,7 +220,13 @@ }, "OutputLogs": { "type": "string", - "enum": ["full", "hash-only", "new-only", "errors-only", "none"] + "enum": [ + "full", + "hash-only", + "new-only", + "errors-only", + "none" + ] }, "RemoteCache": { "type": "object", @@ -269,7 +279,10 @@ }, "UI": { "type": "string", - "enum": ["tui", "stream"] + "enum": [ + "tui", + "stream" + ] }, "RelativeUnixPath": { "type": "string", @@ -277,7 +290,10 @@ }, "EnvMode": { "type": "string", - "enum": ["strict", "loose"] + "enum": [ + "strict", + "loose" + ] }, "RootBoundariesConfig": { "type": "object", @@ -355,7 +371,9 @@ "type": "string" }, "description": "This key is only available in Workspace Configs and cannot be used in your root turbo.json.\n\nTells turbo to extend your root `turbo.json` and overrides with the keys provided in your Workspace Configs.\n\nCurrently, only the \"//\" value is allowed.", - "default": ["//"] + "default": [ + "//" + ] }, "tags": { "type": "array", @@ -369,7 +387,10 @@ "description": "Configuration for `turbo boundaries` that is specific to this package" } }, - "required": ["extends", "tasks"], + "required": [ + "extends", + "tasks" + ], "additionalProperties": false, "description": "A `turbo.json` file in a package in the monorepo (not the root)" }, @@ -387,4 +408,4 @@ "additionalProperties": false } } -} +} \ No newline at end of file diff --git a/packages/turbo-types/src/types/config-v2.ts b/packages/turbo-types/src/types/config-v2.ts index 38ee396f90f2d..9366e084fb6c1 100644 --- a/packages/turbo-types/src/types/config-v2.ts +++ b/packages/turbo-types/src/types/config-v2.ts @@ -196,7 +196,21 @@ export interface RootSchema extends BaseSchema { * * @defaultValue `{}` */ - futureFlags?: Record; + futureFlags?: { + /** Enable `$TURBO_EXTENDS$` + * + * When enabled, allows using `$TURBO_EXTENDS$` in array fields. + * This will change the default behavior of overriding the field to instead append. + */ + turbo_extends_keyword: boolean; + + /** Enable extending from a non-root `turbo.json` + * + * When enabled, allows using extends targeting `turbo.json`s other than + * root. All `turbo.json` must still extend from the root `turbo.json` first. + */ + non_root_extends: boolean; + }; } export interface Pipeline { From defbe7517d3814139e004d7e77587ebd5a5738f3 Mon Sep 17 00:00:00 2001 From: Anthony Shew Date: Tue, 23 Sep 2025 17:41:42 -0700 Subject: [PATCH 3/5] WIP 9acd5 --- packages/turbo-types/schemas/schema.json | 8 ++++---- packages/turbo-types/schemas/schema.v2.json | 8 ++++---- packages/turbo-types/src/types/config-v2.ts | 4 ++-- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/packages/turbo-types/schemas/schema.json b/packages/turbo-types/schemas/schema.json index 03ea59da6b20c..71d7197ca789e 100644 --- a/packages/turbo-types/schemas/schema.json +++ b/packages/turbo-types/schemas/schema.json @@ -106,18 +106,18 @@ "futureFlags": { "type": "object", "properties": { - "turbo_extends_keyword": { + "turboExtendsKeyword": { "type": "boolean", "description": "Enable `$TURBO_EXTENDS$`\n\n When enabled, allows using `$TURBO_EXTENDS$` in array fields. This will change the default behavior of overriding the field to instead append." }, - "non_root_extends": { + "nonRootExtends": { "type": "boolean", "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first." } }, "required": [ - "turbo_extends_keyword", - "non_root_extends" + "turboExtendsKeyword", + "nonRootExtends" ], "additionalProperties": false, "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.", diff --git a/packages/turbo-types/schemas/schema.v2.json b/packages/turbo-types/schemas/schema.v2.json index 03ea59da6b20c..71d7197ca789e 100644 --- a/packages/turbo-types/schemas/schema.v2.json +++ b/packages/turbo-types/schemas/schema.v2.json @@ -106,18 +106,18 @@ "futureFlags": { "type": "object", "properties": { - "turbo_extends_keyword": { + "turboExtendsKeyword": { "type": "boolean", "description": "Enable `$TURBO_EXTENDS$`\n\n When enabled, allows using `$TURBO_EXTENDS$` in array fields. This will change the default behavior of overriding the field to instead append." }, - "non_root_extends": { + "nonRootExtends": { "type": "boolean", "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first." } }, "required": [ - "turbo_extends_keyword", - "non_root_extends" + "turboExtendsKeyword", + "nonRootExtends" ], "additionalProperties": false, "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.", diff --git a/packages/turbo-types/src/types/config-v2.ts b/packages/turbo-types/src/types/config-v2.ts index 9366e084fb6c1..fb73307410c34 100644 --- a/packages/turbo-types/src/types/config-v2.ts +++ b/packages/turbo-types/src/types/config-v2.ts @@ -202,14 +202,14 @@ export interface RootSchema extends BaseSchema { * When enabled, allows using `$TURBO_EXTENDS$` in array fields. * This will change the default behavior of overriding the field to instead append. */ - turbo_extends_keyword: boolean; + turboExtendsKeyword: boolean; /** Enable extending from a non-root `turbo.json` * * When enabled, allows using extends targeting `turbo.json`s other than * root. All `turbo.json` must still extend from the root `turbo.json` first. */ - non_root_extends: boolean; + nonRootExtends: boolean; }; } From 7e66ee792d9d79495c14cff2a6fcbfd77c3ef255 Mon Sep 17 00:00:00 2001 From: Anthony Shew Date: Tue, 23 Sep 2025 17:43:33 -0700 Subject: [PATCH 4/5] WIP 856fb --- packages/turbo-types/schemas/schema.json | 4 ---- packages/turbo-types/schemas/schema.v2.json | 4 ---- packages/turbo-types/src/types/config-v2.ts | 4 ++-- 3 files changed, 2 insertions(+), 10 deletions(-) diff --git a/packages/turbo-types/schemas/schema.json b/packages/turbo-types/schemas/schema.json index 71d7197ca789e..47b50d28a5a77 100644 --- a/packages/turbo-types/schemas/schema.json +++ b/packages/turbo-types/schemas/schema.json @@ -115,10 +115,6 @@ "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first." } }, - "required": [ - "turboExtendsKeyword", - "nonRootExtends" - ], "additionalProperties": false, "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.", "default": {} diff --git a/packages/turbo-types/schemas/schema.v2.json b/packages/turbo-types/schemas/schema.v2.json index 71d7197ca789e..47b50d28a5a77 100644 --- a/packages/turbo-types/schemas/schema.v2.json +++ b/packages/turbo-types/schemas/schema.v2.json @@ -115,10 +115,6 @@ "description": "Enable extending from a non-root `turbo.json`\n\nWhen enabled, allows using extends targeting `turbo.json`s other than root. All `turbo.json` must still extend from the root `turbo.json` first." } }, - "required": [ - "turboExtendsKeyword", - "nonRootExtends" - ], "additionalProperties": false, "description": "Opt into breaking changes prior to major releases, experimental features, and beta features.", "default": {} diff --git a/packages/turbo-types/src/types/config-v2.ts b/packages/turbo-types/src/types/config-v2.ts index fb73307410c34..629671b7623bb 100644 --- a/packages/turbo-types/src/types/config-v2.ts +++ b/packages/turbo-types/src/types/config-v2.ts @@ -202,14 +202,14 @@ export interface RootSchema extends BaseSchema { * When enabled, allows using `$TURBO_EXTENDS$` in array fields. * This will change the default behavior of overriding the field to instead append. */ - turboExtendsKeyword: boolean; + turboExtendsKeyword?: boolean; /** Enable extending from a non-root `turbo.json` * * When enabled, allows using extends targeting `turbo.json`s other than * root. All `turbo.json` must still extend from the root `turbo.json` first. */ - nonRootExtends: boolean; + nonRootExtends?: boolean; }; } From 2f62b3cb425e5bf65618789df8a78303e3cd5452 Mon Sep 17 00:00:00 2001 From: Anthony Shew Date: Tue, 23 Sep 2025 18:45:37 -0700 Subject: [PATCH 5/5] WIP 959a2 --- .../content/docs/reference/configuration.mdx | 31 ++++++++++++++++++- 1 file changed, 30 insertions(+), 1 deletion(-) diff --git a/docs/site/content/docs/reference/configuration.mdx b/docs/site/content/docs/reference/configuration.mdx index 3fabffde8b6fa..8f0adaf0a8a8f 100644 --- a/docs/site/content/docs/reference/configuration.mdx +++ b/docs/site/content/docs/reference/configuration.mdx @@ -26,7 +26,27 @@ Configure the behavior of `turbo` by using a `turbo.json` file in your Workspace Extend from the root `turbo.json` to create specific configuration for a package using [Package Configurations](/docs/reference/package-configurations). - The only valid value for `extends` is `["//"]` to inherit configuration from the root `turbo.json`. -- If `extends` is used in the root `turbo.json`, it will be ignored. +- If `extends` is used in the root `turbo.json`, an error will be thrown. + +#### `$TURBO_EXTENDS` + + + Two Future Flags exist to opt into new features to allow for more + configuration flexibility. + + +By default, keys are completely overridden when using [Package Configurations](/docs/reference/package-configurations). To append to parent configuration, use the `$TURBO_EXTENDS` microsyntax: + +```json title="packages/ui/turbo.json" +{ + "extends": ["//"], + "tasks": { + "build": { + "dependsOn": ["$TURBO_EXTENDS$", "special-task"] + } + } +} +``` ### `globalDependencies` @@ -199,6 +219,15 @@ Adds a tag to a package for use with [Boundaries](/docs/reference/boundaries). This key only works in [Package Configurations](/docs/reference/package-configurations). Using this key in a root `turbo.json` will result in an error. +### `futureFlags` + +"Future flags" allow you to opt into experimental and beta features, and breaking changes prior to major releases. + +Current Future Flags: + +- `turboExtendsKeyword`: Enable usage of [`$TURBO_EXTENDS$` microsyntax](#turbo_extends) +- `nonRootExtends`: Enable [extending Package Configurations from other packages](#TODO) + ## Defining tasks ### `tasks`