From c2c664a055f18da64ed776451b6e38eb3d207cd8 Mon Sep 17 00:00:00 2001
From: Isaac Mann <isaacplmann@users.noreply.github.com>
Date: Thu, 7 Sep 2023 09:36:25 -0400
Subject: [PATCH] docs(core): add directory flag to all project generators
 (#18977)

---
 .../angular/generators/application.json       |  2 +-
 .../packages/angular/generators/library.json  |  2 +-
 .../packages/esbuild/documents/overview.md    |  6 +++-
 .../packages/js/generators/library.json       |  2 +-
 .../packages/next/generators/application.json |  2 +-
 .../packages/next/generators/library.json     |  2 +-
 .../react/generators/application.json         |  2 +-
 .../packages/web/generators/application.json  |  2 +-
 docs/shared/guides/react-native.md            |  6 ++--
 docs/shared/guides/remix.md                   |  8 +++--
 .../setup-incremental-builds-angular.md       |  6 +++-
 docs/shared/migration/migration-angularjs.md  |  6 +++-
 .../shared/packages/esbuild/esbuild-plugin.md |  6 +++-
 docs/shared/recipes/add-stack/add-astro.md    |  7 ++--
 docs/shared/recipes/add-stack/add-deno.md     | 12 +++++--
 docs/shared/recipes/add-stack/add-dotnet.md   | 12 +++++--
 docs/shared/recipes/add-stack/add-express.md  | 12 +++++--
 docs/shared/recipes/add-stack/add-fastify.md  | 12 +++++--
 docs/shared/recipes/add-stack/add-lit.md      | 12 +++++--
 docs/shared/recipes/add-stack/add-qwik.md     | 12 +++++--
 docs/shared/recipes/add-stack/add-rust.md     | 12 +++++--
 docs/shared/recipes/add-stack/add-solid.md    | 12 +++++--
 docs/shared/recipes/add-stack/add-svelte.md   |  6 +++-
 docs/shared/recipes/add-stack/add-vue.md      |  6 +++-
 docs/shared/recipes/deployment/deno-deploy.md |  6 +++-
 .../deployment/deno-netlify-edge-functions.md |  6 +++-
 .../storybook/one-storybook-for-all.md        |  6 +++-
 .../storybook/one-storybook-per-scope.md      | 10 ++++--
 .../one-storybook-with-composition.md         |  6 +++-
 docs/shared/reference/nx-json.md              | 32 +++++++++++++++++--
 packages/angular/docs/application-examples.md |  6 +++-
 packages/angular/docs/library-examples.md     |  6 +++-
 packages/js/docs/library-examples.md          |  6 +++-
 packages/next/docs/application-examples.md    |  6 +++-
 packages/next/docs/library-examples.md        |  6 +++-
 packages/react/docs/application-examples.md   |  6 +++-
 packages/web/docs/application-examples.md     |  6 +++-
 37 files changed, 222 insertions(+), 53 deletions(-)

diff --git a/docs/generated/packages/angular/generators/application.json b/docs/generated/packages/angular/generators/application.json
index 302ddafd9d..8c04afe750 100644
--- a/docs/generated/packages/angular/generators/application.json
+++ b/docs/generated/packages/angular/generators/application.json
@@ -177,7 +177,7 @@
     },
     "additionalProperties": false,
     "required": ["name"],
-    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Simple Application\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/angular:application my-app\n```\n\n{% /tab %}\n\n{% tab label=\"Specify directory and style extension\" %}\n\nCreate an application named `my-app` in the `my-dir` directory and use `scss` for styles:\n\n```bash\nnx g @nx/angular:app my-app --directory=my-dir --style=scss\n```\n\n{% /tab %}\n\n{% tab label=\"Single File Components application\" %}\n\nCreate an application with Single File Components (inline styles and inline templates):\n\n```bash\nnx g @nx/angular:app my-app --inlineStyle --inlineTemplate\n```\n\n{% /tab %}\n\n{% tab label=\"Standalone Components application\" %}\n\nCreate an application that is setup to use standalone components:\n\n```bash\nnx g @nx/angular:app my-app --standalone\n```\n\n{% /tab %}\n\n{% tab label=\"Set custom prefix and tags\" %}\n\nSet the prefix to apply to generated selectors and add tags to the application (used for linting).\n\n```bash\nnx g @nx/angular:app my-app --prefix=admin --tags=scope:admin,type:ui\n```\n\n{% /tab %}\n{% /tabs %}\n",
+    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Simple Application\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/angular:application my-app\n```\n\n{% /tab %}\n\n{% tab label=\"Specify directory and style extension\" %}\n\nCreate an application named `my-app` in the `my-dir` directory and use `scss` for styles:\n\n{% callout type=\"note\" title=\"Directory Flag Behavior Changes\" %}\nThe command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=my-dir`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.\n{% /callout %}\n\n```bash\nnx g @nx/angular:app my-app --directory=my-dir/my-app --style=scss\n```\n\n{% /tab %}\n\n{% tab label=\"Single File Components application\" %}\n\nCreate an application with Single File Components (inline styles and inline templates):\n\n```bash\nnx g @nx/angular:app my-app --inlineStyle --inlineTemplate\n```\n\n{% /tab %}\n\n{% tab label=\"Standalone Components application\" %}\n\nCreate an application that is setup to use standalone components:\n\n```bash\nnx g @nx/angular:app my-app --standalone\n```\n\n{% /tab %}\n\n{% tab label=\"Set custom prefix and tags\" %}\n\nSet the prefix to apply to generated selectors and add tags to the application (used for linting).\n\n```bash\nnx g @nx/angular:app my-app --prefix=admin --tags=scope:admin,type:ui\n```\n\n{% /tab %}\n{% /tabs %}\n",
     "presets": []
   },
   "aliases": ["app"],
diff --git a/docs/generated/packages/angular/generators/library.json b/docs/generated/packages/angular/generators/library.json
index 8173680380..afc77f39bd 100644
--- a/docs/generated/packages/angular/generators/library.json
+++ b/docs/generated/packages/angular/generators/library.json
@@ -204,7 +204,7 @@
     },
     "additionalProperties": false,
     "required": ["name"],
