History

George Kalpakas 1c385a1c22 build(docs-infra): do not include CI-specific config in docs examples ZIP archives (#36018 ) In #35381, a new Protractor config file was introduced in docs examples, `protractor-puppeteer.conf.js`, that was only supposed to be used on CI and not be shipped with the ZIP archives provided for users to download and experiment with the docs examples locally. The logic to ignore the `protractor-puppeteer.conf.js` file was incorrect, resulting in the file being retained in some examples (e.g. [universal][1]). The problem was not immediately obvious, because most examples explicitly specify all `*/.js` files as ignored, but for other examples the file was retained in the ZIP archive. This commit fixes the logic to ensure the file is excluded from all docs examples ZIP archives. [1]: https://v9.angular.io/generated/zips/universal/universal.zip PR Close #36018		2020-03-27 10:48:30 -07:00
..
customizer/package-json	build(docs-infra): clean up dependencies and npm scripts in `systemjs` docs examples (#36015 )	2020-03-18 10:00:02 -07:00
README.md	build(docs-infra): remove obsolete properties from `zipper.json` files (#36018 )	2020-03-27 10:48:30 -07:00
exampleZipper.js	build(docs-infra): do not include CI-specific config in docs examples ZIP archives (#36018 )	2020-03-27 10:48:30 -07:00
generateZips.js	build(aio): rename `src/content` to `src/generated`	2017-05-03 13:40:46 -07:00

README.md

Overview

In the AIO application, we offer the reader the option to download each example as a full self-contained runnable project packaged as a zip file. These zip files are generated by the utility in this folder.

Example zipper

The exampleZipper.js tool is very similar to the Stackblitz's builder.js. The latter creates an HTML file with all the examples' files and the former creates a zip file instead. They both use the stackblitz.json file to flag an example as something to stackblitz or zip. For example:

{
  "description": "Tour of Heroes: Part 6",
  "files":[
    "!**/*.d.ts",
    "!**/*.js",
    "!**/*.[1,2].*"
  ],
  "tags": ["tutorial", "tour", "heroes", "http"]
}

The zipper will use this information for creating new zips.

Three 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.

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.

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.

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 zipper.json

As mentioned, the tool uses the stackblitz.json as a flag and also a configuration file for the zipper. The problem is that not all examples have a stackblitz but they could offer a zip instead.

In those cases, you can create a zipper.json file with the same syntax. It will be ignored by the stackblitz tool.

Executing the zip generation

generateZips.js will create a zip for each stackblitz.json or zipper.json it finds.

Where? At src/generated/zips/.

Then the <live-example> embedded component will look at this folder to get the zip it needs for the example.