Skip to content

Latest commit

 

History

History
199 lines (157 loc) · 8.52 KB

third-party-libraries.md

File metadata and controls

199 lines (157 loc) · 8.52 KB

Installing third party libraries

Abstract

The current ng install process is faulty; third parties have to add a bundles/ directory with metadata that we expect. This document explores ways to improve on the process.

Requirements

The following use cases need to be supported by ng install:

  1. Support for any thirdparties, ultimately falling back to running npm install only and doing nothing else, if necessary.
  2. Not a new package manager.
  3. Metadata storage by thirdparties in package.json. This must be accessible by plugins for the build process or even when scaffolding.
  4. Proper configuration of SystemJs in the browser.
  5. SystemJS configuration managed by the user needs to be kept separated from the autogenerated part.
  6. The build process right now is faulty because the tmp/ directory used by Broccoli is inside the project. TypeScript when using moduleResolution: "node" can resolve the node_modules directory (since it's in an ancestor folder), which means that TypeScript compiles properly, but the build does not copy files used by TypeScript to dist/. We need to proper map the imports and move them to tmp before compiling, then to dist/ properly.
  7. Potentially hook into scaffolding.
  8. Potentially hook into the build.
  9. Safe uninstall path.

Usages

Here's a few stories that should work right off:

$ ng new my-app && cd my-app/
$ ng install jquery

^(this makes jQuery available in the index)

$ ng install angularfire2
> Please specify your Firebase database URL [my-app.firebaseio.com]: _

^(makes firebase available and provided to the App)

$ ng install angularfire2 --dbUrl=my-firebase-db.example.com

^(skip prompts for values passed on the command line)

$ ng install angularfire2 --quiet

^(using --quiet to skip all prompts and use default values)

$ ng install less

^(now compiles CSS files with less for the appropriate extensions)

Proposed Solution

The install task will perform the following subtasks:

  1. Run npm install ${libName}. On failure, fail the install process.

  2. Run preinstall scripts. If any script fails, run npm uninstall ${libName} and fail the install process.

  3. Copy the appData to the angular.json file of the generated app, creating it if it doesn't exist, under the "modules" key. This data will be sent to the App as is. See the appData section for more information.

  4. Read the package["angular-cli"].appPrompt and prompt the user configuration values, if any. See the appData section for more information.

  5. Add the providers specified in package["angular-cli"]["providers"] to the angular.js providers list. Rebuild the providers.js file. See the Providers section for more information.

  6. Run package["angular-cli"].scripts["install"] if it exists. If the script fails, run npm uninstall ${libName} and fail the install process.

  7. Detect if a package named angular/cli-wrapper-${libName} exist in the angular organization. If so, run the steps above as if ng install angular/angular-${libName}. If this install fails, ignore the failure.

    These packages can be used to wrap libraries that we want to support but can't update easily, like Jasmine or LESS.

  8. Install typings. See the Typings section.

  9. Run postinstall scripts.

Proof of Concept

A proof of concept is being developed.

Hooks

The third party library can implement hooks into the scaffolding, and the build system. The CLI's tasks will look for the proper hooks prior to running and execute them.

The order of execution of these hooks is breadth first, going through all node packages and checking for the package['angular-cli']['hooks']['${hookName}']. The hooks are then require()'d as is, from within the app root folder. Within the same level of the dependency tree, there is no guarantee for the order of execution.

Install Hooks

The only tricky part here is install hooks. The installed package should recursively call its (pre|post|)install hooks only on packages that are newly installed. It should call (pre|post|)reinstall on those who were already installed. A map of the currently installed packages should be kept before performing npm install.

appData

The angular-cli key in the generated app should be used for Angular CLI specific data. This includes the CLI configuration itself, as well as third-parties library configuration.

Third-parties can store data that will be passed to the app, and can use that data themselves. That data can be anything. Any keys starting with either $ or _ will be ignored and not passed to the client. It could be used for builds or scaffolding information.

During installation, there's a step to prompt the user for data. The schema contains a prompt text and a default value. The default value type is used to convert the string entered by the user. The key used in appPrompt is the key saved in appData.

Example:

{ // ...
  "angular-cli": {
    "appPrompt": {
      "number": {
        "prompt": "Please enter a number:",
        "defaultValue": 0
      },
      "url": {
        "prompt": "URL of your website:",
        "defaultValue": "${homepage}"
      }
    }
  }
}

The default value is necessary as a quiet mode is enforced, using default values to fill in the data without user interaction. The special strings ${...} can be used to replace with special values in the default string values. The values are taken from the package.json.

We use a declarative style to enforce sensible defaults and make sure developers think about this. In the case where developers want more complex interaction, they can use the install/uninstall hooks to prompt users. But 3rd party libraries developers need to be aware that those hooks might not prompt users (no STDIN) and throw an error.

Providers

Adding Angular providers to the app should be seamless. The install process will create a providers.js from all the providers contained in all the dependencies. The User can blacklist providers it doesn't want.

The providers.js file will always be overwritten by the install / uninstall process. It needs to exist for toolings to be able to understand dependencies. These providers are global to the application.

In order to blacklist providers from being global, the user can use the --no-global-providers flag during installation, or can change the dependencies by using ng providers. As an example:

ng new my-todo-app
ng generate component database
ng install --no-global-providers angularfirebase2
ng providers database angularfirebase2

Or, alternatively, the user can add its own providers and dependencies to its components.

Dependencies

Because dependencies are handled by npm, we don't have to handle it.

Typings

Typings should be added, but failure to find typings should not be a failure of installation. The user might still want to install custom typings himself in the worst case.

The typings package can be used to install/verify that typings exist. If the typings do not exist natively, we should tell the user to install the ambient version if he wants to.

Index.html

We do not touch the index.html file during the installation task. The default page should link to a SystemJS configuration file that is auto generated by the CLI and not user configurable (see SystemJS below). If the user install a third party library, like jQuery, and wants to use it, they have to import it using import * as $ from 'vendor/jquery'.

The index.html also includes a section to configure SystemJS that can be managed by the user. This is separate from the generated code.

SystemJS

It is important that SystemJS works without any modifications by the user. It is also important to leave the liberty to the user to change the SystemJS configuration so that it fits their needs.

We will not use SystemJS bundles in development. This is for better debugging, future proofing (when moving the build system) and better CDN support, as many of the loaded files will end up being pulled from a CDN in production. During the ng build process for production, the SystemJS configuration script will be rebuilt to fetch from the CDN.

Upgrade Strategy

The upgrade process simply uses NPM. If new appData is added, it should be added manually using a migration hook for postinstall.

Remaining Problems

  1. Installing dependencies of packages need to be further sketched out.
  2. Need to add a fully fledged example with Firebase.