-    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Simple Library\" %}\n\nCreates the `my-ui-lib` library with an `ui` tag:\n\n```bash\nnx g @nx/angular:library my-ui-lib --tags=ui\n```\n\n{% /tab %}\n\n{% tab label=\"Publishable Library\" %}\n\nCreates the `my-lib` library that can be built producing an output following the Angular Package Format (APF) to be distributed as an NPM package:\n\n```bash\nnx g @nx/angular:library my-lib --publishable --import-path=@my-org/my-lib\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable Library\" %}\n\nCreates the `my-lib` library with support for incremental builds:\n\n```bash\nnx g @nx/angular:library my-lib --buildable\n```\n\n{% /tab %}\n\n{% tab label=\"Nested Folder & Import\"%}\nCreates the `my-lib` library in the `nested` directory and sets the import path to `@myorg/nested/my-lib`:\n\n```bash\nnx g @nx/angular:library --directory=nested --importPath=@myorg/nested/my-lib my-lib\n```\n\n{% /tab %}\n\n{% tab label=\"Standalone component\"%}\nCreates the `my-standalone-lib` library with a standalone component as an entry point instead of an ng-module. The component can be used via the `myorg-standalone-component` selector.\n\n```bash\nnx g @nx/angular:library --standalone --selector=myorg-standalone-component  my-standalone-lib\n```\n\n{% /tab %}\n",
+    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Simple Library\" %}\n\nCreates the `my-ui-lib` library with an `ui` tag:\n\n```bash\nnx g @nx/angular:library my-ui-lib --tags=ui\n```\n\n{% /tab %}\n\n{% tab label=\"Publishable Library\" %}\n\nCreates the `my-lib` library that can be built producing an output following the Angular Package Format (APF) to be distributed as an NPM package:\n\n```bash\nnx g @nx/angular:library my-lib --publishable --import-path=@my-org/my-lib\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable Library\" %}\n\nCreates the `my-lib` library with support for incremental builds:\n\n```bash\nnx g @nx/angular:library my-lib --buildable\n```\n\n{% /tab %}\n\n{% tab label=\"Nested Folder & Import\"%}\nCreates the `my-lib` library in the `nested` directory and sets the import path to `@myorg/nested/my-lib`:\n\n{% callout type=\"note\" title=\"Directory Flag Behavior Changes\" %}\nThe command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=nested`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.\n{% /callout %}\n\n```bash\nnx g @nx/angular:library --directory=libs/nested/my-lib --importPath=@myorg/nested/my-lib my-lib\n```\n\n{% /tab %}\n\n{% tab label=\"Standalone component\"%}\nCreates the `my-standalone-lib` library with a standalone component as an entry point instead of an ng-module. The component can be used via the `myorg-standalone-component` selector.\n\n```bash\nnx g @nx/angular:library --standalone --selector=myorg-standalone-component  my-standalone-lib\n```\n\n{% /tab %}\n",
     "presets": []
   },
   "aliases": ["lib"],
diff --git a/docs/generated/packages/esbuild/documents/overview.md b/docs/generated/packages/esbuild/documents/overview.md
index e080e50349..0af2d5f537 100644
--- a/docs/generated/packages/esbuild/documents/overview.md
+++ b/docs/generated/packages/esbuild/documents/overview.md
@@ -32,10 +32,14 @@ yarn add -D @nx/esbuild
 
 ### Creating a new JS library
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 You can add a new library that builds using esbuild with:
 
 ```shell
-nx g @nx/js:lib mylib --bundler=esbuild
+nx g @nx/js:lib mylib --directory=libs/mylib --bundler=esbuild
 ```
 
 This command will install the esbuild plugin if needed, and set `@nx/esbuild:esbuild` executor for the `build` target.
diff --git a/docs/generated/packages/js/generators/library.json b/docs/generated/packages/js/generators/library.json
index 0673c658b5..51f017a3c0 100644
--- a/docs/generated/packages/js/generators/library.json
+++ b/docs/generated/packages/js/generators/library.json
@@ -141,7 +141,7 @@
       }
     },
     "required": ["name"],
