angular-cn/aio/tools/examples/README.md

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

> **Note for Windows users**
>
> Setting up the examples involves creating some [symbolic links](https://en.wikipedia.org/wiki/Symbolic_link) (see [here](#symlinked-node_modules) for details). On Windows, this requires to either have [Developer Mode enabled](https://blogs.windows.com/windowsdeveloper/2016/12/02/symlinks-windows-10) (supported on Windows 10 or newer) or run the setup commands as administrator.

## 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 files that works across all the examples.

### Boilerplate files

Inside `/aio/tools/examples/shared/boilerplate` you will find a set of folders representing each project type.

Currently you will find the next project types:

* cli - For CLI based examples. This is the default one, to be used in the majority of the examples.
* getting-started - CLI-based with its own set of styles.
* i18n - CLI-based with additional scripts for internationalization.
* schematics - CLI-based with additional scripts for building schematics.
* service-worker - CLI-based with additional packages and configuration for service workers.
* systemjs - Currently in deprecation, only used in a few examples.
* testing - CLI-based with additional styles for jasmine testing.
* universal - CLI-based with an extra server target.
* viewengine - Additional configuration for running CLI-/SystemJS-based examples with `ViewEngine` (the pre-Ivy compiler/renderer).

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": "cli",
  "useCommonBoilerplate": true
}
```

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 files based on the project type.

<a name="symlinked-node_modules"></a>
### 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/` folder 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.

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

### Updating example dependencies

With every major release, we update the examples to be on the latest version. The following steps to update are:

* In the `shared/package.json` file, bump all the `@angular/*`, `@angular-devkit/*`, `rxjs`, `typescript`, and `zone.js` package versions to the version that corresponds with the [framework version](../../../package.json).
* In the `shared` folder, run `yarn` to update the dependencies for the shared `node_modules` and the `yarn.lock` file.
* In the `boilerplate` folder, go through each sub-folder and update the `package.json` dependencies if one is present.
* Follow the [update guide](./shared/boilerplate/UPDATING_CLI.md) to update the common files used in the examples based on project type.