One tool to rule them all

[michalstocki]

This issue is addressed to ts-skeleton users as much as to @b091 who created this future proof TypeScript stack skeleton.
The problem, we currently noticed is that we have very similar tech stack in our four projects written in TypeScript, but we have to maintain it in every project separately.

Problem: maintaining the tech-stack

Let's look into problems with ts-skeleton itself:

• one day the build task stopped working due to silent update of systems-builder
• another day, one of the tools we use, became deprecated

Now each of us need to correct configuration of their project. What a waste of time! Every time when the tslint, typedoc, jspm, sytemjs or whatever else configuration API changes, we need to make changes in all our projects.

Do our projects really need as much individual configurations? What are main differences between them, that force specific configuration?

Solution: convention

The problem is present also in other technologies. We bumped into the problem in JS world very late. For a long time, the fact that there is no built-in module manager in JavaScript, was not a problem. Now we build more and more complex front-end applications and the tools like webpack and systemjs appeared. Maybe it's time to move a bit forward and create a tool which will handle not only building (systemjs), dependency management (jspm) but also:

• documentation
• reporting
• releases
• and distribution?

Sounds familiar? It's what Maven does for Java projects.

... Maven is about the application of patterns in order to achieve an infrastructure which displays the characteristics of visibility, reusability, maintainability, and comprehensibility.

(Philosophy of Maven)
Maven follows "convention over configuration" principle, which allow it's users to get a new project or module started in seconds.

Convention: project structure

One of the major things which make our gulp tasks different between our projects is directory structure. To not invent the wheel again, I suggest to follow the maven project structure while it make sense for us:

project root
 |- package.json // containing project-specific options for our tool
 |- node_modules
 |- src
 |  |- main
 |  |  |- typescript
 |  |  |  |- Main.ts
 |  |  |  `- tslint.json
 |  |  |- images
 |  |  `- less // or sass or simply css
 |  `- test
 |     |- typescript
 |     `- resources
 |- target // or dist, maybe?
 |- vendor
 |  |- jspm_packages
 |  `- typings
 |- index.html // root file for app projects
 `-README.md

However it's only proposal (to be discussed). Project structure is one of the things that must be thoroughly discussed, as it's really hard to change in the future. We should find an appropriate place for generated docs, reports, distribution files, e2e tests (or maybe e2e tests should be placed in a separate project? – to be discussed).

Convention: shared tools

Of course the idea of the tool is not to implement building, dependencies management etc. itself. To avoid tons of configuration for each project, we need to select one tool for each task. So, here are my proposals (already used in ts-skeleton):

Building (package management)

tool: Systemjs
Configuration of systemjs is a part of JSPM configuration (see below)
We should provide two types of projects:

• library, which build contains index.js and index.js.map
• application, which build contains index.html and directories with images and other resources

Dependency management

tool: JSPM
List of dependencies as well as configuration of non-standard registries, may be provided in custom section of package.json. From options provided in this section we could generate jspm config and dependencies list (invisible in root package.json file). Location of jspm_packages as well as most options jspm.conf.js could be forced by the convention (to be discussed).

Documentation

tool: Typedoc

Tests

tool: Karma
Other tests frameworks (and karma plugins) could be specified by the user. Maybe main part of the karma.conf.js should also be forced by the convention (to be discussed)?

Reports

• test coverage tool: Istanbul until we get better tool for test coverage calculation
• code quality: TSLint, ESLint

Develoment server

tool: browser-sync

Distribution

tool: ?
We should support distribution via:

• npm (with support for private packages)
• git
• Maven artifactory (maybe as a plugin – to be discussed)

Assumtions:

• most of the projects no longer need to have karma, gulp and other tools in dependencies - we guarantee that all tools have latest versions and work together
• project setup is simple and follows best practices
• we are able to easily work with multiple projects at the same time