dsebastien / modernwebdevgenerator

A Yeoman generator for Modern Web development projects

Modern Web Dev Generator

About

ModernWebDevGenerator is a Yeoman generator that will help you quickly get up and running with ModernWebDevBuild.

Projects created with this Yeoman Generator will be able to directly leverage the awesome Gulp-based build provided by the ModernWebDevBuild project, which includes many tasks and features out of the box (e.g., transpilation of TypeScript/ES2015 to ES5, SASS transpilation to CSS, Minification, Bundling, Code quality & code style checks, Sourcemaps, support for unit testing, ...).

This project comes with a fully working Angular 2 configuration.

This generator includes all the folders & files listed by ModernWebDevBuild as mandatory as well as the recommended ones so as to promote good practices. README.md files are placed in multiple locations to describe what to put where, provide some guidance/design guidelines, ...

The generated projects also include:

• a working setup of Angular 2 (this might later move to a separate sub-generator)
  • a root component (app/core/boot.ts)
  • a home page (app/pages/home.ts)
  • a basic component router configuration
• a good HTML5 boilerplate
• a good SASS & styling starting point
• an embedded folder structure and design guidelines (componentization, separation of concerns, naming conventions, ...)
• a set of TypeScript code style/quality rules (tshint.json)
• a set of ES2015 compliant code style/quality rules (.jscsrc and .jshintrc)
• ...

The general idea is that you can remove anything you don't need assuming it's not in the list of mandatory folders/files of ModernWebDevBuild (otherwise you'll break the build ^^).

Any feedback/contributions are welcome to improve the project so don't hesitate!

This project is available as an NPM package; check out the usage instructions below.

Demo

Click on this link to see a demo of how to install & use this project and the modern web dev build:

Background

Please note that this project is heavily inspired from:

• Google's Web Starter Kit
• HTML5 Boilerplate
• Brad Frost's Atomic Design
• Nicolas Gallagher's SUIT CSS
• Countless blog articles
  • Dan Walhin's TypeScript posts & course)
    • Introduction to TypeScript
  • A gazillion Gulp articles
• Many others I'm forgetting :(

Status & roadmap

Check out the issues/labels & milestones to get an idea of what's next. For existing features, refer to the previous sections.

Check out the change log

Usage

In order to use this generator you first need to install Yeoman:

npm install --global yo

Once Yeoman is installed, you can install this generator:

npm install --global generator-modern-web-dev

You will also need to install gulp globally:

npm install --global gulp

Create a new folder, go into it then invoke the generator by running the following command:

yo modern-web-dev

Once you've answered all the questions, the generator will do its thing. Once done, you'll be able to run the development web server and start hacking away using:

npm start

Enjoy!

Note that the ModernWebDevBuild project has other tricks in store for you; be sure to check out the docs.

Options

There are two main approaches to use this generator:

• interactive mode: the generator asks you all the questions
• batch mode: you provide the information directly to the generator

In practice nothing prevents you from mixing both though :) If you pass a setting directly to the generator, it will not prompt you for that value.

You can list all the options with a brief description using yo modern-web-dev --help.

By default, the generator will install all project dependencies (not the global requirements listed in the 'Usage' section!). You can skip the installation of the project dependencies by passing the --skip-install option.

The generator will check for updates once in a while but you can disable the update check by passing the following flag: --no-update-notifier.

Generated projects dev dependencies

• gulp: JavaScript task runner
• babel: ES2015 to ES5 transpiler. Needed so that the Gulp configuration file can be written using ES2015 (gulpfile.babel.js)
• nodemon: monitoring of certain files (used by npm scripts defined in package.json): https://www.npmjs.com/package/nodemon

Generated projects runtime dependencies

The following dependencies are managed by JSPM (in the JSPM section of the package.json file):

• Angular 2
• RxJS: Reactive Extensions. Forget about Promises and use Observable, the future of async in JavaScript!
• normalize.css: Nicolas Gallagher's Normalize CSS (alternative to CSS resets): https://www.npmjs.com/package/normalize.css

Generated projects configuration files

The project includes multiple configuration files.

For more details about the configuration files, check out the ModernWebDevBuild's documentation.

Here's some high level information about these:

