diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index b926aec35d..0e2c21080e 100644 --- a/docs/generated/manifests/menus.json +++ b/docs/generated/manifests/menus.json @@ -1090,6 +1090,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Use the Terminal UI", + "path": "/recipes/running-tasks/terminal-ui", + "id": "terminal-ui", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Run Custom Commands", "path": "/recipes/running-tasks/run-commands-executor", @@ -2192,6 +2200,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Use the Terminal UI", + "path": "/recipes/running-tasks/terminal-ui", + "id": "terminal-ui", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Run Custom Commands", "path": "/recipes/running-tasks/run-commands-executor", @@ -2299,6 +2315,14 @@ "children": [], "disableCollapsible": false }, + { + "name": "Use the Terminal UI", + "path": "/recipes/running-tasks/terminal-ui", + "id": "terminal-ui", + "isExternal": false, + "children": [], + "disableCollapsible": false + }, { "name": "Run Custom Commands", "path": "/recipes/running-tasks/run-commands-executor", diff --git a/docs/generated/manifests/nx.json b/docs/generated/manifests/nx.json index 7bcba45790..993ba62429 100644 --- a/docs/generated/manifests/nx.json +++ b/docs/generated/manifests/nx.json @@ -1493,6 +1493,17 @@ "path": "/recipes/running-tasks/defining-task-pipeline", "tags": ["run-tasks"] }, + { + "id": "terminal-ui", + "name": "Use the Terminal UI", + "description": "", + "mediaImage": "", + "file": "shared/recipes/running-tasks/terminal-ui", + "itemList": [], + "isExternal": false, + "path": "/recipes/running-tasks/terminal-ui", + "tags": ["run-tasks", "terminal-ui"] + }, { "id": "run-commands-executor", "name": "Run Custom Commands", @@ -3002,6 +3013,17 @@ "path": "/recipes/running-tasks/defining-task-pipeline", "tags": ["run-tasks"] }, + { + "id": "terminal-ui", + "name": "Use the Terminal UI", + "description": "", + "mediaImage": "", + "file": "shared/recipes/running-tasks/terminal-ui", + "itemList": [], + "isExternal": false, + "path": "/recipes/running-tasks/terminal-ui", + "tags": ["run-tasks", "terminal-ui"] + }, { "id": "run-commands-executor", "name": "Run Custom Commands", @@ -3150,6 +3172,17 @@ "path": "/recipes/running-tasks/defining-task-pipeline", "tags": ["run-tasks"] }, + "/recipes/running-tasks/terminal-ui": { + "id": "terminal-ui", + "name": "Use the Terminal UI", + "description": "", + "mediaImage": "", + "file": "shared/recipes/running-tasks/terminal-ui", + "itemList": [], + "isExternal": false, + "path": "/recipes/running-tasks/terminal-ui", + "tags": ["run-tasks", "terminal-ui"] + }, "/recipes/running-tasks/run-commands-executor": { "id": "run-commands-executor", "name": "Run Custom Commands", diff --git a/docs/generated/manifests/tags.json b/docs/generated/manifests/tags.json index 97745bf5cd..ea7b25de58 100644 --- a/docs/generated/manifests/tags.json +++ b/docs/generated/manifests/tags.json @@ -100,6 +100,13 @@ "name": "Define a Task Pipeline", "path": "/recipes/running-tasks/defining-task-pipeline" }, + { + "description": "", + "file": "shared/recipes/running-tasks/terminal-ui", + "id": "terminal-ui", + "name": "Use the Terminal UI", + "path": "/recipes/running-tasks/terminal-ui" + }, { "description": "", "file": "shared/recipes/running-tasks/running-custom-commands", @@ -977,6 +984,15 @@ "path": "/nx-api/nx/documents/create-nx-workspace" } ], + "terminal-ui": [ + { + "description": "", + "file": "shared/recipes/running-tasks/terminal-ui", + "id": "terminal-ui", + "name": "Use the Terminal UI", + "path": "/recipes/running-tasks/terminal-ui" + } + ], "exec": [ { "description": "", diff --git a/docs/map.json b/docs/map.json index 9269ebe15f..af352c680c 100644 --- a/docs/map.json +++ b/docs/map.json @@ -391,6 +391,12 @@ "tags": ["run-tasks"], "file": "shared/recipes/running-tasks/defining-task-pipeline" }, + { + "name": "Use the Terminal UI", + "id": "terminal-ui", + "tags": ["run-tasks", "terminal-ui"], + "file": "shared/recipes/running-tasks/terminal-ui" + }, { "name": "Run Custom Commands", "id": "run-commands-executor", diff --git a/docs/shared/features/run-tasks.md b/docs/shared/features/run-tasks.md index b38db4d9f0..85deb3a3db 100644 --- a/docs/shared/features/run-tasks.md +++ b/docs/shared/features/run-tasks.md @@ -3,7 +3,7 @@ title: 'Run Tasks' description: 'Learn how to use Nx task runner to efficiently manage and execute tasks across multiple projects in your monorepo, including parallel execution and caching.' --- -# Run Tasks +# Tasks {% youtube src="https://youtu.be/aEdfYiA5U34" title="Run tasks with Nx" /%} @@ -14,7 +14,7 @@ In a monorepo setup, you don't just run tasks for a single project; you might ha - only run tasks for **projects affected by a given change** - **speed up task execution** with [caching](/features/cache-task-results) -## Defining Tasks +## Define Tasks Nx tasks can be created from existing `package.json` scripts, [inferred from tooling configuration files](/concepts/inferred-tasks), or defined in a `project.json` file. Nx combines these three sources to determine the tasks for a particular project. @@ -94,12 +94,18 @@ Learn more about [inferred tasks here](/concepts/inferred-tasks). The [project configuration docs](/reference/project-configuration) has the details for all the available configuration options. -## Running Tasks +## Run Tasks Nx uses the following syntax: ![Syntax for Running Tasks in Nx](/shared/images/run-target-syntax.svg) +{% callout type="note" title="Terminal UI" %} + +In Nx 21, task output is displayed in an [interactive terminal UI](/recipes/running-tasks/terminal-ui) that allows you to actively choose which task output to display, search through the list of tasks and display multiple tasks side by side. + +{% /callout %} + ### Run a Single Task To run the `test` task for the `header` project run this command: diff --git a/docs/shared/recipes/running-tasks/terminal-ui.md b/docs/shared/recipes/running-tasks/terminal-ui.md new file mode 100644 index 0000000000..91b131c2e2 --- /dev/null +++ b/docs/shared/recipes/running-tasks/terminal-ui.md @@ -0,0 +1,52 @@ +--- +title: Terminal UI +description: 'Learn how to leverage and configure the Nx Terminal UI when running tasks' +--- + +# Nx Terminal UI + +In version 21, Nx provides an interactive UI in the terminal to help you view the results of multiple tasks that are running in parallel. + +![Terminal UI Example](/shared/recipes/running-tasks/tui-example.png) + +## Enable/Disable the Terminal UI + +If your terminal and environment are supported then the Terminal UI will be enabled by default when you run any tasks with `nx run`/`nx run-many`/`nx affected` in Nx v21 and later. The Terminal UI will not be used in CI environments. + +If you want to manually disable the Terminal UI, you can set `NX_TUI=false` in your environment variables, or set `tui.enabled` to `false` in your `nx.json` configuration file. + +```json {% fileName="nx.json" %} +{ + "tui": { + "enabled": false + } +} +``` + +## Configure the Terminal UI + +There are also some configuration options that control the way the terminal UI behaves. + +### Auto-Exit + +By default, the Terminal UI will automatically exit 3 seconds after all relevant tasks have finished running. You can adjust this behavior in the following ways: + +- Set `"tui.autoExit"` to a number to change the number of seconds to wait before auto-exiting. +- Set `"tui.autoExit"` to `false` to disable auto-exiting and keep the Terminal UI open until you manually exit it with `+c`. +- Set `"tui.autoExit"` to `true` to exit automatically immediately after all tasks have finished running. + +```json {% fileName="nx.json" %} +{ + "tui": { + "autoExit": 3 // Equivalent of the default behavior: auto-exit after 3 seconds + } +} +``` + +## Use the Terminal UI + +The terminal UI is entirely controlled through keyboard shortcuts. You can view a list of the available shortcuts by typing `?`: + +![Terminal UI Help](/shared/recipes/running-tasks/tui-help.png) + +You can use these commands to hide and show up to 2 tasks at a time, filter the listed tasks and interact with tasks that are prompting for user input. diff --git a/docs/shared/recipes/running-tasks/tui-example.png b/docs/shared/recipes/running-tasks/tui-example.png new file mode 100644 index 0000000000..1fb88d69af Binary files /dev/null and b/docs/shared/recipes/running-tasks/tui-example.png differ diff --git a/docs/shared/recipes/running-tasks/tui-help.png b/docs/shared/recipes/running-tasks/tui-help.png new file mode 100644 index 0000000000..9e2d9bc6eb Binary files /dev/null and b/docs/shared/recipes/running-tasks/tui-help.png differ diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 7a201d6643..73f1cb9b73 100644 --- a/docs/shared/reference/sitemap.md +++ b/docs/shared/reference/sitemap.md @@ -56,6 +56,7 @@ - [Configure Inputs for Task Caching](/recipes/running-tasks/configure-inputs) - [Configure Outputs for Task Caching](/recipes/running-tasks/configure-outputs) - [Define a Task Pipeline](/recipes/running-tasks/defining-task-pipeline) + - [Use the Terminal UI](/recipes/running-tasks/terminal-ui) - [Run Custom Commands](/recipes/running-tasks/run-commands-executor) - [Pass Args to Commands](/recipes/running-tasks/pass-args-to-commands) - [Run Tasks in Parallel](/recipes/running-tasks/run-tasks-in-parallel) diff --git a/nx-dev/nx-dev/redirect-rules.js b/nx-dev/nx-dev/redirect-rules.js index 3f50b3b7ab..440f4da811 100644 --- a/nx-dev/nx-dev/redirect-rules.js +++ b/nx-dev/nx-dev/redirect-rules.js @@ -1227,6 +1227,11 @@ const powerpackRedirects = { '/nx-api/shared-fs-cache/documents/overview', }; +const tmpTerminalUiRedirects = { + // This will be a dedicated landing page in a follow up, redirect to the recipe for now + '/terminal-ui': '/recipes/running-tasks/terminal-ui', +}; + /** * Public export API */ @@ -1263,4 +1268,5 @@ module.exports = { enterpriseNxSection, manualDTEUpdate, powerpackRedirects, + tmpTerminalUiRedirects, };