docs(core): add terminal-ui recipe (#30918)

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",

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",

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": "",

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",

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:

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 `<ctrl>+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.

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)

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,
 };