nationalbankbelgium/stark

Modern client-side Web application framework based on Angular, Angular Material / Material Design, TypeScript, Redux, RxJS, ...

An Angular 6+ based front-end framework built on top of Angular... Stark features an awesome reusable build using Webpack and built-in support for state of the art front-end tech

Stark provides main building blocks for accelerating front-end development:

• a solid reusable build based on Webpack
• a starter project inspired by Angular Starter by AngularClass and Google's Web Starter Kit
• core modules providing reusable APIs (e.g., reactive client for RESTful APIs based on NBB's RESTful API Design Guide, routing, logging, log shipping, ...)
• UI modules providing reusable UI components (e.g., data table, message pane, ...) and themes
• a showcase application containing
  • demos of all components/services along with their API
  • our living style guide
  • our developer guide

Stark modules are like LEGO blocks: add what you need, no less, no more. If you don't like our defaults then you may replace/override/ignore anything you fancy.

Stark's build

Stark's reusable build integrates support for:

• Angular optimizations: AOT, lazy loading with UI-Router
• TypeScript, @types, TSLint, Codelyzer
• Code formatting with Prettier
• HTML templating with html-webpack-plugin
• PostCSS with CSSNext, nesting, prefixing, ...
• Code splitting
• Tree shaking to automatically remove unused code from your production bundle
• Hot Module Replacement with @angularclass/hmr and @angularclass/hmr-loader
• Minification & uglification
• Cache busting with file hashes
• Tests: E2E, Karma, Protractor, Jasmine, with source maps support, possibility to execute subsets of the tests, ...
• Tests code coverage with Istanbul
• Environments definition (development | production)
• Assets copying
• Security with a DEV mode Content Security Policy (CSP) enabled
• Local testing with fake back-ends using json-server
• Router visualization with UI-Router Visualizer

Stark packaging

All the Stark packages are built following the Angular Package Format so the following bundles are provided:

• FESM2015
• FESM5
• ESM2015
• ESM5
• UMD

So they can be consumed by Angular CLI, Webpack or SystemJS.

Developer guide

• Stark-Build
• Stark-Core
• Stark-UI

Stark monorepo documentation

• Common errors during development
• End-to-End Testing
• Polyfills
• Prettier
• TSConfig files structure

Releases

Stark releases are available on npm: https://www.npmjs.com/settings/nationalbankbelgium/packages

Snapshot builds

Each and every day, a new snapshot of Stark is built, tested and published on npm: https://www.npmjs.com/settings/nationalbankbelgium/packages See this page for more information about the process behind this.

Contributing

Please follow our contribution guidelines.

To know how to release Stark, refer to this page.

Authors

Sebastien Dubois

• @Twitter
• @Medium
• @Blog
• @GitHub

Alexis Georges

• @Twitter
• @GitHub

Christopher Cortes

• @GitHub

Olivia Tournois

• @Twitter
• @GitHub

License

This project and all associated source code is licensed under the terms of the MIT License.

Showcase and Documentation

The Stark Showcase can be found here. There, you'll also find links about:

• the latest API docs for Stark-Core
• the previous API docs for Stark-Core
• the latest API docs for Stark-UI
• the previous API docs for Stark-UI
• the previous Showcase versions

Thank you notes :)

We'd like to thank the following companies who support the open source community with great tools and platforms.

Jetbrains

We're supported by Jetbrains and their awesome support for open source, thanks to which we are able to use the best products on the market to work on this open source project!

GitHub Actions

We're supported by GitHub Actions

BrowserStack

We're supported by BrowserStack

stark's Issues

build & packages: integrate npm ci

Goal: improve ci build speed.

For this to work work

• we first need to have a valid package-lock.json file in the project. It should be valid and point to the npmjs official registry (not our internal nexus).
• we should remove package-lock.json from .gitignore
• we should commit the file

https://medium.com/@tomastrajan/how-to-speed-up-continuous-integration-build-with-new-npm-ci-and-package-lock-json-7647f91751a

starter: add setup script to starter

Should we have our setup script again in the starter?

If so, add it and update the starter/README.md. Also explain which packages are needed in global (if any)

build & all: split translation files per stark module

Once we split up in n modules, the translations should also be split

doc: commit message guidelines

Should be added to CONTRIBUTING.md

Cfr https://chris.beams.io/posts/git-commit/

build: document stylesheets processing

What we have for now: a bit of docs (not up to date nor correct in starter/README.md)
What we want:

• explanation about how stylesheets are loaded
• explanation about how stylesheets are processed/bundled... (webpack, TS, ...)
• explanation about the differences in processing/bundling between dev and prod)

This doc can be put in the starter's readme for now

build: upgrade to Webpack 4+

Webpack 4 has been released: https://medium.com/webpack/webpack-4-released-today-6cdb994702d4

admin: add support for all-contributors

Cfr https://github.com/kentcdodds/all-contributors