• .babelrc: Babel configuration file
• gulpfile.babel.js: gulp's configuration file. This is where the Modern Web Dev Build tasks are loaded
• package.json: NPM's configuration file. This is where all dependencies are defined: project ones under 'jspm' and build-related ones under 'devDependencies' (more information: https://docs.npmjs.com/files/package.json)
• .dockerignore: files that are ignored by Docker when creating images
• .editorconfig: helps configure code style for various text editors (more information here: http://editorconfig.org)
• .gitattributes: allows to define git attributes per path (more information here: http://git-scm.com/docs/gitattributes)
• .gitignore: configures files/folders that are ignored by git
• .jscsrc: configuration file for JSCS. It defines the JS code style (more information: http://jscs.info/overview.html#options)
  • note that it is configured to use ES Next (ES2015+)
  • rules reference: http://jscs.info/rules.html
  • news: https://github.com/jscs-dev/node-jscs/blob/master/CHANGELOG.md
• .jshintrc: JSHint configuration
  • rules reference: http://jshint.com/docs/options
  • more information: http://jshint.com/docs/)
• .jshintignore: stuff that JSHint should ignore
• .travis.yml: Travis CI configuration files (more information: http://docs.travis-ci.com/user/build-configuration/)
• Dockerfile and DockerfileDev: Docker configuration files used to describe how Docker images should be created for this project (more information: https://www.docker.com/ and http://docs.docker.com/reference/builder/)
• jspm.conf.js: JSPM/SystemJS configuration file
• karma.conf.js: Karma test runner configuration file
• runOnDocker.sh and runDevOnDocker.sh: build scripts that create/run Docker images
• tsconfig.json: TypeScript compiler configuration. Contains all compiler options, code style rules and file selection/exclusion rules (bypassed by the gulp-typescript plugin!)
  • http://json.schemastore.org/tsconfig
  • https://github.com/Microsoft/TypeScript/wiki/tsconfig.json
• typings.json: typings configuration file: list of TypeScript type definitions files to retrieve
• tslint.json: TypeScript code style configuration (more information: https://www.npmjs.com/package/tslint)
• Makefile: for *NIX afficionados

Adding project dependencies

As you go along, you'll surely need to add new dependencies for your application. If the dependency you want to add is required at runtime, then you should use JSPM to add it. Installing a dependency with JSPM is as simple as jspm install x. For more information about JSPM, check out the official site: http://jspm.io/

Contributing

Take a look at the project's open issues and milestones.

If you know what to do then:

• Fork the project
• Create a feature branch in your fork
• Rebase if needed to keep the project history clean
• Commit your changes & push to GitHub
• Try and flood me with pull requests :)

Building from source

If you want to build from source, you need to:

• install NodeJS (4.2+) and npm (3+)
• clone this git repository
• install gulp: npm install --global gulp
• run npm run setup
• start hacking :)

Releasing a version

• commit all changes to include in the release
• edit the version in package.json
  • respect semver
• update CHANGELOG.MD
• commit
• git tag
• git push --tags
• draft the release on GitHub (add description, etc)
• npm publish

Authors

Sebastien Dubois

• @Blog
• @Twitter
• @GitHub

License

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

modernwebdevgenerator's Issues

Add karma to the project's build for unit testing

Document how to update runtime dependencies

Remove duplicate npm dependencies

Remove reflect-metadata and angular2 npm dependencies once ts supports a way to add paths for module resolution (like jspm) in tsconfig.json.

Alternative: remove JSPM if the build switches to something else for bundling. See dsebastien/modernWebDevBuild#16

Add sinon.js support

• add sinon.js support (might be better in the generator along with jasmine & karma-jasmine): better stubbing/spying support
• check/add/list all required typings (e.g., jasmine, sinon.js)

Add browse happy to the default index

Now that IE < 11 is dead, it's really time to get older versions out of the way :)

Skip prompts if arguments/options given

Add choice for TypeScript vs ES2015

Dependent on flexibility in ModernWebDevBuild:

• dsebastien/modernWebDevBuild#9

Add version check at generator start

Auto update/warning

Extract the Angular 2 support to a sub-generator

Angular 2 - put back the correct route definition syntax

Reference: angular/angular#3637

Add Makefile

Finalize/test Makefile

Avoid the need for installing packages globally

Linked to dsebastien/modernWebDevBuild#49

Add answer caching

Example: author info

• mention the --skip-cache option if the user wants to be asked everything
• ref: http://yeoman.io/authoring/storage.html

Document how to add runtime dependencies

Angular 2 requires zone.js to be imported

Without that import, change detection just doesn't work.

Add tests

• generated project content
• options

Add npm shrinkwrap for this project

angular2-polyfills.js bundle is not available with the dist version

Given that angular2-polyfills is loaded through a script tag:
https://github.com/dsebastien/modernWebDevGenerator/blob/master/app/templates/applicationTemplates/app/index.html#L48

We load it that way as recommended by the Angular team: angular/angular#5980

The issue is that this breaks the current way the build creates the bundle. When the build creates the bundle it uses JSPM and the boot.ts file of the application as entrypoint and loads/bundles dependencies from there.

This way of building eliminated the need to copy files around (fragile) but given the current situation with a2 beta 0, it's broken on our end.

Possible solutions:

• add an option to the build to specify specific files that should be copied (src/dst)
• always copy the whole node_modules fs tree (yuck)
• ?

Is declaration: true needed in tsconfig.json?

Improve user experience - project generation speed

Currently, generating a project takes a lot of time because of the large number of dependencies to pull down.

How to limit this?

Some ideas:

• reorganize the build and how it is installed
• use npm link assuming a correct version of the build is globally installed (could be part of a pre-req/initial check during project generation)

Update the installation instructions for 0.1.0

• which packages to install first

Put back old paths to Angular 2 modules

Put back old paths to modules (e.g., core/...) once TS can find its way with this

• if needed, add back the jspm paths (core, components, pages)

Upgrade babel dependencies

Add support for unit testing

Depends on dsebastien/modernWebDevBuild#14

• #36
• add karma config file
• add testing related deps
• update readme (explain libraries used, configuration, etc)

Add Docker support

Rename folders to get closer to the Maven world

To make it easier to incorporate this build within a Java maven build, the folders should be renamed:

• .tmp -> target
• app -> src

It doesn't fundamentally change anything in the JS world..

Production build is broken because of HTML minification

See dsebastien/modernWebDevBuild#67

Add scripts

Dependent of build improvements: dsebastien/modernWebDevBuild#13

Add jasmine imports in the provided unit test

Add dummy tests/specs for the components in generated Angular 2 projects

Depends on testing support in modern web dev build: dsebastien/modernWebDevBuild#14

Travis should not run tests twice

When travis starts, we instruct it to run "npm run setup" in the before_install phase.
When that is done, because of the npm install, the prepublish npm script is executed, which builds and tests.

After that travis runs npm test, which builds & runs the unit tests again.

Related: npm/npm#10074

TypeScript - Check the status of files, filesGlob and exclude

• microsoft/TypeScript#1927
• microsoft/TypeScript#3188
• exclude list does not support wilcards. It must simply be a list of files and/or directories

Once fileGlobs are properly supported, simplify the config & update the doc (incl modern web dev build readme)

Review other generators

https://github.com/babel/generator-babel-boilerplate/blob/master/app/index.js

Remove CORE_DIRECTIVES import

See dsebastien/midnightLightV2#83

Enable noImplicitAny by default

TypeScript's noImplicitAny should probably be enabled by default to push best practices forward.
Projects can still decide to disable it if it's too much of a burden for them .. :)

The generator misses the babel-runtime dependency

Upgrade to modernWebDevBuild 0.3.x

Evaluate switch from commonjs to system module format for TS

Currently, in the tsconfig.json file, we define commonjs as the module format that TypeScript should generate. I've done this in the past to fix some issues (can't remember which ones :p), but maybe we could switch to system: https://github.com/dsebastien/modernWebDevGenerator/blob/master/app/templates/projectFiles/tsconfig.json

Upgrade to Angular 2 beta 1

Add ghooks and prevent commit if tests fail

https://www.npmjs.com/package/ghooks

package.json:

...
"config": {
  "ghooks": {
    "pre-commit": "npm run test",
    "commit-msg": "validate-commit-msg $1",
    "pre-push": "npm run test"
  }
}

Switch from tsd to typings

See

• dsebastien/midnightLightV2#86
• dsebastien/mmm#16
• dsebastien/regForm#38

Check if the typings package should be installed globally or not. If so, add the info to the readme

Updgrade Angular 2 support to beta 0

Upgrade to modern-web-dev-build 0.2.0

Add code coverage reports for the project

Goal: integrate https://coveralls.io/

Update dependencies for 0.1.0

• modern web dev build dependency
• modern web dev build peerDependencies
• other dependencies (https://david-dm.org/dsebastien/modernWebDevGenerator)

Add e2e test support

Depends on dsebastien/modernWebDevBuild#47

In addition:

• make sure that e2e-specific globals are allowed by tshint & jshint in the e2e folder
• add typings for protractor

Add meta keywords

Add meta name="keywords" and adapt contents based on the section currently displayed (e.g., keywords of the current post)

Add semantic release support

RxJS dependency is incorrect for Angular 2

npm:rxjs instead of npm:@reactivex/rxjs

Add dependency versions check

• "npm-check": "4.1.0"  
  

• var npmCheck = require("npm-check");
• also add to generator after installation