Jesus Rodriguez
Miško Hevery
parent
b58c3527e9
commit
cd25939be9
|
|
@ -1,7 +1,7 @@
|
|||
{
|
||||
"scripts": [
|
||||
{ "name": "ng", "command": "ng" },
|
||||
{ "name": "build", "command": "ng build" },
|
||||
{ "name": "build", "command": "ng build --prod" },
|
||||
{ "name": "start", "command": "ng serve" },
|
||||
{ "name": "test", "command": "ng test" },
|
||||
{ "name": "lint", "command": "ng lint" },
|
||||
|
|
|
|||
|
|
@ -1,74 +1,57 @@
|
|||
# Overview
|
||||
|
||||
Many of the documentation pages contain snippets of code examples. We extract these snippets from
|
||||
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 Travis 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 we need to install dependencies into
|
||||
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. We maintain these common boilerplate files centrally to reduce the amount
|
||||
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, `system.js` configuration, etc.
|
||||
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
|
||||
generic boilerplate that works in all the examples.
|
||||
set of boilerplates that works in all the examples.
|
||||
|
||||
### Boilerplate files
|
||||
|
||||
Inside `/aio/tools/examples/shared/boilerplate` you will see all the common boilerplate you can find
|
||||
in any Angular application using System.js. This is the boilerplate that will be carried to each example.
|
||||
Inside `/aio/tools/examples/shared/boilerplate` you will find a set of folders representing each
|
||||
boilerplate.
|
||||
|
||||
Among these files, there are a few special ones:
|
||||
Currently you will find the next boilerplates:
|
||||
|
||||
* **src/systemjs.config.js** - This is the configuration of System.js used to run the example locally.
|
||||
* **src/systemjs.config.web.js** - This configuration replaces the previous one on Stackblitz.
|
||||
* **src/systemjs.config.web.build.js** - Same as the previous one but for using angular's `-builds`
|
||||
versions.
|
||||
* **src/systemjs-angular-loader.js** - It is a System.js plugin that removes the need of `moduleId`.
|
||||
* **package.json** - This package.json only contains scripts, no dependencies. It contains the
|
||||
different tasks needed to run any example. Doesn't matter if CLI, System.js or Webpack.
|
||||
* **stackblitz.json** - This file is used by the Stackblitz tool to generate a stackblitz for an example. This
|
||||
concrete file is just a placeholder. Authors needs to tweak it for each guide. More at the
|
||||
[stackblitz docs](../stackblitz-builder/README.md).
|
||||
* **example-config.json** - This file serves as a flag to indicate that the current folder is an
|
||||
example. This concrete file is just a placeholder. More on this later in this readme.
|
||||
|
||||
* 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 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
|
||||
|
||||
So what is this **example-config.json** again? If an author wants to create a new example, say
|
||||
`/aio/content/examples/awesome-example`. The author needs to create an empty `example-config.json`
|
||||
in that folder. That serves as a flag so this tool will say "Hey, that is an example, let's copy
|
||||
all the boilerplate there".
|
||||
|
||||
So when the tool runs, it finds **all** the folders with an `example-config.json` file, and puts
|
||||
a copy of the boilerplate in those folders.
|
||||
|
||||
Normally the file is empty, but we can add information in it, for example:
|
||||
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
|
||||
{
|
||||
"build": "build:cli",
|
||||
"run": "serve:cli"
|
||||
}
|
||||
{ projectType: 'universal' }
|
||||
```
|
||||
|
||||
In this case, this would indicate that this is a CLI example. Won't make any difference on the
|
||||
boilerplate, but will be useful for e2e tests (more on this later). Also works as a hint for
|
||||
the example to know how is executed.
|
||||
|
||||
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 we have a `/aio/tools/examples/shared/package.json` which contains **all** the packages
|
||||
needed to run all the examples.
|
||||
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.
|
||||
|
|
@ -77,12 +60,13 @@ may require admin rights.
|
|||
|
||||
### End to end tests
|
||||
|
||||
Each example contains an `e2e-spec.ts` file. We can find all the related configuration files for
|
||||
e2e in the `/aio/tools/examples/shared` folder.
|
||||
End to end changes between boilerplates.
|
||||
|
||||
This tool expects all the examples to be build with `npm run build`. If an example is not built
|
||||
with that script, the author would need to specify the new build command in the `example-config.json`
|
||||
as shown earlier.
|
||||
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
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,53 @@
|
|||
# How to update the CLI boilerplate
|
||||
|
||||
The boilerplate is updated by hand so you normally update it every minor version unless there is a major bug to fix.
|
||||
|
||||
## Getting a new boilerplate
|
||||
|
||||
The first thing would be updating the CLI globally
|
||||
|
||||
```
|
||||
npm i -g @angular/cli
|
||||
```
|
||||
|
||||
Then create a new dummy project in a temporary folder outside angular
|
||||
|
||||
```
|
||||
ng new dummy
|
||||
```
|
||||
|
||||
Now you have a fresh application to get our new boilerplate files.
|
||||
|
||||
## Updating files
|
||||
|
||||
From `dummy` you can replace the following files into `aio/tools/examples/shared/boilerplate/cli`:
|
||||
|
||||
* tslint.json
|
||||
* tsconfig.json
|
||||
* package.json
|
||||
* protractor.conf.js
|
||||
* karma.conf.js
|
||||
* .editorconfig
|
||||
* angular-cli.json
|
||||
* src/tsconfig.spec.json
|
||||
* src/test.ts
|
||||
* src/polyfills.js
|
||||
* src/typings.d.ts
|
||||
* src/environments/environment.prod.ts
|
||||
* src/environments/environment.ts
|
||||
|
||||
### .angular-cli.json
|
||||
|
||||
Update the `project > name` to `angular.io-example`.
|
||||
|
||||
### package.json
|
||||
|
||||
Update the `name` to `angular.io-example`.
|
||||
|
||||
### src/polyfills.ts
|
||||
|
||||
Uncomment the `import 'web-animations-js';` line to enable `web-animations-js` package.
|
||||
|
||||
### src/tsconfig.app.json
|
||||
|
||||
This file is small enough and there are a few new excludes, update by hand.
|
||||
|
|
@ -5,46 +5,45 @@
|
|||
"scripts": {
|
||||
"ng": "ng",
|
||||
"start": "ng serve",
|
||||
"build": "ng build",
|
||||
"build": "ng build --prod",
|
||||
"test": "ng test",
|
||||
"lint": "ng lint",
|
||||
"e2e": "ng e2e"
|
||||
},
|
||||
"private": true,
|
||||
"dependencies": {
|
||||
"@angular/animations": "^5.0.0",
|
||||
"@angular/common": "^5.0.0",
|
||||
"@angular/compiler": "^5.0.0",
|
||||
"@angular/core": "^5.0.0",
|
||||
"@angular/forms": "^5.0.0",
|
||||
"@angular/http": "^5.0.0",
|
||||
"@angular/platform-browser": "^5.0.0",
|
||||
"@angular/platform-browser-dynamic": "^5.0.0",
|
||||
"@angular/router": "^5.0.0",
|
||||
"@angular/animations": "^5.2.0",
|
||||
"@angular/common": "^5.2.0",
|
||||
"@angular/compiler": "^5.2.0",
|
||||
"@angular/core": "^5.2.0",
|
||||
"@angular/forms": "^5.2.0",
|
||||
"@angular/http": "^5.2.0",
|
||||
"@angular/platform-browser": "^5.2.0",
|
||||
"@angular/platform-browser-dynamic": "^5.2.0",
|
||||
"@angular/router": "^5.2.0",
|
||||
"angular-in-memory-web-api": "~0.5.0",
|
||||
"core-js": "^2.4.1",
|
||||
"rxjs": "^5.5.2",
|
||||
"zone.js": "^0.8.14"
|
||||
"rxjs": "^5.5.6",
|
||||
"zone.js": "^0.8.19"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@angular/cli": "1.5.4",
|
||||
"@angular/compiler-cli": "^5.0.0",
|
||||
"@angular/language-service": "^5.0.0",
|
||||
"@types/jasmine": "~2.8.0",
|
||||
"@angular/cli": "1.6.5",
|
||||
"@angular/compiler-cli": "^5.2.0",
|
||||
"@angular/language-service": "^5.2.0",
|
||||
"@types/jasmine": "~2.8.3",
|
||||
"@types/jasminewd2": "~2.0.2",
|
||||
"@types/node": "~6.0.60",
|
||||
"codelyzer": "^4.0.1",
|
||||
"jasmine-core": "~2.8.0",
|
||||
"jasmine-spec-reporter": "~4.1.0",
|
||||
"karma": "~1.7.0",
|
||||
"karma-chrome-launcher": "~2.1.1",
|
||||
"karma-cli": "~1.0.1",
|
||||
"jasmine-spec-reporter": "~4.2.1",
|
||||
"karma": "~2.0.0",
|
||||
"karma-chrome-launcher": "~2.2.0",
|
||||
"karma-coverage-istanbul-reporter": "^1.2.1",
|
||||
"karma-jasmine": "~1.1.0",
|
||||
"karma-jasmine-html-reporter": "^0.2.2",
|
||||
"protractor": "~5.1.2",
|
||||
"ts-node": "~3.2.0",
|
||||
"tslint": "~5.7.0",
|
||||
"typescript": "~2.4.2"
|
||||
"ts-node": "~4.1.0",
|
||||
"tslint": "~5.9.1",
|
||||
"typescript": "~2.5.3"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
|
|
@ -55,7 +55,7 @@ import 'core-js/es7/reflect';
|
|||
|
||||
|
||||
/***************************************************************************************************
|
||||
* Zone JS is required by Angular itself.
|
||||
* Zone JS is required by default for Angular itself.
|
||||
*/
|
||||
import 'zone.js/dist/zone'; // Included with Angular CLI.
|
||||
|
||||
|
|
@ -64,13 +64,3 @@ import 'zone.js/dist/zone'; // Included with Angular CLI.
|
|||
/***************************************************************************************************
|
||||
* APPLICATION IMPORTS
|
||||
*/
|
||||
|
||||
/**
|
||||
* Date, currency, decimal and percent pipes.
|
||||
* Needed for: All but Chrome, Firefox, Edge, IE11 and Safari 10
|
||||
*/
|
||||
// import 'intl'; // Run `npm install --save intl`.
|
||||
/**
|
||||
* Need to import at least one locale-data with intl.
|
||||
*/
|
||||
// import 'intl/locale-data/jsonp/en';
|
||||
|
|
|
|||
|
|
@ -11,6 +11,9 @@
|
|||
"check-space"
|
||||
],
|
||||
"curly": true,
|
||||
"deprecation": {
|
||||
"severity": "warn"
|
||||
},
|
||||
"eofline": true,
|
||||
"forin": true,
|
||||
"import-blacklist": [
|
||||
|
|
@ -127,6 +130,7 @@
|
|||
"app",
|
||||
"kebab-case"
|
||||
],
|
||||
"no-output-on-prefix": true,
|
||||
"use-input-property-decorator": true,
|
||||
"use-output-property-decorator": true,
|
||||
"use-host-property-decorator": true,
|
||||
|
|
@ -135,7 +139,6 @@
|
|||
"use-life-cycle-interface": true,
|
||||
"use-pipe-transform-interface": true,
|
||||
"component-class-suffix": true,
|
||||
"directive-class-suffix": true,
|
||||
"invoke-injectable": true
|
||||
"directive-class-suffix": true
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 5.3 KiB |
Loading…
Reference in New Issue