-    "examplesFile": "---\ntitle: JS library generator examples\ndescription: This page contains examples for the @nx/js:lib generator.\n---\n\nThe `@nx/js:lib` generator will generate a library for you, and it will configure it according to the options you provide.\n\n```bash\nnpx nx g @nx/js:lib mylib\n```\n\nBy default, the library that is generated when you use this executor without passing any options, like the example above, will be a buildable library, using the `@nx/js:tsc` executor as a builder.\n\nYou may configure the tools you want to use to build your library, or bundle it too, by passing the `--bundler` flag. The `--bundler` flag controls the compiler and/or the bundler that will be used to build your library. If you choose `tsc` or `swc`, the result will be a buildable library using either `tsc` or `swc` as the compiler. If you choose `rollup` or `vite`, the result will be a buildable library using `rollup` or `vite` as the bundler. In the case of `rollup`, it will default to the `tsc` compiler. If you choose `esbuild`, you may use the [`esbuildOptions` property](https://esbuild.github.io/api/) in your `project.json` under the `build` target options to specify whether you wish to bundle your library or not.\n\n## Examples\n\n{% tabs %}\n\n{% tab label=\"Buildable with default compiler (tsc)\" %}\n\nGenerate a buildable library using the `@nx/js:tsc` executor. This uses `tsc` as the compiler.\n\n```bash\nnpx nx g @nx/js:lib mylib\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable with SWC compiler\" %}\n\nGenerate a buildable library using [SWC](https://swc.rs) as the compiler. This will use the `@nx/js:swc` executor.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=swc\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable with tsc\" %}\n\nGenerate a buildable library using tsc as the compiler. This will use the `@nx/js:tsc` executor.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=tsc\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable, with Rollup as a bundler\" %}\n\nGenerate a buildable library using [Rollup](https://rollupjs.org) as the bundler. This will use the `@nx/rollup:rollup` executor. It will also use [SWC](https://swc.rs) as the compiler.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=rollup\n```\n\nIf you do not want to use `swc` as the compiler, and want to use the default `babel` compiler, you can do so in your `project.json` under the `build` target options, using the [`compiler` property](https://nx.dev/packages/rollup/executors/rollup#compiler):\n\n```jsonc {% fileName=\"libs/mylib/project.json\" %}\n\"build\": {\n  \"executor\": \"@nx/rollup:rollup\",\n  \"options\": {\n    //...\n    \"compiler\": \"babel\"\n  }\n}\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable, with Vite as a bundler\" %}\n\nGenerate a buildable library using [Vite](https://vitejs.dev/) as the bundler. This will use the `@nx/vite:build` executor.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=vite\n```\n\n{% /tab %}\n\n{% tab label=\"Using ESBuild\" %}\n\nGenerate a buildable library using [ESBuild](https://esbuild.github.io/) as the bundler. This will use the `@nx/esbuild:esbuild` executor.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=esbuild\n```\n\nIf you want to specify whether you want to bundle your library or not, you can do so in your `project.json` under the `build` target options, using the [`esbuildOptions` property](https://esbuild.github.io/api/):\n\n```jsonc {% fileName=\"libs/mylib/project.json\" %}\n\"build\": {\n  \"executor\": \"@nx/esbuild:esbuild\",\n  \"options\": {\n    //...\n    \"esbuildOptions\": {\n        \"bundle\": true\n    }\n  }\n}\n```\n\n{% /tab %}\n\n{% tab label=\"Minimal publishing target\" %}\n\nGenerate a **publishable** library with a minimal publishing target. The result will be a buildable library using the `@nx/js:tsc` executor, using `tsc` as the compiler. You can change the compiler or the bundler by passing the `--bundler` flag.\n\n```bash\nnpx nx g lib mylib --publishable\n```\n\n{% /tab %}\n\n{% tab label=\"Using directory flag\" %}\n\nGenerate a library named `mylib` and put it under a directory named `myapp` (`libs/myapp/mylib`)\n\n```shell\nnpx nx g lib mylib --directory=myapp\n```\n\n{% /tab %}\n\n{% tab label=\"Non-buildable library\" %}\n\nGenerate a non-buildable library.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=none\n```\n\n{% /tab %}\n\n{% /tabs %}\n",
+    "examplesFile": "---\ntitle: JS library generator examples\ndescription: This page contains examples for the @nx/js:lib generator.\n---\n\nThe `@nx/js:lib` generator will generate a library for you, and it will configure it according to the options you provide.\n\n```bash\nnpx nx g @nx/js:lib mylib\n```\n\nBy default, the library that is generated when you use this executor without passing any options, like the example above, will be a buildable library, using the `@nx/js:tsc` executor as a builder.\n\nYou may configure the tools you want to use to build your library, or bundle it too, by passing the `--bundler` flag. The `--bundler` flag controls the compiler and/or the bundler that will be used to build your library. If you choose `tsc` or `swc`, the result will be a buildable library using either `tsc` or `swc` as the compiler. If you choose `rollup` or `vite`, the result will be a buildable library using `rollup` or `vite` as the bundler. In the case of `rollup`, it will default to the `tsc` compiler. If you choose `esbuild`, you may use the [`esbuildOptions` property](https://esbuild.github.io/api/) in your `project.json` under the `build` target options to specify whether you wish to bundle your library or not.\n\n## Examples\n\n{% tabs %}\n\n{% tab label=\"Buildable with default compiler (tsc)\" %}\n\nGenerate a buildable library using the `@nx/js:tsc` executor. This uses `tsc` as the compiler.\n\n```bash\nnpx nx g @nx/js:lib mylib\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable with SWC compiler\" %}\n\nGenerate a buildable library using [SWC](https://swc.rs) as the compiler. This will use the `@nx/js:swc` executor.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=swc\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable with tsc\" %}\n\nGenerate a buildable library using tsc as the compiler. This will use the `@nx/js:tsc` executor.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=tsc\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable, with Rollup as a bundler\" %}\n\nGenerate a buildable library using [Rollup](https://rollupjs.org) as the bundler. This will use the `@nx/rollup:rollup` executor. It will also use [SWC](https://swc.rs) as the compiler.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=rollup\n```\n\nIf you do not want to use `swc` as the compiler, and want to use the default `babel` compiler, you can do so in your `project.json` under the `build` target options, using the [`compiler` property](https://nx.dev/packages/rollup/executors/rollup#compiler):\n\n```jsonc {% fileName=\"libs/mylib/project.json\" %}\n\"build\": {\n  \"executor\": \"@nx/rollup:rollup\",\n  \"options\": {\n    //...\n    \"compiler\": \"babel\"\n  }\n}\n```\n\n{% /tab %}\n\n{% tab label=\"Buildable, with Vite as a bundler\" %}\n\nGenerate a buildable library using [Vite](https://vitejs.dev/) as the bundler. This will use the `@nx/vite:build` executor.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=vite\n```\n\n{% /tab %}\n\n{% tab label=\"Using ESBuild\" %}\n\nGenerate a buildable library using [ESBuild](https://esbuild.github.io/) as the bundler. This will use the `@nx/esbuild:esbuild` executor.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=esbuild\n```\n\nIf you want to specify whether you want to bundle your library or not, you can do so in your `project.json` under the `build` target options, using the [`esbuildOptions` property](https://esbuild.github.io/api/):\n\n```jsonc {% fileName=\"libs/mylib/project.json\" %}\n\"build\": {\n  \"executor\": \"@nx/esbuild:esbuild\",\n  \"options\": {\n    //...\n    \"esbuildOptions\": {\n        \"bundle\": true\n    }\n  }\n}\n```\n\n{% /tab %}\n\n{% tab label=\"Minimal publishing target\" %}\n\nGenerate a **publishable** library with a minimal publishing target. The result will be a buildable library using the `@nx/js:tsc` executor, using `tsc` as the compiler. You can change the compiler or the bundler by passing the `--bundler` flag.\n\n```bash\nnpx nx g lib mylib --publishable\n```\n\n{% /tab %}\n\n{% tab label=\"Using directory flag\" %}\n\nGenerate a library named `mylib` and put it under a directory named `myapp` (`libs/myapp/mylib`)\n\n{% callout type=\"note\" title=\"Directory Flag Behavior Changes\" %}\nThe command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=myapp`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.\n{% /callout %}\n\n```shell\nnpx nx g lib mylib --directory=libs/myapp/mylib\n```\n\n{% /tab %}\n\n{% tab label=\"Non-buildable library\" %}\n\nGenerate a non-buildable library.\n\n```bash\nnpx nx g @nx/js:lib mylib --bundler=none\n```\n\n{% /tab %}\n\n{% /tabs %}\n",
     "presets": []
   },
   "aliases": ["lib"],
diff --git a/docs/generated/packages/next/generators/application.json b/docs/generated/packages/next/generators/application.json
index 9df9b163b6..bc8ba163bd 100644
--- a/docs/generated/packages/next/generators/application.json
+++ b/docs/generated/packages/next/generators/application.json
@@ -137,7 +137,7 @@
       }
     },
     "required": [],
-    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Create app in a directory\" %}\n\n```shell\nnx g app myapp --directory\n```\n\n{% /tab %}\n{% tab label=\"Use a custom Express server\" %}\n\n```shell\nnx g app myapp --custom-server\n```\n\n{% /tab %}\n{% tab label=\"Use plain JavaScript (not TypeScript)\" %}\n\n```shell\nnx g app myapp --js\n```\n\n{% /tab %}\n{% /tabs %}\n",
+    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Create app in a directory\" %}\n\n{% callout type=\"note\" title=\"Directory Flag Behavior Changes\" %}\nThe command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=nested`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.\n{% /callout %}\n\n```shell\nnx g app myapp --directory=apps/nested/myapp\n```\n\n{% /tab %}\n{% tab label=\"Use a custom Express server\" %}\n\n```shell\nnx g app myapp --custom-server\n```\n\n{% /tab %}\n{% tab label=\"Use plain JavaScript (not TypeScript)\" %}\n\n```shell\nnx g app myapp --js\n```\n\n{% /tab %}\n{% /tabs %}\n",
     "presets": []
   },
   "aliases": ["app"],
