cargdev/angular
1
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

build(docs-infra): simplify ExampleZipper by removing PackageJsonCustomizer (#38192)

Browse Source 
Previously, `ExampleZipper` (the tool used for creating ZIP archives
from our docs examples) used the `PackageJsonCustomizer` to generate
`package.json` files for each example type. This had the following
drawbacks:
- The generated files had to be kept up-to-date with the corresponding
  boilerplate files in `aio/tools/examples/shared/boilerplate/` and
  there was no easy way to find out when the files got out-of-sync.
- The `PackageJsonCustomizer` logic was non-trivial and difficult to
  reason about.
- The same information was duplicated in the boilerplate files and the
  customizer configuration files.

This setup was useful when we used a single `package.json` file for all
docs examples. Now, however, each example type can have its own
boilerplate `package.json` file, including scripts and dependencies
relevant to the example type. Therefore, it is no longer necessary to
generate `package.json` files for ZIP archives.

This commit eliminates the drawbacks mentioned above and simplifies the
`ExampleZipper` tool by removing `PackageJsonCustomizer` and re-using
the boilerplate `package.json` files for ZIP archives.

The changes in this commit also fix some ZIP archives that were
previously broken (for example due to missing dependencies).

PR Close #38192
This commit is contained in:
George Kalpakas
2020-07-22 22:23:55 +03:00
committed by Misko Hevery
parent 7f455e6eec
commit f411c9e5b9
22 changed files with 32 additions and 409 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
aio/tools/example-zipper/README.md
View File

@ -23,33 +23,18 @@ to flag an example as something to stackblitz or zip. For example:
The zipper will use this information for creating new zips.
## Three kinds of examples
## Two kinds of examples
The majority of examples in AIO use `CLI`, with some additionally using `Webpack` and upgrade usiing `SystemJS`. This
tool is able to differentiate between them.
There are mainly two kinds of AIO docs examples: The ones based on the Angular CLI and the ones based on SystemJS.
The majority of the examples are CLI-based with only some of the `ngUpgrade` examples using SystemJS.
The boilerplate uses a `package.json` that contains packages and scripts to run any kind of example.
Using that `package.json` in the zips would confuse the users.
Some of the CLI-based examples require small tweaks to the default layout/configuration (for example, to add support for Angular elements, i18n, universal, etc.).
These example types have separate boilerplate directories with the files that are different from the default `cli` boilerplate.
Thanks to the `package.json` customizer, we can create a new `package.json` on the fly that would
only contain the packages and scripts needed to run that example.
There are appropriate `package.json` files for each type of example in the boilerplate directories.
If there is no special `package.json` file for an example type, the one from the `cli` boilerplate directory will be used instead.
The `exampleZipper.js` won't include any `System.js` related files for `CLI` or `Webpack` projects.
### The package.json customizer
Given a `type`, this tool will populate a `package.json` file customized for that type.
Here you find a:
* **base.json** - All the common scripts and packages
* **cli.json** - Extra scripts and packages for the CLI
* **universal.json** - Extra scripts and packages for universal
* **i18n.json** - Extra scripts and packages for i18n
* **systemjs.json** - All the System.js related packages but it also contains the remainder scripts
that are not in the other files.
The tool will also give some standard names to the scripts.
The `exampleZipper.js` won't include any `System.js` related files for CLI-based projects.
## The zipper.json