update: should document migration of npm scripts due to breaking changes to CLI arguments

[Splaktar]

Versions

Angular CLI: 6.0.0-rc.3
Node: 8.10.0
OS: darwin x64
Angular: 6.0.0-beta.8
... animations, common, compiler, compiler-cli, core, forms
... http, language-service, platform-browser
... platform-browser-dynamic, platform-server, router
... service-worker

@angular/cdk: 6.0.0-rc.2
@angular/cli: 6.0.0-rc.3
@angular/flex-layout: 5.0.0-beta.13
@angular/material: 6.0.0-rc.2
@angular-devkit/architect: 0.5.5
@angular-devkit/build-angular: 0.5.5
@angular-devkit/build-optimizer: 0.5.5
@angular-devkit/core: 0.5.5
@angular-devkit/schematics: 0.5.5
@ngtools/json-schema: 1.1.0
@ngtools/webpack: 6.0.0-rc.3
@schematics/angular: 0.5.5
@schematics/update: 0.5.5
typescript: 2.7.2
webpack: 4.5.0

Repro steps

• Step 1 - Start with the following .angular-cli.json

{
  "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
  "project": {
    "name": "webapp"
  },
  "apps": [
    {
      "root": "src",
      "outDir": "dist",
      "assets": [
        "assets",
        "manifest.json",
        "icons",
        "robots.txt",
        "sitemap.xml"
      ],
      "index": "index.html",
      "main": "main.ts",
      "polyfills": "polyfills.ts",
      "test": "test.ts",
      "tsconfig": "tsconfig.app.json",
      "testTsconfig": "tsconfig.spec.json",
      "prefix": "app",
      "styles": [
        "styles.scss"
      ],
      "scripts": [
        "../node_modules/hammerjs/hammer.js",
        "../node_modules/firebase/firebase-app.js",
        "../node_modules/firebase/firebase-auth.js",
        "../node_modules/firebase/firebase-database.js"
      ],
      "environmentSource": "environments/environment.ts",
      "environments": {
        "dev": "environments/environment.ts",
        "staging": "environments/environment.staging.ts",
        "prod": "environments/environment.prod.ts"
      },
      "serviceWorker": true
    }
  ],
  "e2e": {
    "protractor": {
      "config": "./protractor.conf.js"
    }
  },
  "lint": [
    {
      "project": "src/tsconfig.app.json",
      "exclude": ["**/node_modules/**"]
    },
    {
      "project": "src/tsconfig.spec.json",
      "exclude": ["**/node_modules/**"]
    },
    {
      "project": "e2e/tsconfig.e2e.json",
      "exclude": ["**/node_modules/**"]
    }
  ],
  "test": {
    "karma": {
      "config": "./karma.conf.js"
    }
  },
  "defaults": {
    "styleExt": "scss",
    "component": {
      "spec": false,
      "inlineStyle": false,
      "inlineTemplate": false
    },
    "directive": {
      "spec": false
    },
    "class": {
      "spec": false
    },
    "guard": {
      "spec": false
    },
    "module": {
      "spec": false
    },
    "pipe": {
      "spec": false
    },
    "service": {
      "spec": false
    }
  }
}

• Step 2 - Run npm start, which in my case runs ng serve --target=development --environment=dev
• Step 3 - Get message

An old project has been detected, which needs to be updated to Angular CLI 6.

Please run the following commands to update this project.

  ng update @angular/cli --migrate-only --from=1.7.1
  npm i

This ng update command seems to run npm i for you, so I'm not sure why it's saying to run npm i again here.
Step 4 - Run ng update @angular/cli --migrate-only --from=1.7.1
Step 5 - Run npm start (ng serve --target=development --environment=dev) again