diff --git a/docs/generated/packages/next/generators/library.json b/docs/generated/packages/next/generators/library.json
index a51864e257..2c2b5c46c5 100644
--- a/docs/generated/packages/next/generators/library.json
+++ b/docs/generated/packages/next/generators/library.json
@@ -153,7 +153,7 @@
       }
     },
     "required": ["name"],
-    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Create a new lib\" %}\n\n```shell\nnx g lib my-lib\n```\n\n{% /tab %}\n{% tab label=\"Create a new lib under a directory\" %}\n\nThe following will create a library at `libs/shared/my-lib`.\n\n```shell\nnx g lib my-lib --directory=shared\n```\n\n{% /tab %}\n{% /tabs %}\n",
+    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Create a new lib\" %}\n\n```shell\nnx g lib my-lib\n```\n\n{% /tab %}\n{% tab label=\"Create a new lib under a directory\" %}\n\nThe following will create a library at `libs/shared/my-lib`.\n\n{% callout type=\"note\" title=\"Directory Flag Behavior Changes\" %}\nThe command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=shared`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.\n{% /callout %}\n\n```shell\nnx g lib my-lib --directory=libs/shared/my-lib\n```\n\n{% /tab %}\n{% /tabs %}\n",
     "presets": []
   },
   "aliases": ["lib"],
diff --git a/docs/generated/packages/react/generators/application.json b/docs/generated/packages/react/generators/application.json
index 51f8b34c45..a54771a680 100644
--- a/docs/generated/packages/react/generators/application.json
+++ b/docs/generated/packages/react/generators/application.json
@@ -191,7 +191,7 @@
       }
     },
     "required": ["name"],
-    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Simple Application\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/react:application my-app\n```\n\n{% /tab %}\n\n{% tab label=\"Application using Vite as bundler\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/react:app my-app --bundler=vite\n```\n\n{% /tab %}\n\n{% tab label=\"Specify directory and style extension\" %}\n\nCreate an application named `my-app` in the `my-dir` directory and use `scss` for styles:\n\n```bash\nnx g @nx/react:app my-app --directory=my-dir --style=scss\n```\n\n{% /tab %}\n\n{% tab label=\"Add tags\" %}\n\nAdd tags to the application (used for linting).\n\n```bash\nnx g @nx/react:app my-app --tags=scope:admin,type:ui\n```\n\n{% /tab %}\n{% /tabs %}\n",
+    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Simple Application\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/react:application my-app\n```\n\n{% /tab %}\n\n{% tab label=\"Application using Vite as bundler\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/react:app my-app --bundler=vite\n```\n\n{% /tab %}\n\n{% tab label=\"Specify directory and style extension\" %}\n\nCreate an application named `my-app` in the `my-dir` directory and use `scss` for styles:\n\n{% callout type=\"note\" title=\"Directory Flag Behavior Changes\" %}\nThe command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=my-dir`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.\n{% /callout %}\n\n```bash\nnx g @nx/react:app my-app --directory=apps/my-dir/my-app --style=scss\n```\n\n{% /tab %}\n\n{% tab label=\"Add tags\" %}\n\nAdd tags to the application (used for linting).\n\n```bash\nnx g @nx/react:app my-app --tags=scope:admin,type:ui\n```\n\n{% /tab %}\n{% /tabs %}\n",
     "presets": []
   },
   "aliases": ["app"],
diff --git a/docs/generated/packages/web/generators/application.json b/docs/generated/packages/web/generators/application.json
index d2e3ece2bb..759bb8d85a 100644
--- a/docs/generated/packages/web/generators/application.json
+++ b/docs/generated/packages/web/generators/application.json
@@ -106,7 +106,7 @@
       }
     },
     "required": ["name"],
-    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Simple Application\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/web:application my-app\n```\n\n{% /tab %}\n\n{% tab label=\"Application using Vite as bundler\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/web:app my-app --bundler=vite\n```\n\n{% /tab %}\n\n{% tab label=\"Specify directory\" %}\n\nCreate an application named `my-app` in the `my-dir` directory:\n\n```bash\nnx g @nx/web:app my-app --directory=my-dir\n```\n\n{% /tab %}\n\n{% tab label=\"Add tags\" %}\n\nAdd tags to the application (used for linting).\n\n```bash\nnx g @nx/web:app my-app --tags=scope:admin,type:ui\n```\n\n{% /tab %}\n{% /tabs %}\n",
+    "examplesFile": "## Examples\n\n{% tabs %}\n{% tab label=\"Simple Application\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/web:application my-app\n```\n\n{% /tab %}\n\n{% tab label=\"Application using Vite as bundler\" %}\n\nCreate an application named `my-app`:\n\n```bash\nnx g @nx/web:app my-app --bundler=vite\n```\n\n{% /tab %}\n\n{% tab label=\"Specify directory\" %}\n\nCreate an application named `my-app` in the `my-dir` directory:\n\n{% callout type=\"note\" title=\"Directory Flag Behavior Changes\" %}\nThe command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=my-dir`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.\n{% /callout %}\n\n```bash\nnx g @nx/web:app my-app --directory=apps/my-dir/my-app\n```\n\n{% /tab %}\n\n{% tab label=\"Add tags\" %}\n\nAdd tags to the application (used for linting).\n\n```bash\nnx g @nx/web:app my-app --tags=scope:admin,type:ui\n```\n\n{% /tab %}\n{% /tabs %}\n",
     "presets": []
   },
   "aliases": ["app"],
diff --git a/docs/shared/guides/react-native.md b/docs/shared/guides/react-native.md
index b5b0de8799..4c84372635 100644
--- a/docs/shared/guides/react-native.md
+++ b/docs/shared/guides/react-native.md
@@ -146,7 +146,7 @@ yarn add @nx/react-native --dev
 To create additional React Native apps run:
 
 ```shell
-npx nx g @nx/react-native:app
+npx nx g @nx/react-native:app mobile --directory=apps/mobile
 ```
 
 ## Generating a Library
@@ -163,7 +163,7 @@ and [Library Types](/concepts/more-concepts/library-types).
 To generate a new library run:
 
 ```shell
-npx nx g @nx/react-native:lib shared-ui-layout
+npx nx g @nx/react-native:lib shared-ui-layout --directory=libs/shared-ui-layout
 ```
 
 And you will see the following:
