History

George Kalpakas 7491b854b3 build(docs-infra): remove obsolete `typings.d.ts` files from angular.io and docs examples (#38173 ) There were two `typings.d.ts` files with SystemJS module definitions in `aio/src/` and `aio/tools/examples/shared/boilerplate/cli/`. These are remnants from old CLI versions that used SystemJS and are no longer needed. For docs examples specifically, these files were never copied over to example projects and thus not included in StackBlitz projects and ZIP archives. This commit removes these obsolete files. PR Close #38173		2020-07-22 10:15:09 -07:00
..
customizer/package-json	refactor(docs-infra): update `universal` example to match latest CLI (#36483 )	2020-04-16 09:43:41 -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): remove obsolete `typings.d.ts` files from angular.io and docs examples (#38173 )	2020-07-22 10:15:09 -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.