From ba20e3bed03880bb9b209750cd018c8fc3b9faaa Mon Sep 17 00:00:00 2001 From: Jesus Rodriguez Date: Wed, 19 Jul 2017 19:00:56 +0200 Subject: [PATCH] docs(aio): add zipper documentation (#18151) PR Close #18151 --- aio/tools/example-zipper/README.md | 73 ++++++++++++++++++++++++++++- aio/tools/plunker-builder/README.md | 4 +- 2 files changed, 73 insertions(+), 4 deletions(-) diff --git a/aio/tools/example-zipper/README.md b/aio/tools/example-zipper/README.md index 96bf8d1311..15c0d7f092 100644 --- a/aio/tools/example-zipper/README.md +++ b/aio/tools/example-zipper/README.md @@ -1,4 +1,73 @@ # 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. \ No newline at end of file +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 Plunker'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 `plnkr.json` file to flag an example as something to plunker a zip. For example: + +```json +{ + "description": "Tour of Heroes: Part 6", + "basePath": "src/", + "files":[ + "!**/*.d.ts", + "!**/*.js", + "!**/*.[1,2].*" + ], + "tags": ["tutorial", "tour", "heroes", "http"] +} +``` + +The zipper will use this information for creating new zips. + +## Three kind of examples + +The majority of examples in AIO use `System.js` but there are also `CLI` and `Webpack` projects. This tool is able to differentiate between them. + +The boilerplate uses a `package.json` that contains packages and scripts tags 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 +* **webpack.json** - Extra scripts and packages for Webpack +* **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 `plnkr.json` as a flag and also a configuration file for the zipper. The problem is that not all examples have a plunker but they could offer a zip instead. + +In those cases, you can create a `zipper.json` file with with the same syntax. It will be ignored by the plunker tool. + +## Choosing the zip "type" + +In both `plnkr.json` and `zipper.json` you can use two new properties: + +``` +{ + ... + "removeSystemJsConfig": true, + "type": "webpack" +} +``` + +This would generate a .zip for a webpack application and it will also remove everything related with SystemJS. + +## Executing the zip generation + +`generateSipz.js` will create a zip for each `plnk.json` or `zipper.json` it finds. + +Where? at `src/generated/zips/`. + +Then the `` embedded component will look at this folder to get the zip it needs for the example. diff --git a/aio/tools/plunker-builder/README.md b/aio/tools/plunker-builder/README.md index 41c119aa3a..19c9b8a64e 100644 --- a/aio/tools/plunker-builder/README.md +++ b/aio/tools/plunker-builder/README.md @@ -47,8 +47,8 @@ To handle those exceptions, we have the `embeddedPlunker.js` and the `regularPlu Where? at `src/generated/live-examples/`. -Then the `` embedded component will look at this folder to get the plunker it needs for the example +Then the `` embedded component will look at this folder to get the plunker it needs for the example. ## Appendix: Why not generating plunkers on runtime? -At AngularJS, all the plunkers were generated a runtime. The downside is that all the example codes would need to be deployed as well and they won't be no longer useful after the plunker is generated. This tool takes a few seconds to run, and the end result is only 3mb~ +At AngularJS, all the plunkers were generated a runtime. The downside is that all the example codes would need to be deployed as well and they won't be no longer useful after the plunker is generated. This tool takes a few seconds to run, and the end result is only 3mb~.