deprecated-patterns.md
deprecated-patterns.mdBrowse 8 files
1,390 tokens
13,309 bytes
Token encoding: o200k_base
Snapshot 646e806
← Back to SKILL.md
Deprecated migration patterns
Two registries: patterns that exist only in git history (you will meet them when reading old migrations for reference, or in third-party plugins) and patterns still present in live code that must not be copied. When porting or referencing an old migration, rewrite it in the modern shape; never reproduce these.
Historical only (deleted from the repo)
| Pattern | Era | Recognition signature | Modern replacement |
|---|---|---|---|
| Angular Devkit schematic Rules | v6-11 | import { Rule, chain } from '@angular-devkit/schematics'; updateJsonInTree, readJsonInTree, createOrUpdate, insert with Change objects; formatFiles() appended as a Rule | Default-exported async function (tree: Tree) using @nx/devkit |
Top-level schematics section in migrations.json | through 2023 | Entries under "schematics" instead of "generators" | generators section (the schematics section routes through the Angular Devkit adapter) |
| Package bumps inside migration code | v6-10 | addUpdateTask(...), RunSchematicTask chaining, updateJsonInTree('package.json', ...) bumps | Declarative packageJsonUpdates; a .ts implementation only for conditional dep changes |
| workspace.json / angular.json editing | v8-11 | updateWorkspaceInTree, getWorkspace / updateWorkspace, updateBuilderConfig | getProjects / updateProjectConfiguration; readNxJson / updateNxJson |
@nrwl/* imports | through ~v15 | from '@nrwl/workspace', from '@nrwl/devkit'; readWorkspaceConfiguration / updateWorkspaceConfiguration | @nx/devkit |
| SchematicTestRunner specs | v6-13 | SchematicTestRunner, UnitTestTree, runMigration('<name>', ...) against the collection | createTreeWithEmptyWorkspace + direct import of the default export. Note what was lost: the old helper loaded the migration BY NAME through migrations.json, so it validated the name-to-implementation wiring; direct-import specs do not, which is why the pre-PR checklist requires opening the file behind the manifest path |
| AI-instruction wrapper factories | pre mid-2026 | Factory that reads a files/<name>.md template and tree.writes tools/ai-migrations/MIGRATE_<THING>.md, returning string[] | The prompt key pointing at a colocated .md; the runner writes the managed workspace copy under tools/ai-migrations/ itself |
@nx/devkit/src/* deep imports | pre-23 | from '@nx/devkit/src/generators/...' | @nx/devkit/internal |
Still live, do not copy
| Pattern | Recognition signature | Rule |
|---|---|---|
"cli": "nx" on entries | "cli" key inside a generators entry (widespread in older entries) | Dead key; new entries omit it |
factory key | "factory": "./dist/..." | Tolerated alias; author implementation. Do not mass-rename existing entries |
x-prompt on packageJsonUpdates | "x-prompt": "Do you want to update..." | Interactive-only and deprecated for removal in Nx v24; gate with requires instead |
| Slug-less or dotted entry keys | update-22-2-0 (version, no action slug), 16.0.0-remove-nrwl-cli (dots instead of dashes); bare-version directories like 21-0-0/ | A key names its action (a slug-less key cannot distinguish two migrations in one release) and uses dashes, never dots, between version segments; directories are update-<ver>/. Key form otherwise follows the file's dominant convention (SKILL.md section 3) |
Raw updateJson(tree, 'nx.json', ...) | Direct updateJson on nx.json | readNxJson / updateNxJson |
Raw updateJson on project.json | updateJson(tree, join(root, 'project.json'), ...) | updateProjectConfiguration; raw edits silently skip package.json-based projects |
Returning a GeneratorCallback | Promise<GeneratorCallback> return type, returning install tasks | Discarded by the runner; return void, string[], or { nextSteps, agentContext, skipAgentic } |
console.* or the nx output util | console.warn(...), import { output } from 'nx/src/utils/output' | devkit logger |
Static import * as ts from 'typescript' | Value import at module top | Type-only import plus lazy ensureTypescript() / ensurePackage |
Deep nx/src/* imports | from 'nx/src/utils/...' in a plugin migration | Use devkit exports; boundary-crossing imports are tolerated in old code, not in new |
| Substring checks for ignore files | content.includes(entry) then string append | addEntryToGitIgnore (packages/nx/src/utils/ignore.ts) |
| Non-colocated prompt files | prompt pointing into a generator's files/ directory | Colocate the .md in the migration's update-<ver>/ directory |
| Prompt .md written in the documentation genre | h4 #### Sample Code Changes headings in a file wired as prompt | Prompts use the runbook genre (templates/prompt-runbook.md); the h4 genre is for documentation files |
devkit glob in migrations | glob( from @nx/devkit | Deprecated in place; use globAsync |