@@ -248,7 +248,7 @@ That's it! There is no need to build the library prior to using it. When you upd
 For libraries intended to be built and published to a registry (e.g. npm) you can use the `--publishable` and `--importPath` options.
 
 ```shell
-npx nx g @nx/react-native:lib shared-ui-layout --publishable --importPath=@happynrwl/ui-components
+npx nx g @nx/react-native:lib shared-ui-layout --directory=libs/shared-ui-layout --publishable --importPath=@happynrwl/ui-components
 npx nx g @nx/react-native:component layout --project=shared-ui-layout --export
 ```
 
diff --git a/docs/shared/guides/remix.md b/docs/shared/guides/remix.md
index 89ef078287..b1518674b9 100644
--- a/docs/shared/guides/remix.md
+++ b/docs/shared/guides/remix.md
@@ -33,7 +33,11 @@ npm install --save-dev @nx/remix
 
 ## Generate a Remix Application
 
-```{% command="nx g @nx/remix:app myapp" path="~/acme" %}
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
+```{% command="nx g @nx/remix:app myapp --directory=apps/myapp" path="~/acme" %}
 >  NX  Generating @nx/remix:application
 
 ✔ What unit test runner should be used? · vitest
@@ -120,7 +124,7 @@ When developing your application, it often makes sense to split your codebase in
 
 To generate a library to use in your Remix application run:
 
-```{% command="nx g @nx/remix:lib login" path="~/acme" %}
+```{% command="nx g @nx/remix:lib login --directory=libs/login" path="~/acme" %}
 >  NX  Generating @nx/remix:library
 
 ✔ What test runner should be used? · vitest
