English Version

This guide applies to the current version ng-zorro-antd >= 11; If you encounter problems during the upgrade process, feel free to comment here. If you find any errors in this guide, please point out Or you have encountered a new problem and solved it, welcome to comment here.

Before upgrade

Make sure Node.js >= 10.13.
Create a new branch, or use other methods to back up the current project.
Delete the package-lock.json file.

1.Upgrade dependencies

Upgrade Angular to 12.x version, ref https://update.angular.io/ .
Run ng update @angular/cdk, if you have used @angular/cdk.

2.Upgrade NG-ZORRO

Run ng update ng-zorro-antd.
If any warning messages appear in the console, follow the prompts to modify the corresponding code.

Common Problems

...

中文版

本指南适用于当前版本 ng-zorro-antd >= 11 ; 如果在升级过程中遇到问题，欢迎提出。提问前请阅读如何向开源社区提问题如果发现本指南存在遗漏/错误，请指出! 或者你遇到了新的问题并解决了，欢迎补充!

开始之前

首先确保你 Node.js >= 10.13
创建新的分支，或者使用其他方式备份当前项目
删除项目下 package-lock.json 文件

升级步骤

1. 升级相关依赖

前往 https://update.angular.io/ 将项目升级到 Angular 12。
如果你有单独使用 @angular/cdk 请执行 ng update @angular/cdk

2.升级 NG-ZORRO

运行 ng update ng-zorro-antd
如果控制台出现警告消息请按提示修改对应代码

常见问题

...

Hi,

After upgrading to Angular@12 and ng-zorro-antd@12. The following warning has started coming in the compiler. Although the app is working fine.

Invalid dependencies may lead to broken watching and caching.
As best effort we try to convert all invalid values to absolute paths and converting globs into context dependencies, but this is deprecated behavior.
Loaders: Pass absolute paths to this.addDependency (existing files), this.addMissingDependency (not existing files), and this.addContextDependency (directories).
Plugins: Pass absolute paths to fileDependencies (existing files), missingDependencies (not existing files), and contextDependencies (directories).
Globs: They are not supported. Pass absolute path to the directory as context dependencies.
The following invalid values have been reported:
 * "node_modules\\ng-zorro-antd\\style\\color\\bezierEasing.less"
 * "node_modules\\ng-zorro-antd\\style\\color\\colorPalette.less"
 * "node_modules\\ng-zorro-antd\\style\\color\\colors.less"
 * and more ...

Does anyone familiar with the issue?

