docs(aio): add zipper documentation (#18151)

PR Close #18151
This commit is contained in:
Jesus Rodriguez 2017-07-19 19:00:56 +02:00 committed by Igor Minar
parent 6f7aa466ae
commit ba20e3bed0
2 changed files with 73 additions and 4 deletions

View File

@ -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.
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 `<live-example>` embedded component will look at this folder to get the zip it needs for the example.

View File

@ -47,8 +47,8 @@ To handle those exceptions, we have the `embeddedPlunker.js` and the `regularPlu
Where? at `src/generated/live-examples/`.
Then the `<live-example>` embedded component will look at this folder to get the plunker it needs for the example
Then the `<live-example>` 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~.