@nx/devkit 23.1.0-beta.4 → 23.1.0-beta.5

package/dist/internal.d.ts

@@ -7,7 +7,7 @@ export { migrateProjectExecutorsToPlugin, migrateProjectExecutorsToPluginV1, NoT
 export { processTargetOutputs, deleteMatchingProperties, toProjectRelativePath, } from './src/generators/plugin-migrations/plugin-migration-utils';
 export { determineProjectNameAndRootOptions, ensureRootProjectName, resolveImportPath, } from './src/generators/project-name-and-root-utils';
 export { promptWhenInteractive } from './src/generators/prompt';
-export { addBuildTargetDefaults, addE2eCiTargetDefaults, } from './src/generators/target-defaults-utils';
+export { addBuildTargetDefaults, addE2eCiTargetDefaults, findTargetDefault, readTargetDefaultsForTarget, updateTargetDefault, upsertTargetDefault, } from './src/generators/target-defaults-utils';
 export { addPlugin } from './src/utils/add-plugin';
 export { getDeclaredPackageVersion, getInstalledPackageVersion, } from './src/utils/installed-version';
 export { assertSupportedInstalledPackageVersion, assertSupportedPackageVersion, } from './src/utils/version-floor';

package/dist/internal.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.dasherize = exports.classify = exports.capitalize = exports.camelize = exports.checkAndCleanWithSemver = exports.eachValueFrom = exports.logShowProjectCommand = exports.getNamedInputs = exports.findPluginForConfigFile = exports.clearRequireCache = exports.loadConfigFile = exports.getCatalogManager = exports.calculateHashesForCreateNodes = exports.calculateHashForCreateNodes = exports.mapAsyncIterable = exports.combineAsyncIterables = exports.createAsyncIterable = exports.assertSupportedPackageVersion = exports.assertSupportedInstalledPackageVersion = exports.getInstalledPackageVersion = exports.getDeclaredPackageVersion = exports.addPlugin = exports.addE2eCiTargetDefaults = exports.addBuildTargetDefaults = exports.promptWhenInteractive = exports.resolveImportPath = exports.ensureRootProjectName = exports.determineProjectNameAndRootOptions = exports.toProjectRelativePath = exports.deleteMatchingProperties = exports.processTargetOutputs = exports.NoTargetsToMigrateError = exports.migrateProjectExecutorsToPluginV1 = exports.migrateProjectExecutorsToPlugin = exports.AggregatedLog = exports.forEachExecutorOptions = exports.getE2EWebServerInfo = exports.getRelativeCwd = exports.determineArtifactNameAndDirectoryOptions = exports.PromptResolutionError = exports.resolvePrompt = exports.SchemaResolutionError = exports.ImplementationResolutionError = exports.resolveSchema = exports.resolveImplementation = exports.emitPluginWorkerLog = exports.safeWriteFileCache = exports.PluginCache = exports.createProjectRootMappingsFromProjectConfigurations = exports.signalToCode = void 0;
+exports.checkAndCleanWithSemver = exports.eachValueFrom = exports.logShowProjectCommand = exports.getNamedInputs = exports.findPluginForConfigFile = exports.clearRequireCache = exports.loadConfigFile = exports.getCatalogManager = exports.calculateHashesForCreateNodes = exports.calculateHashForCreateNodes = exports.mapAsyncIterable = exports.combineAsyncIterables = exports.createAsyncIterable = exports.assertSupportedPackageVersion = exports.assertSupportedInstalledPackageVersion = exports.getInstalledPackageVersion = exports.getDeclaredPackageVersion = exports.addPlugin = exports.upsertTargetDefault = exports.updateTargetDefault = exports.readTargetDefaultsForTarget = exports.findTargetDefault = exports.addE2eCiTargetDefaults = exports.addBuildTargetDefaults = exports.promptWhenInteractive = exports.resolveImportPath = exports.ensureRootProjectName = exports.determineProjectNameAndRootOptions = exports.toProjectRelativePath = exports.deleteMatchingProperties = exports.processTargetOutputs = exports.NoTargetsToMigrateError = exports.migrateProjectExecutorsToPluginV1 = exports.migrateProjectExecutorsToPlugin = exports.AggregatedLog = exports.forEachExecutorOptions = exports.getE2EWebServerInfo = exports.getRelativeCwd = exports.determineArtifactNameAndDirectoryOptions = exports.PromptResolutionError = exports.resolvePrompt = exports.SchemaResolutionError = exports.ImplementationResolutionError = exports.resolveSchema = exports.resolveImplementation = exports.emitPluginWorkerLog = exports.safeWriteFileCache = exports.PluginCache = exports.createProjectRootMappingsFromProjectConfigurations = exports.signalToCode = void 0;
+exports.dasherize = exports.classify = exports.capitalize = exports.camelize = void 0;
 var devkit_internals_1 = require("nx/src/devkit-internals");
 Object.defineProperty(exports, "signalToCode", { enumerable: true, get: function () { return devkit_internals_1.signalToCode; } });
 Object.defineProperty(exports, "createProjectRootMappingsFromProjectConfigurations", { enumerable: true, get: function () { return devkit_internals_1.createProjectRootMappingsFromProjectConfigurations; } });
@@ -40,6 +41,10 @@ Object.defineProperty(exports, "promptWhenInteractive", { enumerable: true, get:
 var target_defaults_utils_1 = require("./src/generators/target-defaults-utils");
 Object.defineProperty(exports, "addBuildTargetDefaults", { enumerable: true, get: function () { return target_defaults_utils_1.addBuildTargetDefaults; } });
 Object.defineProperty(exports, "addE2eCiTargetDefaults", { enumerable: true, get: function () { return target_defaults_utils_1.addE2eCiTargetDefaults; } });
+Object.defineProperty(exports, "findTargetDefault", { enumerable: true, get: function () { return target_defaults_utils_1.findTargetDefault; } });
+Object.defineProperty(exports, "readTargetDefaultsForTarget", { enumerable: true, get: function () { return target_defaults_utils_1.readTargetDefaultsForTarget; } });
+Object.defineProperty(exports, "updateTargetDefault", { enumerable: true, get: function () { return target_defaults_utils_1.updateTargetDefault; } });
+Object.defineProperty(exports, "upsertTargetDefault", { enumerable: true, get: function () { return target_defaults_utils_1.upsertTargetDefault; } });
 // Utils
 var add_plugin_1 = require("./src/utils/add-plugin");
 Object.defineProperty(exports, "addPlugin", { enumerable: true, get: function () { return add_plugin_1.addPlugin; } });

package/dist/src/generators/e2e-web-server-info-utils.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getE2EWebServerInfo = getE2EWebServerInfo;
 const devkit_exports_1 = require("nx/src/devkit-exports");
+const target_defaults_utils_1 = require("./target-defaults-utils");
 const find_plugin_for_config_file_1 = require("../utils/find-plugin-for-config-file");
 async function getE2EWebServerInfo(tree, projectName, pluginOptions, defaultValues, isPluginBeingAdded) {
     const pm = (0, devkit_exports_1.getPackageManagerCommand)((0, devkit_exports_1.detectPackageManager)(tree.root));
@@ -33,23 +34,18 @@ async function getE2EWebServerInfoForPlugin(tree, projectName, pluginOptions, de
     }
     const nxJson = (0, devkit_exports_1.readNxJson)(tree);
     let e2ePort = defaultValues.defaultE2EPort ?? 4200;
-    if (nxJson.targetDefaults?.[foundPlugin.options[pluginOptions.serveTargetName] ??
-        defaultValues.defaultServeTargetName] &&
-        nxJson.targetDefaults?.[foundPlugin.options[pluginOptions.serveTargetName] ??
-            defaultValues.defaultServeTargetName].options?.port) {
-        e2ePort =
-            nxJson.targetDefaults?.[foundPlugin.options[pluginOptions.serveTargetName] ??
-                defaultValues.defaultServeTargetName].options?.port;
-    }
+    const serveTargetName = foundPlugin.options[pluginOptions.serveTargetName] ??
+        defaultValues.defaultServeTargetName;
+    e2ePort =
+        (0, target_defaults_utils_1.readTargetDefaultsForTarget)(serveTargetName, nxJson.targetDefaults)?.options
+            ?.port ?? e2ePort;
     const e2eWebServerAddress = defaultValues.defaultE2EWebServerAddress.replace(/:\d+/, `:${e2ePort}`);
     return {
         e2eWebServerAddress,
-        e2eWebServerCommand: `${pm.exec} nx run ${projectName}:${foundPlugin.options[pluginOptions.serveTargetName] ??
-            defaultValues.defaultServeTargetName}`,
+        e2eWebServerCommand: `${pm.exec} nx run ${projectName}:${serveTargetName}`,
         e2eCiWebServerCommand: `${pm.exec} nx run ${projectName}:${foundPlugin.options[pluginOptions.serveStaticTargetName] ??
             defaultValues.defaultServeStaticTargetName}`,
         e2eCiBaseUrl: defaultValues.defaultE2ECiBaseUrl,
-        e2eDevServerTarget: `${projectName}:${foundPlugin.options[pluginOptions.serveTargetName] ??
-            defaultValues.defaultServeTargetName}`,
+        e2eDevServerTarget: `${projectName}:${serveTargetName}`,
     };
 }

package/dist/src/generators/plugin-migrations/executor-to-plugin-migrator.d.ts

@@ -1,5 +1,5 @@
 import type { ProjectConfiguration } from 'nx/src/config/workspace-json-project-json';
-import { type CreateNodes, type ProjectGraph, type TargetConfiguration, type Tree } from 'nx/src/devkit-exports';
+import { type CreateNodes, type NxJsonConfiguration, type ProjectGraph, type TargetConfiguration, type Tree } from 'nx/src/devkit-exports';
 import { logger as devkitLogger } from 'nx/src/devkit-exports';
 export type InferredTargetConfiguration = TargetConfiguration & {
     name: string;
@@ -13,6 +13,7 @@ type SkipProjectFilter = (projectConfiguration: ProjectConfiguration) => false |
 export declare class NoTargetsToMigrateError extends Error {
     constructor();
 }
+export declare function readTargetDefaultsForExecutor(executor: string, targetDefaults: NxJsonConfiguration['targetDefaults'] | undefined): Partial<TargetConfiguration> | undefined;
 export declare function migrateProjectExecutorsToPlugin<T>(tree: Tree, projectGraph: ProjectGraph, pluginPath: string, createNodesV2: CreateNodes<T>, defaultPluginOptions: T, migrations: Array<{
     executors: string[];
     targetPluginOptionMapper: (targetName: string) => Partial<T>;

package/dist/src/generators/plugin-migrations/executor-to-plugin-migrator.js

@@ -2,6 +2,7 @@
 var _ExecutorToPluginMigrator_instances, _ExecutorToPluginMigrator_projectGraph, _ExecutorToPluginMigrator_executor, _ExecutorToPluginMigrator_pluginPath, _ExecutorToPluginMigrator_pluginOptionsBuilder, _ExecutorToPluginMigrator_postTargetTransformer, _ExecutorToPluginMigrator_skipTargetFilter, _ExecutorToPluginMigrator_skipProjectFilter, _ExecutorToPluginMigrator_specificProjectToMigrate, _ExecutorToPluginMigrator_logger, _ExecutorToPluginMigrator_nxJson, _ExecutorToPluginMigrator_targetDefaultsForExecutor, _ExecutorToPluginMigrator_targetAndProjectsToMigrate, _ExecutorToPluginMigrator_createNodes, _ExecutorToPluginMigrator_createNodesV2, _ExecutorToPluginMigrator_createNodesResultsForTargets, _ExecutorToPluginMigrator_skippedProjects, _ExecutorToPluginMigrator_init, _ExecutorToPluginMigrator_migrateTarget, _ExecutorToPluginMigrator_migrateProject, _ExecutorToPluginMigrator_mergeInputs, _ExecutorToPluginMigrator_getTargetAndProjectsToMigrate, _ExecutorToPluginMigrator_getTargetDefaultsForExecutor, _ExecutorToPluginMigrator_getCreatedTargetForProjectRoot, _ExecutorToPluginMigrator_getCreateNodesResults;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NoTargetsToMigrateError = void 0;
+exports.readTargetDefaultsForExecutor = readTargetDefaultsForExecutor;
 exports.migrateProjectExecutorsToPlugin = migrateProjectExecutorsToPlugin;
 exports.migrateProjectExecutorsToPluginV1 = migrateProjectExecutorsToPluginV1;
 const tslib_1 = require("tslib");
@@ -11,6 +12,7 @@ const posix_1 = require("node:path/posix");
 const devkit_exports_1 = require("nx/src/devkit-exports");
 const devkit_internals_1 = require("nx/src/devkit-internals");
 const executor_options_utils_1 = require("../executor-options-utils");
+const target_defaults_utils_1 = require("../target-defaults-utils");
 const plugin_migration_utils_1 = require("./plugin-migration-utils");
 const devkit_exports_2 = require("nx/src/devkit-exports");
 class ExecutorToPluginMigrator {
@@ -169,7 +171,7 @@ _ExecutorToPluginMigrator_projectGraph = new WeakMap(), _ExecutorToPluginMigrato
         }
     });
 }, _ExecutorToPluginMigrator_getTargetDefaultsForExecutor = function _ExecutorToPluginMigrator_getTargetDefaultsForExecutor() {
-    tslib_1.__classPrivateFieldSet(this, _ExecutorToPluginMigrator_targetDefaultsForExecutor, structuredClone(tslib_1.__classPrivateFieldGet(this, _ExecutorToPluginMigrator_nxJson, "f").targetDefaults?.[tslib_1.__classPrivateFieldGet(this, _ExecutorToPluginMigrator_executor, "f")]), "f");
+    tslib_1.__classPrivateFieldSet(this, _ExecutorToPluginMigrator_targetDefaultsForExecutor, structuredClone(readTargetDefaultsForExecutor(tslib_1.__classPrivateFieldGet(this, _ExecutorToPluginMigrator_executor, "f"), tslib_1.__classPrivateFieldGet(this, _ExecutorToPluginMigrator_nxJson, "f").targetDefaults) ?? {}), "f");
 }, _ExecutorToPluginMigrator_getCreatedTargetForProjectRoot = function _ExecutorToPluginMigrator_getCreatedTargetForProjectRoot(targetName, projectRoot) {
     const entry = Object.entries(tslib_1.__classPrivateFieldGet(this, _ExecutorToPluginMigrator_createNodesResultsForTargets, "f").get(targetName)?.projects ?? {}).find(([root]) => root === projectRoot);
     if (!entry) {
@@ -204,6 +206,22 @@ class NoTargetsToMigrateError extends Error {
     }
 }
 exports.NoTargetsToMigrateError = NoTargetsToMigrateError;
+function readTargetDefaultsForExecutor(executor, targetDefaults) {
+    // Preserve the legacy record-shape semantics this migrator used before
+    // array support: only an unfiltered default keyed directly by executor
+    // applies here. Target-scoped or filtered array entries remain opt-in
+    // behaviors for callers that can evaluate them in project context.
+    const entry = (0, target_defaults_utils_1.findTargetDefault)(targetDefaults, { executor });
+    if (!entry) {
+        return undefined;
+    }
+    const config = { ...entry };
+    delete config.target;
+    delete config.executor;
+    delete config.projects;
+    delete config.plugin;
+    return config;
+}
 async function migrateProjectExecutorsToPlugin(tree, projectGraph, pluginPath, createNodesV2, defaultPluginOptions, migrations, specificProjectToMigrate, logger) {
     const projects = await migrateProjects(tree, projectGraph, pluginPath, undefined, createNodesV2, defaultPluginOptions, migrations, specificProjectToMigrate, logger);
     return projects;

package/dist/src/generators/target-defaults-utils.d.ts

@@ -1,3 +1,120 @@
-import { type TargetConfiguration, type Tree } from 'nx/src/devkit-exports';
+import { type NxJsonConfiguration, type TargetConfiguration, type TargetDefaultEntry, type TargetDefaultFilter, type TargetDefaults, type Tree } from 'nx/src/devkit-exports';
+import { readTargetDefaultsForTarget as readTargetDefaultsForTargetFromNx } from 'nx/src/devkit-internals';
+/**
+ * Upsert a `targetDefaults` entry on the provided `nxJson`. Mutates
+ * `nxJson` in place and returns it so the caller can chain or batch
+ * other edits before persisting via `updateNxJson` exactly once.
+ *
+ * The input is the logical {@link TargetDefaultEntry} shape
+ * (`{ target?, executor?, projects?, plugin?, ...config }`). The `projects` /
+ * `plugin` filter is *context* describing what the caller is configuring, used
+ * to pick which existing entry to merge into — it is never authored as a new
+ * filtered entry. For the key (`target` ?? `executor`):
+ *
+ * - No value yet → create the generic (plain object) value.
+ * - Only a generic value → merge into it.
+ * - A filtered entry matching the context filter exists → merge into that one
+ *   (so a caller updating a project the user already scoped a default for edits
+ *   that scoped entry rather than clobbering the workspace baseline).
+ * - Otherwise → merge into the generic, creating one if needed.
+ *
+ * A lone unfiltered entry is always stored as a plain object, never a
+ * single-element array. The entry must set at least one of `target` /
+ * `executor`.
+ */
+export declare function upsertTargetDefault(tree: Tree, nxJson: NxJsonConfiguration, options: TargetDefaultEntry): NxJsonConfiguration;
+/**
+ * Find a `targetDefaults` entry by its logical locator tuple
+ * `(target, executor, projects, plugin)`. Locator keys default to
+ * `undefined`, matching only entries that also leave them unset — same
+ * semantics as `upsertTargetDefault`.
+ *
+ * Throws when called with an empty locator (no `target`, `executor`,
+ * `projects`, or `plugin`). An empty locator is almost always a bug — the
+ * caller intended to find a specific entry but forgot to populate the lookup.
+ */
+export declare function findTargetDefault(targetDefaults: TargetDefaults | undefined, locator: Pick<TargetDefaultEntry, 'target' | 'executor' | 'projects' | 'plugin'>): TargetDefaultEntry | undefined;
+/**
+ * The subset of a project graph node that the `projects` narrowing reads —
+ * names come from the map keys, `root`/`tags` drive `findMatchingProjects`.
+ * Mirrors `MatcherProjectNode` without importing it, so the signature stays
+ * stable across the supported nx version range.
+ */
+type ContextProjectNode = {
+    data: {
+        root: string;
+        tags?: string[];
+    };
+};
+/**
+ * What the caller is updating, used to pick which `targetDefaults` entries the
+ * callback runs against. At least one of `executor` / `projects` is required.
+ */
+export interface UpdateTargetDefaultContext {
+    /**
+     * Visit only entries that resolve to this executor — matched against the map
+     * key (executor-keyed form), an entry's `executor` field, or its
+     * `filter.executor`. When omitted, entries are not filtered by executor.
+     */
+    executor?: string;
+    /**
+     * Project nodes the update is scoped to, keyed by project name. When set, a
+     * project-filtered entry is visited only if its `filter.projects` covers
+     * *every* one of these projects; unfiltered entries always match. When
+     * omitted, project filters are not a constraint and every (executor-matching)
+     * entry is visited — the workspace-wide case.
+     */
+    projects?: Record<string, ContextProjectNode>;
+}
+/**
+ * Describes the entry a callback invocation is operating on, so the callback
+ * can tell the executor-keyed form from the target-keyed form and read the
+ * entry's filter.
+ */
+export interface UpdateTargetDefaultEntryInfo {
+    /** The `targetDefaults` map key the entry lives under. */
+    key: string;
+    /** Logical target name — `undefined` for executor-keyed entries. */
+    target?: string;
+    /** Executor the entry resolves to (from the key, `executor` field, or filter). */
+    executor?: string;
+    /** The entry's filter, present only for filtered array entries. */
+    filter?: TargetDefaultFilter;
+}
+/**
+ * Called once per matching entry. Receives the entry's flat config (everything
+ * but `filter`) and may mutate it in place. Return a new config to replace the
+ * entry's payload, return `null` to drop the entry, or return nothing to keep
+ * the (possibly mutated) config.
+ */
+export type UpdateTargetDefaultCallback = (config: Partial<TargetConfiguration>, info: UpdateTargetDefaultEntryInfo) => Partial<TargetConfiguration> | null | void;
+/**
+ * Walk the `targetDefaults` entries matching `context` and run `callback`
+ * against each, mutating `nxJson` in place and returning it. This is the
+ * read-modify-write counterpart to {@link upsertTargetDefault}, meant for
+ * generators and migrations that need to edit *existing* defaults across both
+ * value forms (plain object and filtered array) without re-implementing the
+ * normalize → edit → collapse dance by hand.
+ *
+ * Matching, per the `context`:
+ * - `executor` selects entries that reference it as the map key, an `executor`
+ *   config field, or `filter.executor`.
+ * - `projects` narrows to entries whose `filter.projects` covers the scoped
+ *   projects (unfiltered entries always match). With no `projects` context,
+ *   project filters are ignored and every executor-matching entry is visited.
+ *
+ * Removal and collapsing follow the storage-form rules:
+ * - Array entry whose callback returns `null` → dropped from the array.
+ * - An array that collapses to a single unfiltered entry → stored as the plain
+ *   object form; an emptied array → the whole key is deleted.
+ * - Object-form value whose callback returns `null` → the whole key is deleted.
+ * - An emptied `targetDefaults` map → removed from `nxJson` entirely.
+ *
+ * Throws when neither `executor` nor `projects` is provided — an empty context
+ * would match everything and is almost always a bug.
+ */
+export declare function updateTargetDefault(nxJson: NxJsonConfiguration, context: UpdateTargetDefaultContext, callback: UpdateTargetDefaultCallback): NxJsonConfiguration;
+export declare function readTargetDefaultsForTarget(targetName: string, targetDefaults: TargetDefaults | undefined, executor?: string, opts?: Parameters<typeof readTargetDefaultsForTargetFromNx>[3]): Partial<TargetConfiguration> | null;
 export declare function addBuildTargetDefaults(tree: Tree, executorName: string, buildTargetName?: string, extraInputs?: TargetConfiguration['inputs']): void;
 export declare function addE2eCiTargetDefaults(tree: Tree, e2ePlugin: string, buildTarget: string, pathToE2EConfigFile: string): Promise<void>;
+export {};

package/dist/src/generators/target-defaults-utils.js

@@ -1,14 +1,362 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.upsertTargetDefault = upsertTargetDefault;
+exports.findTargetDefault = findTargetDefault;
+exports.updateTargetDefault = updateTargetDefault;
+exports.readTargetDefaultsForTarget = readTargetDefaultsForTarget;
 exports.addBuildTargetDefaults = addBuildTargetDefaults;
 exports.addE2eCiTargetDefaults = addE2eCiTargetDefaults;
 const devkit_exports_1 = require("nx/src/devkit-exports");
 const devkit_internals_1 = require("nx/src/devkit-internals");
 const minimatch_1 = require("minimatch");
+/**
+ * Upsert a `targetDefaults` entry on the provided `nxJson`. Mutates
+ * `nxJson` in place and returns it so the caller can chain or batch
+ * other edits before persisting via `updateNxJson` exactly once.
+ *
+ * The input is the logical {@link TargetDefaultEntry} shape
+ * (`{ target?, executor?, projects?, plugin?, ...config }`). The `projects` /
+ * `plugin` filter is *context* describing what the caller is configuring, used
+ * to pick which existing entry to merge into — it is never authored as a new
+ * filtered entry. For the key (`target` ?? `executor`):
+ *
+ * - No value yet → create the generic (plain object) value.
+ * - Only a generic value → merge into it.
+ * - A filtered entry matching the context filter exists → merge into that one
+ *   (so a caller updating a project the user already scoped a default for edits
+ *   that scoped entry rather than clobbering the workspace baseline).
+ * - Otherwise → merge into the generic, creating one if needed.
+ *
+ * A lone unfiltered entry is always stored as a plain object, never a
+ * single-element array. The entry must set at least one of `target` /
+ * `executor`.
+ */
+function upsertTargetDefault(tree, nxJson, options) {
+    const { target, executor, projects, plugin, ...config } = options;
+    const key = target ?? executor;
+    if (key === undefined) {
+        throw new Error('upsertTargetDefault requires at least one of `target` or `executor` to be set.');
+    }
+    // `executor` is the map key itself when no `target` is given; when a `target`
+    // is present it is a configuration field (a default executor) written onto
+    // the value.
+    const valueConfig = target !== undefined && executor !== undefined
+        ? { executor, ...config }
+        : config;
+    const targetDefaults = (nxJson.targetDefaults ??= {});
+    targetDefaults[key] = collapse(upsertValue(targetDefaults[key], valueConfig, {
+        tree,
+        projects,
+        plugin,
+        executor,
+    }));
+    return nxJson;
+}
+/**
+ * Merge `config` into the right entry of a key's value, per the algorithm
+ * documented on {@link upsertTargetDefault}. Returns the new value (always an
+ * array here; {@link collapse} downgrades a lone unfiltered one to an object).
+ */
+function upsertValue(existing, config, context) {
+    // No value yet → create the generic.
+    if (existing === undefined) {
+        return { ...config };
+    }
+    const entries = Array.isArray(existing)
+        ? [...existing]
+        : [existing];
+    // A filtered entry that covers what's being configured → merge into it,
+    // preserving its filter.
+    const matchIdx = entries.findIndex((e) => e.filter !== undefined && filterCoversContext(e.filter, context));
+    if (matchIdx >= 0) {
+        entries[matchIdx] = { ...entries[matchIdx], ...config };
+        return entries;
+    }
+    // Otherwise merge into the generic (catch-all) entry, creating one if absent.
+    const genericIdx = entries.findIndex((e) => e.filter === undefined);
+    if (genericIdx >= 0) {
+        const { filter: _filter, ...rest } = entries[genericIdx];
+        entries[genericIdx] = { ...rest, ...config };
+    }
+    else {
+        entries.push({ ...config });
+    }
+    return entries;
+}
+/**
+ * Whether an entry's `filter` applies to what the caller is configuring:
+ * `plugin` / `executor` must match exactly, and `projects` is evaluated as
+ * *coverage* — every configured project must match the filter's patterns
+ * (names, globs, `tag:`, directories, negation) via `findMatchingProjects`,
+ * resolved against each project's tags/root in the tree. A `projects` filter
+ * can't be confirmed when no project context is supplied (or the project
+ * isn't in the tree), so it falls through to the generic.
+ */
+function filterCoversContext(filter, context) {
+    if (filter.plugin !== undefined && filter.plugin !== context.plugin) {
+        return false;
+    }
+    if (filter.executor !== undefined && filter.executor !== context.executor) {
+        return false;
+    }
+    if (filter.projects !== undefined) {
+        const configured = context.projects ?? [];
+        const nodes = contextProjectNodes(context.tree, configured);
+        if (!projectsFilterCovers(filter.projects, nodes, configured)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Whether a `filter.projects` pattern set covers *every* required project name:
+ * each must be returned by `findMatchingProjects` against `nodes`. An empty
+ * `requiredNames` can never be "covered", so the entry falls through to the
+ * generic baseline. Shared by the upsert and update paths so the coverage
+ * semantics live in one place.
+ */
+function projectsFilterCovers(patterns, nodes, requiredNames) {
+    if (requiredNames.length === 0) {
+        return false;
+    }
+    const matched = (0, devkit_internals_1.findMatchingProjects)([...patterns], nodes);
+    return requiredNames.every((name) => matched.includes(name));
+}
+function contextProjectNodes(tree, projectNames) {
+    const projects = (0, devkit_exports_1.getProjects)(tree);
+    const nodes = {};
+    for (const name of projectNames) {
+        const config = projects.get(name);
+        if (config) {
+            nodes[name] = { data: { root: config.root, tags: config.tags } };
+        }
+    }
+    return nodes;
+}
+/**
+ * Collapse a key's value back to the plain object form when it has degenerated
+ * to a single entry with no filter — at that point the array wrapper carries no
+ * information the object form doesn't, and the object form is the tidier,
+ * record-shape-compatible representation.
+ */
+function collapse(value) {
+    if (Array.isArray(value) &&
+        value.length === 1 &&
+        value[0].filter === undefined) {
+        // Drop the (already-undefined) `filter` key so the result matches the
+        // object value form, which forbids `filter`.
+        const { filter: _filter, ...config } = value[0];
+        return config;
+    }
+    return value;
+}
+/**
+ * Find a `targetDefaults` entry by its logical locator tuple
+ * `(target, executor, projects, plugin)`. Locator keys default to
+ * `undefined`, matching only entries that also leave them unset — same
+ * semantics as `upsertTargetDefault`.
+ *
+ * Throws when called with an empty locator (no `target`, `executor`,
+ * `projects`, or `plugin`). An empty locator is almost always a bug — the
+ * caller intended to find a specific entry but forgot to populate the lookup.
+ */
+function findTargetDefault(targetDefaults, locator) {
+    if (locator.target === undefined &&
+        locator.executor === undefined &&
+        locator.projects === undefined &&
+        locator.plugin === undefined) {
+        throw new Error('findTargetDefault requires at least one of `target`, `executor`, `projects`, or `plugin` on the locator.');
+    }
+    for (const entry of logicalTargetDefaultEntries(targetDefaults)) {
+        if (entry.target === locator.target &&
+            entry.executor === locator.executor &&
+            projectsEqual(entry.projects, locator.projects) &&
+            entry.plugin === locator.plugin) {
+            return entry;
+        }
+    }
+    return undefined;
+}
+/**
+ * Expand the nested `targetDefaults` map into its logical {@link
+ * TargetDefaultEntry} view, one entry at a time. The key becomes `target` (or
+ * `executor` for executor-shaped keys) and any `filter` is un-nested into the
+ * flat `projects`/`plugin`/`executor` siblings. Lazy so callers that find a
+ * match early stop iterating. Internal to this module — the flat shape is a
+ * lookup convenience, never a `targetDefaults` value form.
+ */
+function* logicalTargetDefaultEntries(targetDefaults) {
+    for (const key of Object.keys(targetDefaults ?? {})) {
+        const locator = isExecutorLikeKey(key)
+            ? { executor: key }
+            : { target: key };
+        const value = targetDefaults[key];
+        const entries = Array.isArray(value)
+            ? value
+            : [value ?? {}];
+        for (const entry of entries) {
+            const { filter, ...config } = entry;
+            yield {
+                ...locator,
+                ...(filter?.projects !== undefined
+                    ? { projects: filter.projects }
+                    : {}),
+                ...(filter?.plugin !== undefined ? { plugin: filter.plugin } : {}),
+                ...(filter?.executor !== undefined
+                    ? { executor: filter.executor }
+                    : {}),
+                ...config,
+            };
+        }
+    }
+}
+// Mirrors `isGlobPattern` from `nx/src/utils/globs.ts`, which isn't on the
+// devkit-exports surface guaranteed across the supported nx version range.
+//
+// Known limitation: a `:` is also legal in a target name, so a target literally
+// named e.g. `e2e:ci` is classified as an executor key here. This matches how
+// the rest of the target-defaults stack disambiguates keys (executor-shaped
+// keys win), and such target names are vanishingly rare — accepted rather than
+// worked around.
+const GLOB_CHARACTERS = new Set(['*', '|', '{', '}', '(', ')', '[']);
+function isExecutorLikeKey(key) {
+    if (!key.includes(':'))
+        return false;
+    for (const c of key)
+        if (GLOB_CHARACTERS.has(c))
+            return false;
+    return true;
+}
+/**
+ * Walk the `targetDefaults` entries matching `context` and run `callback`
+ * against each, mutating `nxJson` in place and returning it. This is the
+ * read-modify-write counterpart to {@link upsertTargetDefault}, meant for
+ * generators and migrations that need to edit *existing* defaults across both
+ * value forms (plain object and filtered array) without re-implementing the
+ * normalize → edit → collapse dance by hand.
+ *
+ * Matching, per the `context`:
+ * - `executor` selects entries that reference it as the map key, an `executor`
+ *   config field, or `filter.executor`.
+ * - `projects` narrows to entries whose `filter.projects` covers the scoped
+ *   projects (unfiltered entries always match). With no `projects` context,
+ *   project filters are ignored and every executor-matching entry is visited.
+ *
+ * Removal and collapsing follow the storage-form rules:
+ * - Array entry whose callback returns `null` → dropped from the array.
+ * - An array that collapses to a single unfiltered entry → stored as the plain
+ *   object form; an emptied array → the whole key is deleted.
+ * - Object-form value whose callback returns `null` → the whole key is deleted.
+ * - An emptied `targetDefaults` map → removed from `nxJson` entirely.
+ *
+ * Throws when neither `executor` nor `projects` is provided — an empty context
+ * would match everything and is almost always a bug.
+ */
+function updateTargetDefault(nxJson, context, callback) {
+    const { executor, projects } = context;
+    if (executor === undefined && projects === undefined) {
+        throw new Error('updateTargetDefault requires at least one of `executor` or `projects` on the context to locate entries to update.');
+    }
+    const targetDefaults = nxJson.targetDefaults;
+    if (!targetDefaults) {
+        return nxJson;
+    }
+    const projectNames = projects ? Object.keys(projects) : [];
+    for (const key of Object.keys(targetDefaults)) {
+        const value = targetDefaults[key];
+        const entries = Array.isArray(value)
+            ? value
+            : [value];
+        const kept = [];
+        for (const entry of entries) {
+            if (!entryMatchesContext(key, entry, executor, projects, projectNames)) {
+                kept.push(entry);
+                continue;
+            }
+            const { filter, ...config } = entry;
+            const result = callback(config, {
+                key,
+                target: isExecutorLikeKey(key) ? undefined : key,
+                executor: isExecutorLikeKey(key)
+                    ? key
+                    : (config.executor ?? filter?.executor),
+                filter,
+            });
+            // `null` drops the entry; anything else keeps the (mutated or replaced)
+            // config, re-attaching the filter so a filtered entry stays filtered.
+            if (result === null) {
+                continue;
+            }
+            const nextConfig = result ?? config;
+            kept.push(filter !== undefined ? { filter, ...nextConfig } : nextConfig);
+        }
+        if (kept.length === 0) {
+            delete targetDefaults[key];
+        }
+        else {
+            targetDefaults[key] = collapse(kept);
+        }
+    }
+    if (Object.keys(targetDefaults).length === 0) {
+        delete nxJson.targetDefaults;
+    }
+    return nxJson;
+}
+/**
+ * Whether `callback` should run against this entry: it must reference the
+ * context's `executor` (when given), and — when the context is scoped to
+ * `projects` — any `filter.projects` it carries must cover every scoped
+ * project. Unfiltered entries always pass the project check.
+ */
+function entryMatchesContext(key, entry, executor, projects, projectNames) {
+    if (executor !== undefined) {
+        const referencesExecutor = key === executor ||
+            entry.executor === executor ||
+            entry.filter?.executor === executor;
+        if (!referencesExecutor) {
+            return false;
+        }
+    }
+    if (projects !== undefined && entry.filter?.projects !== undefined) {
+        const patterns = Array.isArray(entry.filter.projects)
+            ? entry.filter.projects
+            : [entry.filter.projects];
+        if (!projectsFilterCovers(patterns, projects, projectNames)) {
+            return false;
+        }
+    }
+    return true;
+}
+function readTargetDefaultsForTarget(targetName, targetDefaults, executor, opts) {
+    // `targetDefaults` is the nested map; the nx reader resolves either the
+    // object or array value form for `targetName` natively.
+    return (0, devkit_internals_1.readTargetDefaultsForTarget)(targetName, targetDefaults, executor, opts);
+}
+// Order-insensitive equality so re-upserts with reordered patterns merge into
+// the same entry rather than appending a duplicate. Comparing sorted copies
+// keeps duplicates significant (`['a','a']` ≠ `['a']`) without special-casing.
+function projectsEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    if (a.length !== b.length)
+        return false;
+    const sortedA = [...a].sort();
+    const sortedB = [...b].sort();
+    return sortedA.every((value, i) => value === sortedB[i]);
+}
 function addBuildTargetDefaults(tree, executorName, buildTargetName = 'build', extraInputs = []) {
-    const nxJson = (0, devkit_exports_1.readNxJson)(tree);
-    nxJson.targetDefaults ??= {};
-    nxJson.targetDefaults[executorName] ??= {
+    const nxJson = (0, devkit_exports_1.readNxJson)(tree) ?? {};
+    // Only skip when an *unfiltered* entry already covers this executor.
+    // A filtered entry (`projects:` or `plugin:`) only applies to a subset
+    // of targets, so it doesn't satisfy the workspace-wide default this
+    // helper writes — we still need to add the unfiltered baseline.
+    if (findTargetDefault(nxJson.targetDefaults, { executor: executorName })) {
+        return;
+    }
+    upsertTargetDefault(tree, nxJson, {
+        executor: executorName,
         cache: true,
         dependsOn: [`^${buildTargetName}`],
         inputs: [
@@ -17,12 +365,12 @@ function addBuildTargetDefaults(tree, executorName, buildTargetName = 'build', e
                 : ['default', '^default']),
             ...extraInputs,
         ],
-    };
+    });
     (0, devkit_exports_1.updateNxJson)(tree, nxJson);
 }
 async function addE2eCiTargetDefaults(tree, e2ePlugin, buildTarget, pathToE2EConfigFile) {
     const nxJson = (0, devkit_exports_1.readNxJson)(tree);
-    if (!nxJson.plugins) {
+    if (!nxJson?.plugins) {
         return;
     }
     const e2ePluginRegistrations = nxJson.plugins.filter((p) => typeof p === 'string' ? p === e2ePlugin : p.plugin === e2ePlugin);
@@ -58,18 +406,13 @@ async function addE2eCiTargetDefaults(tree, e2ePlugin, buildTarget, pathToE2ECon
         ? 'e2e-ci'
         : (foundPluginForApplication.options?.ciTargetName ?? 'e2e-ci');
     const ciTargetNameGlob = `${ciTargetName}--**/**`;
-    nxJson.targetDefaults ??= {};
-    const e2eCiTargetDefaults = nxJson.targetDefaults[ciTargetNameGlob];
-    if (!e2eCiTargetDefaults) {
-        nxJson.targetDefaults[ciTargetNameGlob] = {
-            dependsOn: [buildTarget],
-        };
-    }
-    else {
-        e2eCiTargetDefaults.dependsOn ??= [];
-        if (!e2eCiTargetDefaults.dependsOn.includes(buildTarget)) {
-            e2eCiTargetDefaults.dependsOn.push(buildTarget);
-        }
+    const existing = findTargetDefault(nxJson.targetDefaults, {
+        target: ciTargetNameGlob,
+    });
+    const dependsOn = [...(existing?.dependsOn ?? [])];
+    if (!dependsOn.includes(buildTarget)) {
+        dependsOn.push(buildTarget);
     }
+    upsertTargetDefault(tree, nxJson, { target: ciTargetNameGlob, dependsOn });
     (0, devkit_exports_1.updateNxJson)(tree, nxJson);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nx/devkit",
-  "version": "23.1.0-beta.4",
+  "version": "23.1.0-beta.5",
   "private": false,
   "type": "commonjs",
   "files": [
@@ -60,7 +60,7 @@
   },
   "devDependencies": {
     "jest": "30.3.0",
-    "nx": "23.1.0-beta.4"
+    "nx": "23.1.0-beta.5"
   },
   "peerDependencies": {
     "nx": ">= 22 <= 24 || ^23.0.0-0"