From f0b581d1443a8ca8152cd440c9febf23e5642be4 Mon Sep 17 00:00:00 2001
From: Caleb Ukle <caleb@nrwl.io>
Date: Mon, 12 Dec 2022 15:55:28 -0600
Subject: [PATCH] docs(core): add info about defaultConfiguration (#13775)

---
 .../recipes/use-executor-configurations.md    | 30 ++++++++++++++++++-
 packages/nx/schemas/project-schema.json       |  4 +++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/docs/shared/recipes/use-executor-configurations.md b/docs/shared/recipes/use-executor-configurations.md
index 1223b583f1891..928f9e58a73eb 100644
--- a/docs/shared/recipes/use-executor-configurations.md
+++ b/docs/shared/recipes/use-executor-configurations.md
@@ -22,7 +22,7 @@ The `configurations` property provides extra sets of values that will be merged
 ```
 
 You can select a configuration like this: `nx build mylib --configuration=production`
-or `nx run mylib:build:configuration=production`.
+or `nx run mylib:build:production`.
 
 The following code snippet shows how the executor options get constructed:
 
@@ -36,3 +36,31 @@ require(`@nrwl/jest`).executors['jest']({
 
 The selected configuration adds/overrides the default options, and the provided command line args add/override the
 configuration options.
+
+## Default Configuration
+
+When using multiple configurations for a given target, it's helpful to provide a default configuration.
+For example, running e2e tests for multiple environments. By default it would make sense to use a `dev` configuration for day to day work, but having the ability to run against an internal staging environment for the QA team.
+
+```json {% fileName="project.json" %}
+{
+  "e2e": {
+    "executor": "@nrwl/cypress:cypress",
+    "options": {
+      "cypressConfig": "apps/my-app-e2e/cypress.config.ts"
+    },
+    "configurations": {
+      "dev": {
+        "devServerTarget": "my-app:serve"
+      },
+      "qa": {
+        "baseUrl": "https://some-internal-url.example.com"
+      }
+    },
+    "defaultConfiguration": "dev"
+  }
+}
+```
+
+When running `nx e2e my-app-e2e`, the _dev_ configuration will be used. In this case using the local dev server for `my-app`.
+You can always run the other configurations by explicitly providing the configuration i.e. `nx e2e my-app-e2e --configuration=qa` or `nx run my-app-e2e:e2e:qa`
diff --git a/packages/nx/schemas/project-schema.json b/packages/nx/schemas/project-schema.json
index 2204ed13151bf..42d890a5ea122 100644
--- a/packages/nx/schemas/project-schema.json
+++ b/packages/nx/schemas/project-schema.json
@@ -30,6 +30,10 @@
               "type": "string"
             }
           },
+          "defaultConfiguration": {
+            "type": "string",
+            "description": "The name of a configuration to use as the default if a configuration is not provided"
+          },
           "configurations": {
             "type": "object",
             "description": "provides extra sets of values that will be merged into the options map",