add a ".all-contributorsrc" file. Example: https://github.com/alexjoverm/typescript-library-starter/blob/master/.all-contributorsrc

testing: revisit how we test stark and the starter

Currently we still create a big fat bundle for tests.
This was a source of complaints for project teams.
Can we take another approach? What does the Angular team recommend

doc: update and publish training materials

Update and publish stark training and tie with the build to make sure that stark training still at least compiles and that tests are ok with each new release of stark in the making

• review/update existing training materials
• tie training materials with the build to make sure it always works
• add section about e2e testing
• add section about debugging and troubleshooting

stark-build: CommonChunkPlugin config

Should we still use infinity?

build & all: review typedoc config

• starter: review typedoc config file
• project root: add typedoc.json and scripts

build: extract starter scripts (aka Stark CLI)

Scripts in the starter should be extracted and made part of the build

admin: add badges

Add the following badges (edit to see links)

• npm version
• downloads
• Travis
• Coveralls (#249)
• BrowserStack (#274)
• Dependencies up to date

build: ensure that sourcemaps are present and fully functional

To check:

• sourcemaps generated for stark packages with the main build
• starter sourcemaps: generation / loading
• debugging in dev mode: are sourcemaps there in the browser?
• debugging of tests

build: integrate jarvis or similar

Goal: evaluate and integrate if worth it (in dev)
https://github.com/zouhir/jarvis

Or similar solutions

doc: how to publish a release

To document in RELEASE.md

core: create stark-core module

build: add support for environments

Assuming the build specifies the environment (either default value or provided as CLI argument), make sure we have support for finding out the current environment within Stark apps (programmatically)

This requires some cleanup as we currently have (at least) these:

• webpack options
• Define plugin
• src/environments/environments.ts: provides programmatic checks (if env === ...)
• custom-typings.d.ts: probably doesn't need any typings for the env anymore!
• HTML templating
• polyfills.browser.ts

i18n & l10n: add support

Goals

• find a replacement for the current angular-translate in AngularJS for Angular 4+
• keep support for translation files
• isolate in a dedicated module?
• integrate stark translations (split per module? #39)
• add translation loading support

Later:

• add support for remote translations: #200

Possible options:

• https://angular.io/guide/i18n (Angular2+ builtin support)
• https://github.com/ngx-translate/core (pretty similar with what we already have in AngularJS)
• https://github.com/robisim74/angular-l10n

build: evaluate puppeteer

evaluate and integrate if worth it: https://github.com/GoogleChrome/puppeteer

doc: add README.md

Create templates for issues and PRs

Create a template for issues and PRs; see https://github.com/blog/2111-issue-and-pull-request-templates
This'll help with issues reporting & changes proposals

build: configure CI

Integrate CI for

• stark as a whole
• starter
• demo

We can start with Travis. Example:

• https://github.com/angular/angular/blob/master/.travis.yml
• https://github.com/angular/angular/tree/master/scripts/ci

doc: main project structure

To doc in CONTRIBUTING.md

discussion: evaluate if we need to split up stark-core in multiple packages

Over time, we can use this issue as discussion point for the split-up of stark-core in multiple npm packages

starter: document structure

To doc in starter/README.md

build: add a clean script

Goals:

• be able to clean everything from stark's root (dist, node_modules, ...)
• be able to clean each package (e.g., npm run clean from packages/stark-core)
• be able to clean the starter
• be able to clean the demo

build: integrate changelog and upgrade guidelines docs

• decide how to manage changelog and upgrade guide for Stark
• integrate changelog and scripts to automate

Angular uses conventional-changelog: https://www.npmjs.com/package/conventional-changelog and standard-version to update the changelog: https://github.com/conventional-changelog/standard-version

References:

• https://github.com/angular/angular/blob/master/CHANGELOG.md
• https://github.com/dsebastien/modernWebDevBuild/blob/master/UPGRADE.MD

build: review and integrate build steps and initial structure for stark packages

References to look at:

• https://medium.com/@cyrilletuzi/how-to-build-and-publish-an-angular-module-7ad19c0b4464
• https://github.com/cyrilletuzi/angular-quickstart-lib

Things we have identified we need to adapt:

• stark-core should probably use peerDependencies for core deps

build: automate release process

We should have a script that helps us doing a release easily and automatically.
It should

• update package.json (semver)
• update changelog
• tag
• push the tag
• let travis handle the npm publish

First

• review what angular does: https://github.com/angular/angular/tree/master/scripts/release
• evaluate semantic-release
• evaluate standard-version

build & starter: verify manifest inlining config

Cfr https://www.npmjs.com/package/inline-manifest-webpack-plugin

starter: review index.html head

Goal: review the head part of the index.html template.
Should we add support for defining custom entries?

Review also the following files in the starter

• https://github.com/gdi2290/angular-starter/blob/master/config/head-config.common.js
• https://github.com/gdi2290/angular-starter/blob/master/config/html-elements-plugin/index.js

Can't we mimick this?

build: add headless testing support

Take a look at:

• https://github.com/developit/karmatic
• https://developers.google.com/web/updates/2017/04/headless-chrome
• https://hackernoon.com/more-than-you-want-to-know-about-headless-chrome-31f6b3b06d82
• https://developers.google.com/web/updates/2017/06/headless-karma-mocha-chai

build: review all build scripts

Review all scripts:

• align with what we had before and make sure we don't lose anything
• HMR: review webpack config and code/comments in starter/src/hmr.ts
• make sure we have a clean script: #47

doc: add CONTRIBUTING.md

core: config

Add support for Stark configuration
Revisit stark config files

Do we keep the concept? (vs angular.json usage/extension)
Consider impact on our deploy tool.

• design (e.g., eliminate metadata config file)?
• load config files
• validate config files on app startup

build: publish nightly builds

Integrate generation/publication of nightly builds.
How? npm script as we had in Stark "v1" ?
How does Angular create its nightly builds?

Publish nightly through Travis

pre-reqs:

• needs NPM token to publish
• should only publish to npm if
  • nightly build (should add the "next" tag)
  • slug = NationalBankBelgium/stark

steps:

• release-publish.sh: check if TRAVIS_EVENT_TYPE == "cron". If so:
  • don't check for TRAVIS_TAG
  • publish with "next" tag

build & starter: integrate prettier

Goal: add prettier to Stark: https://prettier.io/

References:

• https://medium.com/@victormejia/setting-up-prettier-in-an-angular-cli-project-2f50c3b9a537
• https://github.com/prettier/prettier
• https://github.com/prettier
• https://prettier.io

Must have:

• dedicated npm script to prettify the code
• IDE (IntelliJ) integration (automatic if possible)
• git hook
• no conflict with ts-lint!

build & starter: review linting config

Review / finalize our tslint config:

• currently we have codelyzer in our deps (from Angular starter) and two different tslint config files (root & starter/). We should clean this up and decide if we keep codelyzer or not
• tslint config files should be present in all parts (root, stark packages, starter) (extends)
• contents of the tslint config should be fully reviewed
• pcss code should also have dedicated configs in each part with the same logic as for prettier & tslint)

If we drop it we'll need to adapt the project's readme

Add CODE_OF_CONDUCT.md

https://help.github.com/articles/adding-a-code-of-conduct-to-your-project/

Example: https://github.com/alexjoverm/typescript-library-starter/blob/master/code-of-conduct.md

starter: clean up

Goal:

• get rid of everything we don't need in the current starter
• remove icons (same)
• Create a simple home page with routes and submodules

doc: add browser compatibility info

Reference: https://github.com/angular/angular

core: add paths for core modules to stark core

Goal: make sure packages that depend on the stark core module have access to it through this trick:

    "paths": {
      "@angular/core": ["../../dist/packages/core"],
      "@angular/common": ["../../dist/packages/common"],
      "@angular/platform-browser": ["../../dist/packages/platform-browser"]
    },

build: make it functional under *nix

Currently our build script doesn't work under ubuntu.

build & starter: review webdriver install process

Make sure webdriver config is ok (cfr what we did internally before for it with custom script, etc)
Depending on result, adapt starter/README.md

doc: how to build the whole project

Build.sh etc
To document in CONTRIBUTING.md

build: implement the build.sh script

Not having the build.sh script working slows us down too much.

build: verify postcss prefixing config

build & starter: add Docker and Kubernetes support

Multiple ideas to look into:

• docker: build & start starter in a container (npm start)
• docker: build & start starter in a container (DEV build with an NGINX / Tomcat server)
• docker: build & start starter in a container (PROD build with an NGINX / Tomcat server)
• docker: build & start starter json-server in a container (npm start + npm run json-server)
• kubernetes: build & start starter in a pod (npm start)
• kubernetes: build & start starter json-server in a pod (npm run json-server)
• kubernetes: build & start starter in a pod WITH json-server (npm start + npm run json-server)
• kubernetes: build & start starter in a pod (DEV build with an NGINX / Tomcat server)
• kubernetes: build & start starter AND json-server in a pod (DEV build with an NGINX / Tomcat server)
• kubernetes: build & start starter in a pod (PROD build with an NGINX / Tomcat server)
• update the readme files
• demo: replicate all the above
• execute unit tests in Docker/Kubernetes (need headless tests)
• execute e2e tests in Docker/Kubernetes (need headless tests)

So for this we'll need:

• Dockerfiles in the starter
• k8s deployment descriptors in the starter
• Dockerfiles in the root
• k8s deployment descriptors in the root

http: evaluate if we should switch to angular's fake http server

Angular apparently now has support for a fake API back-end.
Could we get rid of json-server?