diff --git a/docs/shared/guides/setup-incremental-builds-angular.md b/docs/shared/guides/setup-incremental-builds-angular.md
index a6efc7b20d..25ee512aee 100644
--- a/docs/shared/guides/setup-incremental-builds-angular.md
+++ b/docs/shared/guides/setup-incremental-builds-angular.md
@@ -34,10 +34,14 @@ Please note that `ngcc` doesn’t support `pnpm` ([#32087](https://github.com/an
 
 To enable incremental builds you need to use buildable libraries.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 You can generate a new buildable library with:
 
 ```shell
-nx g @nx/angular:lib my-lib --buildable
+nx g @nx/angular:lib my-lib --directory=libs/my-lib --buildable
 ```
 
 The generated buildable library uses the `@nx/angular:ng-packagr-lite` executor which is optimized for the incremental
diff --git a/docs/shared/migration/migration-angularjs.md b/docs/shared/migration/migration-angularjs.md
index f0f2a2c89a..896ebd9958 100644
--- a/docs/shared/migration/migration-angularjs.md
+++ b/docs/shared/migration/migration-angularjs.md
@@ -53,8 +53,12 @@ Codebases with existing unit and e2e tests should continue to use whatever runne
 
 With the Angular capability added, generate your application:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx generate @nx/angular:application --name=realworld --unitTestRunner=karma --e2eTestRunner=protractor
+nx generate @nx/angular:application --name=realworld --directory=apps/realword --unitTestRunner=karma --e2eTestRunner=protractor
 ```
 
 Accept the default options for each prompt:
diff --git a/docs/shared/packages/esbuild/esbuild-plugin.md b/docs/shared/packages/esbuild/esbuild-plugin.md
index e080e50349..0af2d5f537 100644
--- a/docs/shared/packages/esbuild/esbuild-plugin.md
+++ b/docs/shared/packages/esbuild/esbuild-plugin.md
@@ -32,10 +32,14 @@ yarn add -D @nx/esbuild
 
 ### Creating a new JS library
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 You can add a new library that builds using esbuild with:
 
 ```shell
-nx g @nx/js:lib mylib --bundler=esbuild
+nx g @nx/js:lib mylib --directory=libs/mylib --bundler=esbuild
 ```
 
 This command will install the esbuild plugin if needed, and set `@nx/esbuild:esbuild` executor for the `build` target.
diff --git a/docs/shared/recipes/add-stack/add-astro.md b/docs/shared/recipes/add-stack/add-astro.md
index 7e2966c376..5102ea83d3 100644
--- a/docs/shared/recipes/add-stack/add-astro.md
+++ b/docs/shared/recipes/add-stack/add-astro.md
@@ -89,10 +89,13 @@ npm i -DE @nx/js@<nx-version>
 
 Then generate a project
 
-```{% command="nx g lib --simpleName --minimal}
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
+```{% command="nx g @nx/js:lib ui --directory=libs/ui --simpleName --minimal}
 >  NX  Generating @nx/js:library
 
-✔ What name would you like to use for the library? · ui
 ✔ Which unit test runner would you like to use? · none
 ✔ Which bundler would you like to use to build the library? Choose 'none' to skip build setup. · none
 
diff --git a/docs/shared/recipes/add-stack/add-deno.md b/docs/shared/recipes/add-stack/add-deno.md
index 6b8507cc91..b6985e1896 100644
--- a/docs/shared/recipes/add-stack/add-deno.md
+++ b/docs/shared/recipes/add-stack/add-deno.md
@@ -41,10 +41,14 @@ yarn add --dev @nx/deno
 
 ## Create an Application
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 Use the `app` generator to create a new Deno app.
 
 ```shell
-nx g @nx/deno:app deno-app
+nx g @nx/deno:app deno-app --directory=apps/deno-app
 ```
 
 Serve the API by running
@@ -57,10 +61,14 @@ This starts the application on localhost:4200 by default.
 
 ## Create a Library
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 To create a new library, run:
 
 ```shell
-nx g @nx/deno:lib my-lib
+nx g @nx/deno:lib my-lib --directory=libs/my-lib
 ```
 
 {% callout type="note" title="Deno Library Paths" %}
diff --git a/docs/shared/recipes/add-stack/add-dotnet.md b/docs/shared/recipes/add-stack/add-dotnet.md
index b59f05e871..75f4aaac88 100644
--- a/docs/shared/recipes/add-stack/add-dotnet.md
+++ b/docs/shared/recipes/add-stack/add-dotnet.md
@@ -105,8 +105,12 @@ This generates the following files:
 
 Use the `app` generator to create a new .NET app. For this demo, use the `nx` path naming convention and the `web-api` project template.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @nx-dotnet/core:app my-api --test-template nunit --language C#
+nx g @nx-dotnet/core:app my-api --directory=apps/my-api --test-template nunit --language C#
 ```
 
 Serve the API by running
@@ -119,8 +123,12 @@ nx serve my-api
 
 To create a new library, run the library generator. Use the `classlib` template.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @nx-dotnet/core:lib dotnet-lib
+nx g @nx-dotnet/core:lib dotnet-lib --directory=libs/dotnet-lib
 ```
 
 We also want to add a project reference from `my-api` to `dotnet-lib` using the `project-reference` generator:
diff --git a/docs/shared/recipes/add-stack/add-express.md b/docs/shared/recipes/add-stack/add-express.md
index 9abda68be1..83e5bd34fe 100644
--- a/docs/shared/recipes/add-stack/add-express.md
+++ b/docs/shared/recipes/add-stack/add-express.md
@@ -39,8 +39,12 @@ yarn add --dev @nx/express
 
 Use the `app` generator to create a new Express app.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @nx/express:app my-express-api
+nx g @nx/express:app my-express-api --directory=apps/my-express-api
 ```
 
 Serve the API by running
@@ -55,8 +59,12 @@ This starts the application on localhost:3333/api by default.
 
 The `@nx/express` plugin does not have a `library` generator, but we can use the `library` generator from the `@nx/js` plugin. To create a new library, install the `@nx/js` package and run:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @nx/js:lib my-lib
+nx g @nx/js:lib my-lib --directory=libs/my-lib
 ```
 
 Once the library is created, update the following files.
diff --git a/docs/shared/recipes/add-stack/add-fastify.md b/docs/shared/recipes/add-stack/add-fastify.md
index f0173ed58a..bf994b7a6a 100644
--- a/docs/shared/recipes/add-stack/add-fastify.md
+++ b/docs/shared/recipes/add-stack/add-fastify.md
@@ -56,8 +56,12 @@ yarn add --dev @nx/node
 
 Use the `app` generator to create a new Fastify app.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @nx/node:app fastify-api
+nx g @nx/node:app fastify-api --directory=apps/fastify-api
 ```
 
 Serve the API by running
@@ -72,8 +76,12 @@ This starts the application on localhost:3000/api by default.
 
 To create a new library, run:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @nx/node:lib my-lib
+nx g @nx/node:lib my-lib --directory=libs/my-lib
 ```
 
 Once the library is created, update the following files.
diff --git a/docs/shared/recipes/add-stack/add-lit.md b/docs/shared/recipes/add-stack/add-lit.md
index 9958fe6a4a..fc74523781 100644
--- a/docs/shared/recipes/add-stack/add-lit.md
+++ b/docs/shared/recipes/add-stack/add-lit.md
@@ -43,10 +43,14 @@ yarn add --dev @nx/node lit http-server
 
 ## Create an Application
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 We'll start with a node application and then tweak the settings to match what we need. Add a new node application to your workspace with the following command:
 
 ```shell
-nx g @nx/node:app my-lit-app
+nx g @nx/node:app my-lit-app --directory=apps/my-lit-app
 ```
 
 Choose `none` for the node framework, since we won't be using this as a node app.
@@ -163,10 +167,14 @@ nx serve my-lit-app
 
 ## Create a Library
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 Let's create a library that our Lit application is going to consume. To create a new library, install the `@nx/js` package and run:
 
 ```shell
-nx g @nx/js:lib my-lib
+nx g @nx/js:lib my-lib --directory=libs/my-lib
 ```
 
 Once the library is created, update the following files.
diff --git a/docs/shared/recipes/add-stack/add-qwik.md b/docs/shared/recipes/add-stack/add-qwik.md
index 5cd1fe5abe..51dd376566 100644
--- a/docs/shared/recipes/add-stack/add-qwik.md
+++ b/docs/shared/recipes/add-stack/add-qwik.md
@@ -60,16 +60,24 @@ If you need help finding the version of `nx` you are currently using, run `nx re
 
 Let's generate a new application using `qwik-nx`.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g qwik-nx:app todo
+nx g qwik-nx:app todo --directory=apps/todo
 ```
 
 ## Create a library
 
 Let's generate a new library using `qwik-nx`.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g qwik-nx:lib data-access
+nx g qwik-nx:lib data-access --directory=libs/data-access
 ```
 
 ## Create a Context in the library
diff --git a/docs/shared/recipes/add-stack/add-rust.md b/docs/shared/recipes/add-stack/add-rust.md
index 830159fd7e..e6d101155f 100644
--- a/docs/shared/recipes/add-stack/add-rust.md
+++ b/docs/shared/recipes/add-stack/add-rust.md
@@ -60,16 +60,24 @@ Using the preset provided by `@monodon/rust` will:
 
 Let's generate a new application using `@monodon/rust`.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @monodon/rust:binary myapp
+nx g @monodon/rust:binary myapp --directory=apps/myapp
 ```
 
 ## Create a library
 
 Let's generate a new library using `@monodon/rust`.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @monodon/rust:library cats
+nx g @monodon/rust:library cats --directory=libs/cats
 ```
 
 ## Update the `cats` library
diff --git a/docs/shared/recipes/add-stack/add-solid.md b/docs/shared/recipes/add-stack/add-solid.md
index c100f587ba..158cc5ebf0 100644
--- a/docs/shared/recipes/add-stack/add-solid.md
+++ b/docs/shared/recipes/add-stack/add-solid.md
@@ -53,11 +53,15 @@ pnpm i --save-dev @nx/web solid-devtools vite-plugin-solid
 
 ## Create an Application
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 We'll start with a web application and then tweak the settings to match what we need. Add a new web application to your
 workspace with the following command:
 
 ```shell
-nx g @nx/web:app my-solid-app --bundler=vite
+nx g @nx/web:app my-solid-app --directory=apps/my-solid-app --bundler=vite
 ```
 
 The `@nx/web:app` generator will create some files that are unnecessary for our Solid application.
@@ -228,11 +232,15 @@ You can now run `nx serve my-solid-app` and your Solid application can be viewed
 
 ## Create a Library
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 Let's create a library that our Solid application is going to consume. To create a new library, install the `@nx/js`
 package and run:
 
 ```shell
-nx g @nx/js:lib my-lib
+nx g @nx/js:lib my-lib --directory=libs/my-lib
 ```
 
 Once the library is created, update the following files.
diff --git a/docs/shared/recipes/add-stack/add-svelte.md b/docs/shared/recipes/add-stack/add-svelte.md
index 9dce4b51f8..dc1b0dd4e7 100644
--- a/docs/shared/recipes/add-stack/add-svelte.md
+++ b/docs/shared/recipes/add-stack/add-svelte.md
@@ -269,8 +269,12 @@ Navigate to `http://localhost:4200` and you should see your application.
 
 Instead of having our Counter directly defined in `App.svelte` file, let's create a library that we can import into our application.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx generate @nx/js:library --name=Counter --unitTestRunner=vitest --bundler=vite --importPath=@acme/counter
+nx generate @nx/js:library --name=Counter --directory=libs/counter --unitTestRunner=vitest --bundler=vite --importPath=@acme/counter
 ```
 
 Create the Counter component at `libs/counter/src/lib/Counter.svelte` and copy the contents of your `apps/acme/src/App.svelte` file into it.
diff --git a/docs/shared/recipes/add-stack/add-vue.md b/docs/shared/recipes/add-stack/add-vue.md
index e7ed39826c..a161b79515 100644
--- a/docs/shared/recipes/add-stack/add-vue.md
+++ b/docs/shared/recipes/add-stack/add-vue.md
@@ -231,7 +231,11 @@ nx serve acme
 
 Instead of having our Counter directly defined in the app we can instead create a library that exports the Counter component.
 
-Create a new library `nx generate @nx/js:library --name=Counter --unitTestRunner=vitest --bundler=vite --importPath=@acme/counter`
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
+Create a new library `nx generate @nx/js:library --name=Counter --directory=libs/counter --unitTestRunner=vitest --bundler=vite --importPath=@acme/counter`
 
 Create your Counter component at `counter/src/lib/Counter.vue` and copy the contents of your `src/App.vue` into it.
 
diff --git a/docs/shared/recipes/deployment/deno-deploy.md b/docs/shared/recipes/deployment/deno-deploy.md
index 9e97f65e9a..667bdc49d9 100644
--- a/docs/shared/recipes/deployment/deno-deploy.md
+++ b/docs/shared/recipes/deployment/deno-deploy.md
@@ -42,10 +42,14 @@ pnpm add -D @nx/deno
 {% /tab %}
 {% /tabs %}
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 Then generate a new Deno app with the following command:
 
 ```shell
-nx g @nx/deno:app denoapp
+nx g @nx/deno:app denoapp --directory=apps/denoapp
 ```
 
 ## Configuring Deno Deploy
diff --git a/docs/shared/recipes/deployment/deno-netlify-edge-functions.md b/docs/shared/recipes/deployment/deno-netlify-edge-functions.md
index 17d8b13256..228674f54e 100644
--- a/docs/shared/recipes/deployment/deno-netlify-edge-functions.md
+++ b/docs/shared/recipes/deployment/deno-netlify-edge-functions.md
@@ -40,10 +40,14 @@ pnpm add -D @nx/deno
 {% /tab %}
 {% /tabs %}
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 Then generate a new Deno app with the following command:
 
 ```shell
-nx g @nx/deno:app denoapp
+nx g @nx/deno:app denoapp --directory=apps/denoapp
 ```
 
 ## Adding a Netlify Serverless Function
diff --git a/docs/shared/recipes/storybook/one-storybook-for-all.md b/docs/shared/recipes/storybook/one-storybook-for-all.md
index e735b99bad..77e6aeff23 100644
--- a/docs/shared/recipes/storybook/one-storybook-for-all.md
+++ b/docs/shared/recipes/storybook/one-storybook-for-all.md
@@ -20,8 +20,12 @@ Let’s see how we can implement this solution:
 
 According to the framework you are using, use the corresponding generator to generate a new library. Let’s suppose that you are using React and all your stories are using `@storybook/react`:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @nx/react:library storybook-host
+nx g @nx/react:library storybook-host --directory=libs/storybook-host
 ```
 
 Now, you have a new library, which will act as a shell/host for all your stories.
diff --git a/docs/shared/recipes/storybook/one-storybook-per-scope.md b/docs/shared/recipes/storybook/one-storybook-per-scope.md
index d7c4367c79..a67b9a4227 100644
--- a/docs/shared/recipes/storybook/one-storybook-per-scope.md
+++ b/docs/shared/recipes/storybook/one-storybook-per-scope.md
@@ -91,10 +91,14 @@ Let's assume in this case that all our libraries are using Angular.
 
 Let's generate three Angular libraries, one for each scope, and let's call them `storybook-host-client`, `storybook-host-admin`, and `storybook-host-shared`. We can do this by running the following commands:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The commands below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g @nx/angular:lib storybook-host-client
-nx g @nx/angular:lib storybook-host-admin
-nx g @nx/angular:lib storybook-host-shared
+nx g @nx/angular:lib storybook-host-client --directory=libs/storybook-host-client
+nx g @nx/angular:lib storybook-host-admin --directory=libs/storybook-host-admin
+nx g @nx/angular:lib storybook-host-shared --directory=libs/storybook-host-shared
 ```
 
 ### Generate the Storybook configuration for the libraries
diff --git a/docs/shared/recipes/storybook/one-storybook-with-composition.md b/docs/shared/recipes/storybook/one-storybook-with-composition.md
index 54d9229f77..aa3279fd66 100644
--- a/docs/shared/recipes/storybook/one-storybook-with-composition.md
+++ b/docs/shared/recipes/storybook/one-storybook-with-composition.md
@@ -28,10 +28,14 @@ We are going to assume that you are at the state where you already have your `st
 
 It does not matter which framework you use for the host Storybook library. It can be any framework really, and it does not have to be one of the frameworks that are used in the hosted apps. The only thing that is important is for this host library to have _at least one story_. This is important, or else Storybook will not load. The one story can be a component, for example, which would work like a title for the application, or any other introduction to your Storybook you see fit.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, omit the `--directory` flag. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 So, let’s use React for the Storybook Composition host library:
 
 ```shell
-nx g @nx/react:lib storybook-host
+nx g @nx/react:lib storybook-host --directory=libs/storybook-host
 ```
 
 Now that your library is generated, you can write your intro in the generated component (you can also do this later, it does not matter).
diff --git a/docs/shared/reference/nx-json.md b/docs/shared/reference/nx-json.md
index 2a80e37232..c0356b0437 100644
--- a/docs/shared/reference/nx-json.md
+++ b/docs/shared/reference/nx-json.md
@@ -11,8 +11,7 @@ The following is an expanded example showing all options. Your `nx.json` will li
     "defaultBase": "main"
   },
   "workspaceLayout": {
-    "appsDir": "demos",
-    "libsDir": "packages"
+    "projectNameAndRootFormat": "as-provided"
   },
   "generators": {
     "@nx/js:library": {
@@ -64,11 +63,29 @@ Tells Nx which branch and HEAD to use when calculating affected projects.
 
 ### Workspace Layout
 
-You can add a `workspaceLayout` property to modify where libraries and apps are located.
+You can add a `workspaceLayout` property to modify where libraries and apps are located. As of Nx 16.8.0, there is a property called `projectNameAndRootFormat` that determines how this configuration block is interpreted. The default setting is `"projectNameAndRootFormat": "as-provided"`.
 
 ```json
 {
   "workspaceLayout": {
+    "projectNameAndRootFormat": "as-provided"
+  }
+}
+```
+
+This setting makes app or lib generators behave in the following way:
+
+- `nx g app my-app` creates a new application named `my-app` in the `/my-app` folder
+- `nx g lib my-lib` creates a new library named `my-lib` in the `/my-lib` folder
+- `nx g app my-app --directory=apps/nested/my-app` creates a new application named `my-app` in the `/apps/nested/my-app` folder
+- `nx g lib my-lib --directory=libs/shared/ui/my-lib` creates a new library named `my-lib` in the `/libs/shared/ui/my-lib` folder
+
+The other style is `"projectNameAndRootFormat": "derived"`, which behaves the way Nx did before version 16.8.0.
+
+```json
+{
+  "workspaceLayout": {
+    "projectNameAndRootFormat": "derived",
     "appsDir": "demos",
     "libsDir": "packages"
   }
@@ -78,6 +95,15 @@ You can add a `workspaceLayout` property to modify where libraries and apps are
 These settings would store apps in `/demos/` and libraries in `/packages/`. The paths specified are relative to the
 workspace root.
 
+This makes app or lib generators behave in the following way:
+
+- `nx g app my-app` creates a new application named `my-app` in the `/demos/my-app` folder
+- `nx g lib my-lib` creates a new library named `my-lib` in the `/packages/my-lib` folder
+- `nx g app my-app --directory=nested` creates a new application named `nested-my-app` in the `/demos/nested/my-app` folder
+- `nx g lib my-lib --directory=shared/ui` creates a new library named `shared-ui-my-lib` in the `/packages/shared/ui/my-lib` folder
+
+If you accidentally generate a project in the wrong folder, use the [move generator](/packages/workspace/generators/move) to move it to the correct location.
+
 ### inputs & namedInputs
 
 Named inputs defined in `nx.json` are merged with the named inputs defined in each project's project.json.
diff --git a/packages/angular/docs/application-examples.md b/packages/angular/docs/application-examples.md
index c5a4fc34fa..ba912e4bd3 100644
--- a/packages/angular/docs/application-examples.md
+++ b/packages/angular/docs/application-examples.md
@@ -15,8 +15,12 @@ nx g @nx/angular:application my-app
 
 Create an application named `my-app` in the `my-dir` directory and use `scss` for styles:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=my-dir`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```bash
-nx g @nx/angular:app my-app --directory=my-dir --style=scss
+nx g @nx/angular:app my-app --directory=my-dir/my-app --style=scss
 ```
 
 {% /tab %}
diff --git a/packages/angular/docs/library-examples.md b/packages/angular/docs/library-examples.md
index f6d1637723..20cf465cfb 100644
--- a/packages/angular/docs/library-examples.md
+++ b/packages/angular/docs/library-examples.md
@@ -34,8 +34,12 @@ nx g @nx/angular:library my-lib --buildable
 {% tab label="Nested Folder & Import"%}
 Creates the `my-lib` library in the `nested` directory and sets the import path to `@myorg/nested/my-lib`:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=nested`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```bash
-nx g @nx/angular:library --directory=nested --importPath=@myorg/nested/my-lib my-lib
+nx g @nx/angular:library --directory=libs/nested/my-lib --importPath=@myorg/nested/my-lib my-lib
 ```
 
 {% /tab %}
diff --git a/packages/js/docs/library-examples.md b/packages/js/docs/library-examples.md
index e8da2be146..d6d478b915 100644
--- a/packages/js/docs/library-examples.md
+++ b/packages/js/docs/library-examples.md
@@ -117,8 +117,12 @@ npx nx g lib mylib --publishable
 
 Generate a library named `mylib` and put it under a directory named `myapp` (`libs/myapp/mylib`)
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=myapp`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-npx nx g lib mylib --directory=myapp
+npx nx g lib mylib --directory=libs/myapp/mylib
 ```
 
 {% /tab %}
diff --git a/packages/next/docs/application-examples.md b/packages/next/docs/application-examples.md
index 052bff9075..0b00b8f99d 100644
--- a/packages/next/docs/application-examples.md
+++ b/packages/next/docs/application-examples.md
@@ -3,8 +3,12 @@
 {% tabs %}
 {% tab label="Create app in a directory" %}
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=nested`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g app myapp --directory
+nx g app myapp --directory=apps/nested/myapp
 ```
 
 {% /tab %}
diff --git a/packages/next/docs/library-examples.md b/packages/next/docs/library-examples.md
index 328034e468..1aeb15c002 100644
--- a/packages/next/docs/library-examples.md
+++ b/packages/next/docs/library-examples.md
@@ -12,8 +12,12 @@ nx g lib my-lib
 
 The following will create a library at `libs/shared/my-lib`.
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=shared`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```shell
-nx g lib my-lib --directory=shared
+nx g lib my-lib --directory=libs/shared/my-lib
 ```
 
 {% /tab %}
diff --git a/packages/react/docs/application-examples.md b/packages/react/docs/application-examples.md
index 249dae784f..e04cc4ffb0 100644
--- a/packages/react/docs/application-examples.md
+++ b/packages/react/docs/application-examples.md
@@ -25,8 +25,12 @@ nx g @nx/react:app my-app --bundler=vite
 
 Create an application named `my-app` in the `my-dir` directory and use `scss` for styles:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=my-dir`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```bash
-nx g @nx/react:app my-app --directory=my-dir --style=scss
+nx g @nx/react:app my-app --directory=apps/my-dir/my-app --style=scss
 ```
 
 {% /tab %}
diff --git a/packages/web/docs/application-examples.md b/packages/web/docs/application-examples.md
index 5e8af3de91..753cd0e44d 100644
--- a/packages/web/docs/application-examples.md
+++ b/packages/web/docs/application-examples.md
@@ -25,8 +25,12 @@ nx g @nx/web:app my-app --bundler=vite
 
 Create an application named `my-app` in the `my-dir` directory:
 
+{% callout type="note" title="Directory Flag Behavior Changes" %}
+The command below uses the `as-provided` directory flag behavior, which is the default in Nx 16.8.0. If you're on an earlier version of Nx or using the `derived` option, use `--directory=my-dir`. See the [workspace layout documentation](/reference/nx-json#workspace-layout) for more details.
+{% /callout %}
+
 ```bash
-nx g @nx/web:app my-app --directory=my-dir
+nx g @nx/web:app my-app --directory=apps/my-dir/my-app
 ```
 
 {% /tab %}