Project 'development' could not be found in workspace.
Error: Project 'development' could not be found in workspace.
    at Workspace.getProject (/Users/splaktar/Git/tf/webapp/node_modules/@angular-devkit/core/src/workspace/workspace.js:86:19)
    at Architect.getBuilderConfiguration (/Users/splaktar/Git/tf/webapp/node_modules/@angular-devkit/architect/src/architect.js:96:41)
    at MergeMapSubscriber._loadWorkspaceAndArchitect.pipe.operators_1.concatMap [as project] (/Users/splaktar/Git/tf/webapp/node_modules/@angular/cli/models/architect-command.js:75:55)
    at MergeMapSubscriber._tryNext (/Users/splaktar/Git/tf/webapp/node_modules/@angular/cli/node_modules/rxjs/internal/operators/mergeMap.js:122:27)
    at MergeMapSubscriber._next (/Users/splaktar/Git/tf/webapp/node_modules/@angular/cli/node_modules/rxjs/internal/operators/mergeMap.js:112:18)
    at MergeMapSubscriber.Subscriber.next (/Users/splaktar/Git/tf/webapp/node_modules/@angular/cli/node_modules/rxjs/internal/Subscriber.js:103:18)
    at TapSubscriber._next (/Users/splaktar/Git/tf/webapp/node_modules/@angular/cli/node_modules/rxjs/internal/operators/tap.js:109:26)
    at TapSubscriber.Subscriber.next (/Users/splaktar/Git/tf/webapp/node_modules/@angular/cli/node_modules/rxjs/internal/Subscriber.js:103:18)
    at MergeMapSubscriber.notifyNext (/Users/splaktar/Git/tf/webapp/node_modules/@angular/cli/node_modules/rxjs/internal/operators/mergeMap.js:141:26)
    at InnerSubscriber._next (/Users/splaktar/Git/tf/webapp/node_modules/@angular/cli/node_modules/rxjs/internal/InnerSubscriber.js:30:21)

Step 6 - Run ng serve --target=development --environment=development
Same error as prior step.

Desired behavior

All 3 of my environments should have been migrated: dev, staging, prod. Only staging and prod were migrated and dev appears to have been lost.

Mention any other details that might be useful (optional)

Here is the migrated angular.json

{
  "version": 1,
  "newProjectRoot": "projects",
  "projects": {
    "webapp": {
      "root": "",
      "projectType": "application",
      "architect": {
        "build": {
          "builder": "@angular-devkit/build-angular:browser",
          "options": {
            "outputPath": "dist",
            "index": "src/index.html",
            "main": "src/main.ts",
            "tsConfig": "src/tsconfig.app.json",
            "polyfills": "src/polyfills.ts",
            "assets": [
              {
                "glob": "**/*",
                "input": "src/assets",
                "output": "/assets"
              },
              {
                "glob": "manifest.json",
                "input": "src",
                "output": "/"
              },
              {
                "glob": "**/*",
                "input": "src/icons",
                "output": "/icons"
              },
              {
                "glob": "robots.txt",
                "input": "src",
                "output": "/"
              },
              {
                "glob": "sitemap.xml",
                "input": "src",
                "output": "/"
              }
            ],
            "styles": [
              {
                "input": "src/styles.scss"
              }
            ],
            "scripts": [
              {
                "input": "node_modules/hammerjs/hammer.js"
              },
              {
                "input": "node_modules/firebase/firebase-app.js"
              },
              {
                "input": "node_modules/firebase/firebase-auth.js"
              },
              {
                "input": "node_modules/firebase/firebase-database.js"
              }
            ]
          },
          "configurations": {
            "staging": {
              "optimization": true,
              "outputHashing": "all",
              "sourceMap": false,
              "extractCss": true,
              "namedChunks": false,
              "aot": true,
              "extractLicenses": true,
              "vendorChunk": false,
              "buildOptimizer": true,
              "serviceWorker": true,
              "fileReplacements": [
                {
                  "src": "src/environments/environment.ts",
                  "replaceWith": "src/environments/environment.staging.ts"
                }
              ]
            },
            "production": {
              "optimization": true,
              "outputHashing": "all",
              "sourceMap": false,
              "extractCss": true,
              "namedChunks": false,
              "aot": true,
              "extractLicenses": true,
              "vendorChunk": false,
              "buildOptimizer": true,
              "serviceWorker": true,
              "fileReplacements": [
                {
                  "src": "src/environments/environment.ts",
                  "replaceWith": "src/environments/environment.prod.ts"
                }
              ]
            }
          }
        },
        "serve": {
          "builder": "@angular-devkit/build-angular:dev-server",
          "options": {
            "browserTarget": "webapp:build"
          },
          "configurations": {
            "staging": {
              "browserTarget": "webapp:build:staging"
            },
            "production": {
              "browserTarget": "webapp:build:production"
            }
          }
        },
        "extract-i18n": {
          "builder": "@angular-devkit/build-angular:extract-i18n",
          "options": {
            "browserTarget": "webapp:build"
          }
        },
        "test": {
          "builder": "@angular-devkit/build-angular:karma",
          "options": {
            "main": "src/test.ts",
            "karmaConfig": "./karma.conf.js",
            "polyfills": "src/polyfills.ts",
            "tsConfig": "src/tsconfig.spec.json",
            "scripts": [
              {
                "input": "node_modules/hammerjs/hammer.js"
              },
              {
                "input": "node_modules/firebase/firebase-app.js"
              },
              {
                "input": "node_modules/firebase/firebase-auth.js"
              },
              {
                "input": "node_modules/firebase/firebase-database.js"
              }
            ],
            "styles": [
              {
                "input": "src/styles.scss"
              }
            ],
            "assets": [
              {
                "glob": "**/*",
                "input": "src/assets",
                "output": "/assets"
              },
              {
                "glob": "manifest.json",
                "input": "src",
                "output": "/"
              },
              {
                "glob": "**/*",
                "input": "src/icons",
                "output": "/icons"
              },
              {
                "glob": "robots.txt",
                "input": "src",
                "output": "/"
              },
              {
                "glob": "sitemap.xml",
                "input": "src",
                "output": "/"
              }
            ]
          }
        },
        "lint": {
          "builder": "@angular-devkit/build-angular:tslint",
          "options": {
            "tsConfig": [
              "src/tsconfig.app.json",
              "src/tsconfig.spec.json"
            ],
            "exclude": [
              "**/node_modules/**"
            ]
          }
        }
      }
    },
    "webapp-e2e": {
      "root": "",
      "projectType": "application",
      "cli": {},
      "schematics": {},
      "architect": {
        "e2e": {
          "builder": "@angular-devkit/build-angular:protractor",
          "options": {
            "protractorConfig": "./protractor.conf.js",
            "devServerTarget": "webapp:serve"
          }
        },
        "lint": {
          "builder": "@angular-devkit/build-angular:tslint",
          "options": {
            "tsConfig": [
              "e2e/tsconfig.e2e.json"
            ],
            "exclude": [
              "**/node_modules/**"
            ]
          }
        }
      }
    }
  },
  "schematics": {
    "@schematics/angular:class": {
      "spec": false
    },
    "@schematics/angular:component": {
      "spec": false,
      "inlineStyle": false,
      "inlineTemplate": false,
      "prefix": "app",
      "styleext": "scss"
    },
    "@schematics/angular:directive": {
      "spec": false,
      "prefix": "app"
    },
    "@schematics/angular:guard": {
      "spec": false
    },
    "@schematics/angular:module": {
      "spec": false
    },
    "@schematics/angular:pipe": {
      "spec": false
    },
    "@schematics/angular:service": {
      "spec": false
    }
  }
}

