generator-modern-web-dev

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.