Updates NG-ZORRO to v12 [https://github.com/NG-ZORRO/ng-zorro-antd/issues/6834]. × Migration failed: directoryExists is not a function

[error] TypeError: directoryExists is not a function at Object.matchFiles (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:20102:17) at FileSystemHost.readDirectory (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules\@angular\cdk\schematics\update-tool\utils\virtual-host.js:39:19) at getFileNamesFromConfigSpecs (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:40747:40) at getFileNames (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:40250:29) at parseJsonConfigFileContentWorker (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:40183:24) at Object.parseJsonConfigFileContent (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:40124:16) at Object.parseTsconfigFile (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules\@angular\cdk\schematics\update-tool\utils\parse-tsconfig.js:16:15) at Function.createProgramFromTsconfig (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules\@angular\cdk\schematics\update-tool\index.js:152:41) at runMigrations (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules\@angular\cdk\schematics\ng-update\devkit-migration-rule.js:113:57) at Object. (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules\@angular\cdk\schematics\ng-update\devkit-migration-rule.js:85:17)

Updates NG-ZORRO to v12 [https://github.com/[/issues/6834](https://github.com/NG-ZORRO/ng-zorro-antd/issues/6834)]. × Migration failed: directoryExists is not a function

[error] TypeError: directoryExists is not a function at Object.matchFiles (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:20102:17) at FileSystemHost.readDirectory (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules@angular\cdk\schematics\update-tool\utils\virtual-host.js:39:19) at getFileNamesFromConfigSpecs (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:40747:40) at getFileNames (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:40250:29) at parseJsonConfigFileContentWorker (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:40183:24) at Object.parseJsonConfigFileContent (D:\srccodes\achihui\node_modules\typescript\lib\typescript.js:40124:16) at Object.parseTsconfigFile (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules@angular\cdk\schematics\update-tool\utils\parse-tsconfig.js:16:15) at Function.createProgramFromTsconfig (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules@angular\cdk\schematics\update-tool\index.js:152:41) at runMigrations (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules@angular\cdk\schematics\ng-update\devkit-migration-rule.js:113:57) at Object. (D:\srccodes\achihui\node_modules\ng-zorro-antd\node_modules@angular\cdk\schematics\ng-update\devkit-migration-rule.js:85:17)

看一下依赖的typescript版本是不是4.2.x，升级Angular版本的时候会给升级成4.3.x，就会出现这个问题，降级到4.2.x就好了

theme.less client build issue: "@angular/core": "12.2.13", "ng-zorro-antd": "12.0.2",

in angular.json

                        "styles": [
                            "client/src/styles/theme.less",
                            "client/src/styles/global.scss",
                            "client/src/styles/d3d-theme.scss"
                        ],
                        "stylePreprocessorOptions": {
                            "includePaths": [
                                "client/src/styles",
                                "client/src/modules/assembly/styles",
                                "node_modules/ng-zorro-antd"
                            ]
                        },

./client/src/styles/theme.less - Error: Module build failed (from ./node_modules/mini-css-extract-plugin/dist/loader.js):
ModuleBuildError: Module build failed (from ./node_modules/less-loader/dist/cjs.js):

@table-header-icon-color-hover: darken(@table-header-icon-color, 10%);
@table-sticky-zindex: (@zindex-table-fixed + 1);
^
Operation on an invalid type

新项目，css 和 scss 都一样，报错

ng add ng-zorro-antd

报错

Node.js version v17.2.0 detected.
Odd numbered Node.js versions will not enter LTS status and should not be used for production. For more information, please see https://nodejs.org/en/about/releases/.
ℹ Using package manager: npm
⚠ Unable to find compatible package.  Using 'latest' tag.
⚠ Package has unmet peer dependencies. Adding the package may not succeed.

The package ng-zorro-antd@12.1.0 will be installed and executed.
Would you like to proceed? Yes
npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree
npm ERR! 
npm ERR! While resolving: demo@0.0.0
npm ERR! Found: @angular/animations@13.0.3
npm ERR! node_modules/@angular/animations
npm ERR!   @angular/animations@"~13.0.0" from the root project
npm ERR! 
npm ERR! Could not resolve dependency:
npm ERR! peer @angular/animations@"^12.1.0" from ng-zorro-antd@12.1.0
npm ERR! node_modules/ng-zorro-antd
npm ERR!   ng-zorro-antd@"12.1.0" from the root project
npm ERR! 
npm ERR! Fix the upstream dependency conflict, or retry
npm ERR! this command with --force, or --legacy-peer-deps
npm ERR! to accept an incorrect (and potentially broken) dependency resolution.
npm ERR! 
npm ERR! See /home/mmc/.npm/eresolve-report.txt for a full report.

npm ERR! A complete log of this run can be found in:
npm ERR!     /home/mmc/.npm/_logs/2021-12-04T08_55_12_641Z-debug.log
✖ Package install failed, see above.

/home/mmc/.npm/eresolve-report.txt

# npm resolution error report

2021-12-04T08:55:12.637Z

While resolving: demo@0.0.0
Found: @angular/animations@13.0.3
node_modules/@angular/animations
  @angular/animations@"~13.0.0" from the root project

Could not resolve dependency:
peer @angular/animations@"^12.1.0" from ng-zorro-antd@12.1.0
node_modules/ng-zorro-antd
  ng-zorro-antd@"12.1.0" from the root project

Fix the upstream dependency conflict, or retry
this command with --force, or --legacy-peer-deps
to accept an incorrect (and potentially broken) dependency resolution.

Raw JSON explanation object:

{
  "code": "ERESOLVE",
  "current": {
    "name": "@angular/animations",
    "version": "13.0.3",
    "whileInstalling": {
      "name": "demo",
      "version": "0.0.0",
      "path": "/home/mmc/projects/web/demo"
    },
    "location": "node_modules/@angular/animations",
    "isWorkspace": false,
    "dependents": [
      {
        "type": "prod",
        "name": "@angular/animations",
        "spec": "~13.0.0",
        "from": {
          "location": "/home/mmc/projects/web/demo"
        }
      }
    ]
  },
  "currentEdge": {
    "type": "prod",
    "name": "@angular/animations",
    "spec": "~13.0.0",
    "from": {
      "location": "/home/mmc/projects/web/demo"
    }
  },
  "edge": {
    "type": "peer",
    "name": "@angular/animations",
    "spec": "^12.1.0",
    "error": "INVALID",
    "from": {
      "name": "ng-zorro-antd",
      "version": "12.1.0",
      "whileInstalling": {
        "name": "demo",
        "version": "0.0.0",
        "path": "/home/mmc/projects/web/demo"
      },
      "location": "node_modules/ng-zorro-antd",
      "isWorkspace": false,
      "dependents": [
        {
          "type": "prod",
          "name": "ng-zorro-antd",
          "spec": "12.1.0",
          "from": {
            "location": "/home/mmc/projects/web/demo"
          }
        }
      ]
    }
  },
  "strictPeerDeps": false,
  "force": false
}

/home/mmc/.npm/_logs/2021-12-04T08_55_12_641Z-debug.log

0 verbose cli [
0 verbose cli   '/home/mmc/.nvm/versions/node/v17.2.0/bin/node',
0 verbose cli   '/home/mmc/.nvm/versions/node/v17.2.0/bin/npm',
0 verbose cli   'install',
0 verbose cli   'ng-zorro-antd@12.1.0',
0 verbose cli   '--quiet'
0 verbose cli ]
1 info using npm@8.1.4
2 info using node@v17.2.0
3 timing npm:load:whichnode Completed in 0ms
4 timing config:load:defaults Completed in 1ms
5 timing config:load:file:/home/mmc/.nvm/versions/node/v17.2.0/lib/node_modules/npm/npmrc Completed in 1ms
6 timing config:load:builtin Completed in 1ms
7 timing config:load:cli Completed in 2ms
8 timing config:load:env Completed in 0ms
9 timing config:load:file:/home/mmc/projects/web/demo/.npmrc Completed in 1ms
10 timing config:load:project Completed in 1ms
11 timing config:load:file:/home/mmc/.npmrc Completed in 1ms
12 timing config:load:user Completed in 1ms
13 timing config:load:file:/home/mmc/.nvm/versions/node/v17.2.0/etc/npmrc Completed in 0ms
14 timing config:load:global Completed in 0ms
15 timing config:load:validate Completed in 1ms
16 timing config:load:credentials Completed in 0ms
17 timing config:load:setEnvs Completed in 1ms
18 timing config:load Completed in 8ms
19 timing npm:load:configload Completed in 8ms
20 timing npm:load:setTitle Completed in 0ms
21 timing npm:load:setupLog Completed in 0ms
22 timing config:load:flatten Completed in 2ms
23 timing npm:load:cleanupLog Completed in 1ms
24 timing npm:load:configScope Completed in 0ms
25 timing npm:load:projectScope Completed in 1ms
26 timing npm:load Completed in 12ms
27 timing arborist:ctor Completed in 0ms
28 timing idealTree:init Completed in 348ms
29 timing idealTree:userRequests Completed in 3ms
30 silly idealTree buildDeps
31 silly fetch manifest ng-zorro-antd@12.1.0
32 verbose shrinkwrap failed to load node_modules/.package-lock.json out of date, updated: node_modules
33 http fetch GET 200 https://registry.npm.taobao.org/ng-zorro-antd 749ms (cache revalidated)
34 silly fetch manifest @angular/animations@~13.0.0
35 http fetch GET 200 https://registry.npm.taobao.org/@angular%2fanimations 130ms (cache revalidated)
36 silly fetch manifest @angular/animations@^12.1.0
37 silly fetch manifest @angular/core@~13.0.0
38 http fetch GET 200 https://registry.npm.taobao.org/@angular%2fcore 105ms (cache revalidated)
39 silly fetch manifest rxjs@~7.4.0
40 http fetch GET 200 https://registry.npm.taobao.org/rxjs 40ms (cache revalidated)
41 silly fetch manifest zone.js@~0.11.4
42 http fetch GET 200 https://registry.npm.taobao.org/zone.js 41ms (cache revalidated)
43 timing idealTree Completed in 1490ms
44 timing command:install Completed in 1498ms
45 verbose stack Error: unable to resolve dependency tree
45 verbose stack     at Arborist.[failPeerConflict] (/home/mmc/.nvm/versions/node/v17.2.0/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/build-ideal-tree.js:1356:25)
45 verbose stack     at Arborist.[loadPeerSet] (/home/mmc/.nvm/versions/node/v17.2.0/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/build-ideal-tree.js:1322:34)
45 verbose stack     at async Arborist.[buildDepStep] (/home/mmc/.nvm/versions/node/v17.2.0/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/build-ideal-tree.js:930:11)
45 verbose stack     at async Arborist.buildIdealTree (/home/mmc/.nvm/versions/node/v17.2.0/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/build-ideal-tree.js:216:7)
45 verbose stack     at async Promise.all (index 1)
45 verbose stack     at async Arborist.reify (/home/mmc/.nvm/versions/node/v17.2.0/lib/node_modules/npm/node_modules/@npmcli/arborist/lib/arborist/reify.js:149:5)
45 verbose stack     at async Install.exec (/home/mmc/.nvm/versions/node/v17.2.0/lib/node_modules/npm/lib/commands/install.js:157:5)
45 verbose stack     at async module.exports (/home/mmc/.nvm/versions/node/v17.2.0/lib/node_modules/npm/lib/cli.js:65:5)
46 verbose cwd /home/mmc/projects/web/demo
47 verbose Linux 5.14.18-1-MANJARO
48 verbose argv "/home/mmc/.nvm/versions/node/v17.2.0/bin/node" "/home/mmc/.nvm/versions/node/v17.2.0/bin/npm" "install" "ng-zorro-antd@12.1.0" "--quiet"
49 verbose node v17.2.0
50 verbose npm  v8.1.4
51 error code ERESOLVE
52 error ERESOLVE unable to resolve dependency tree
53 error
54 error While resolving: demo@0.0.0
54 error Found: @angular/animations@13.0.3
54 error node_modules/@angular/animations
54 error   @angular/animations@"~13.0.0" from the root project
54 error
54 error Could not resolve dependency:
54 error peer @angular/animations@"^12.1.0" from ng-zorro-antd@12.1.0
54 error node_modules/ng-zorro-antd
54 error   ng-zorro-antd@"12.1.0" from the root project
54 error
54 error Fix the upstream dependency conflict, or retry
54 error this command with --force, or --legacy-peer-deps
54 error to accept an incorrect (and potentially broken) dependency resolution.
54 error
54 error See /home/mmc/.npm/eresolve-report.txt for a full report.
55 verbose exit 1

NG-ZORRO / ng-zorro-antd

NG-ZORRO V12 Upgrade Guide/ 升级指南 #6834