I would assume that my existing NPM Scripts would continue to work after the update. These include things like

  "scripts": {
    "build": "ng build --target=development --environment=development",
    "build-staging": "ng build --target=production --environment=staging",
    "build-staging-with-source-maps": "ng build --target=production --environment=staging -sm",
    "build-prod": "ng build --target=production --environment=prod",
    "start": "ng serve --target=development --environment=development",
    "start-staging": "ng serve --target=production --environment=staging",
    "start-prod": "ng serve --target=production --environment=prod",

[Splaktar]

It seems like there needs to be a migration step that updates NPM Scripts if the CLI commands are going to have breaking changes. I had some success manually updating my scripts to the following:

  "scripts": {
    "build": "ng build",
    "build-staging": "ng build --configuration=staging",
    "build-staging-with-source-maps": "ng build --configuration=staging -sm",
    "build-prod": "ng build --configuration=production",
    "start": "ng serve",
    "start-staging": "ng serve --configuration=staging",
    "start-prod": "ng serve --configuration=production",

[filipesilva]

Regarding the update message mentioning npm i, that is removed in master currently.

The dev environment was not migrated over because that ends up being default settings. It would have ended up being

          "configurations": {
            "dev": {
              "fileReplacements": [
                {
                  "src": "src/environments/environment.ts",
                  "replaceWith": "src/environments/environment.ts"
                }
              ]

which effectively does nothing.

On the topic of npm scripts needing changes... yes they will need changes. Options have changed name and some have different meanings. --target no longer is production or development, but rather refers to the key inside the architect entry of a project.

But I don't think we should change npm scripts on a user project. Changing dependencies is one thing, but changing scripts seems too invasive IMHO.

I think the changes in options need to be addressed via documentation on the upgrade itself. Users will also need to adapt the commands they run manually, not just in the npm scripts.

@hansl WDYT?

[Splaktar]

I'm OK with not changing scripts, as you mentioned it might be invasive or possibly buggy.

I do however think that this needs to be called out in an official upgrade guide and likely in the output of the update migration command itself. If it's too long, perhaps via a link.