93 lines
4.0 KiB
Markdown
93 lines
4.0 KiB
Markdown
# Overview
|
|
|
|
Many of the documentation pages contain snippets of code examples. Extract these snippets from
|
|
real working example applications, which are stored in subfolders of the `/aio/content/examples`
|
|
folder. Each example can be built and run independently. Each example also provides e2e specs, which
|
|
are run as part of our CircleCI legacy build tasks, to verify that the examples continue to work as
|
|
expected, as changes are made to the core Angular libraries.
|
|
|
|
In order to build, run and test these examples independently you need to install dependencies into
|
|
their sub-folder. Also there are a number of common boilerplate files that are needed to configure
|
|
each example's project. Maintain these common boilerplate files centrally to reduce the amount
|
|
of effort if one of them needs to change.
|
|
|
|
## Boilerplate overview
|
|
|
|
As mentioned, many of the documentation pages contain snippets extracted from real example applications.
|
|
To achieve that, all those applications needs to contain a basic boilerplate. E.g. a `node_modules`
|
|
folder, `package.json` with scripts, etc.
|
|
|
|
No one wants to maintain the boilerplate on each example, so the goal of this tool is to provide a
|
|
set of boilerplates that works in all the examples.
|
|
|
|
### Boilerplate files
|
|
|
|
Inside `/aio/tools/examples/shared/boilerplate` you will find a set of folders representing each
|
|
boilerplate.
|
|
|
|
Currently you will find the next boilerplates:
|
|
|
|
|
|
* CLI - For CLI based examples. This is the default one, to be used in the majority of the examples.
|
|
* systemjs - Currently in deprecation, only used in a few examples.
|
|
* i18n - Based on the CLI one, features a few scripts for i18n.
|
|
* universal - Based on the cli with a extra server for universal.
|
|
|
|
There is also a `common` folder that contains files used in all different examples.
|
|
|
|
### The example-config.json
|
|
|
|
Each example is identified by an **example-config.json** configuration file in its root folder.
|
|
This configuration file indicates what type of boilerplate this example needs. E.g.
|
|
|
|
```json
|
|
{ projectType: 'universal' }
|
|
```
|
|
|
|
If the file is empty then the default type of cli is assumed.
|
|
When the boilerplate tooling runs, it will copy into the example folder all of the appropriate boilerplate files.
|
|
|
|
### A node_modules to share
|
|
|
|
With all the boilerplate files in place, the only missing piece are the installed packages. For
|
|
that you have a `/aio/tools/examples/shared/package.json` which contains **all** the packages
|
|
needed to run all the examples through all different boilerplates.
|
|
|
|
After installing these dependencies, a `node_modules` will be created at
|
|
`/aio/tools/examples/shared/node_modules`. This folder will be **symlinked** into each example.
|
|
So it is not a copy like the other boilerplate files. This solution works in all OSes. Windows
|
|
may require admin rights.
|
|
|
|
### End to end tests
|
|
|
|
End to end changes between boilerplates.
|
|
|
|
For CLI applications, create a `app.e2e-spec.ts` inside the `e2e` folder. The tooling will run
|
|
`ng e2e` for each CLI based examples.
|
|
|
|
For SystemJS, each example contains an `e2e-spec.ts` file. You can find all the related configuration files
|
|
in the `/aio/tools/examples/shared` folder.
|
|
|
|
### example-boilerplate.js
|
|
|
|
This script installs all the dependencies that are shared among all the examples, creates the
|
|
`node_modules` symlinks and copy all the boilerplate files where needed. It won't do anything
|
|
about stackblitz nor e2e tests.
|
|
|
|
It also contains a function to remove all the boilerplate. It uses a `git clean -xdf` to do
|
|
the job. It will remove all files that don't exist in the git repository, **including any
|
|
new file that you are working on that hasn't been stage yet.** So be sure to save your work
|
|
before removing the boilerplate.
|
|
|
|
### run-example-e2e.js
|
|
|
|
This script will find all the `e2e-spec.ts` files and run them.
|
|
|
|
To not run all tests, you can use the `--filter=name` flag to run the example's e2e that contains
|
|
that name.
|
|
|
|
It also has an optional `--setup` flag to run the `example-boilerplate.js` script and install
|
|
the latest `webdriver`.
|
|
|
|
It will create a `/aio/protractor-results-txt` file when it finishes running tests.
|