divmain / js-seed

Start a frontend project in under 5 minutes, with full test and build infrastructure.

The JavaScript Seed

One of the most common blockers to starting a new project is boilerplate. Not many of us want to spend days setting up build and test infrastructure - we want to get coding while the idea is fresh.

Ideally,

• Starting a new frontend project should take less than 5 minutes.
• The developer should not have to sacrifice the robustness of build tools or test infrastructure for the sake of a quick start.
• Tests should be easy to write, quick to run, and straight-forward to debug.
• The developer should only have to make decisions specific to the project.
• Because not all developers have the same level of experience, "the build" should be as comprehensible as possible.

This project aims to:

• Be narrow in scope, providing only build and test infrastructure, remaining agnostic to frontend libraries or frameworks;
• Ease the developer experience, by providing a well documented and discoverable build;
• Serve as an educational tool for developers unfamiliar with one or more of the tools utilized here; and
• Provide a foundation for a variety of frontend applications.

Getting Started

Clone the repo locally, providing the name of your new project:

cd <YOUR_WORKING_DIRECTORY>
git clone https://github.com/divmain/js-seed.git <YOUR_PROJECT_NAME>
cd <YOUR_PROJECT_NAME>

A quick-start script is provided to help you get things set up. To run it, type ./start.sh into your console. It will:

• clean up all files related to the js-seed project;
• configure package.json with your name, email and project name;
• offer a selection of licenses that you can use for your project, and enter your contact information in the copyright notices;
• offer a selection of CI integration options;
• offer to setup a remote Github or Bitbucket repository; and
• initialize a new Git history.

Using this script is optional, and you should feel free to do the work manually if you have special requirements.

Finally, run npm install.

Tasks

When working on a project, a lot of your time will be spent in the terminal running Gulp tasks. To see what tasks are available, type gulp or gulp help into your console.

You should see something like the following:

[11:26:07] Starting 'help'...

Usage
  gulp [task]

Available tasks
  build             Copy assets, build CSS and JS.
  build-dev         Build, but with unminified JS + sourcemaps.
  build:css         Build CSS, Stylus & LESS --> CSS.
  build:css:css     Build and add vendor prefixes for plain CSS.
  build:css:less    Build and add vendor prefixes to LESS styles.
  build:css:sass    Build and add vendor prefixes to SAS styles.
  build:css:stylus  Build and add vendor prefixes to Stylus styles.
  build:js          Build minified JS.
  build:js-dev      Build unminified JS with sourcemaps.
  help              Display this help text.
  lint              Lint application- and test-code.
  test              Run unit tests in the browser.
  test-coverage     Run browser unit tests in the console.
  test-karma        Auto-run unit tests in multiple browsers.
  test-phantom      Run browser unit tests in the console.
  test-watch        Run browser tests in console; run again on change.
  watch             Perform build-dev when sources change.

[11:26:07] Finished 'help' after 1.41 ms

The Stack

Before going any further, take a look at the tools that you have at your disposal. If you come across questions that are unanswered in this README, check the following sites for documentation.

• Build
  • gulp - a task runner and build tool
  • webpack - a module bundler that accepts/outputs CommonJS/AMD/UMD
• Tests
  • mocha - test framework
  • Chai - assertion framework
  • Sinon.JS - spies, stubs, and mocks
  • Karma - automated testing in multiple browsers (Chrome, Firefox, Sarafi enabled by default) and in the console
  • Istanbul - test code coverage
• Libraries
  • Lo-Dash - utility library, an alternative to Underscore.js (this is used for the build and need not be used in your application)
• CSS
  • Stylus - CSS pre-processor
  • LESS - CSS pre-processor
  • SASS - CSS pre-processor; only SCSS syntax supported
  • Autoprefixer - automatic vendor prefix handling

Tests and Application Code

The project is configured in such a way that you can write tests anywhere you want in the frontend directory. Test files will be identified by their extension: .spec.js. To keep things organized, we recommend creating one spec file for each application file, and placing that spec file in the same location.

Example test and application code

To see this in action, open up frontend/js/main.js and frontend/js/main.spec.js. The latter contains code that tests the functionality of the former.

main.js is written using the CommonJs pattern - you will see that it returns a function. This function always returns true. It also calls a function if one is provided. That sounds like testable functionality!

In main.spec.js, you will see some comments explaining how things are layed out, and why. You'll also see a couple of tests that correspond to the functionality we identified.

As you develop your project, keep track of the functionality you're implementing, and write tests! Then, as requirements change and complexity increases, you can be confident that you haven't broken anything.

Running tests

To run these tests, we have a few options. For a terminal-only experience, use gulp test-phantom. This will run your tests in a headless browser, and you'll see the results in your console. If you run gulp test-watch, tests will run once and then wait. If any of your test or application code changes, they'll run again automatically.

To run your tests in multiple browsers, try gulp test-karma. You'll see browser windows pop up, and the results will be reported in your terminal.

Finally, you can try something more interactive. Run gulp test. A browser window will appear and a report of your tests will be compiled as your tests are run. You can set breakpoints using Firebug or Chrome Dev-tools in your test or application code to help debug. Additionally, if any of your test or application code changes, the tests related to that code (and only those tests) will run again. This will save you time and headaches as your test suite grows.

Linting Your Code

As a project grows, and especially when multiple developers contribute, it becomes increasingly valuable to enforce a particular code style. This seed project provides a default code style configuration. You can also select an style configuration that conforms to the Airbnb style guide. Feel free to inspect and modify .eslintrc to fit your preferences; the most important thing is consistency across your project.

To check your code for non-compliance with the code style, as well as running sanity checks for common problems, use gulp lint. If all your code passes, you'll see a [lint] SUCCESS! message. Any problems that are found will be specifically pointed out, followed by *** FAILED ESLINT ***.

Pulling in Templates

Webpack supplies a mechanism to require files as plain text. This is a convenient way to access templates. It should look something like var myTemplateString = require("./my-template.tmpl");. By default, this special behavior only works for files with extension .tmpl, but new rules can be created in webpack.config.js.

Pulling in Styles

Stylus

By default, frontend/styles/main.styl is processed by Stylus and saved as main.css in the output directory. Any other .styl files in this directory will be compiled, vendor prefixes added, and outputted to the frontend-dist/styles/ directory.

If you have files that are specific to a piece of your application, it may make sense to keep those styles in the same place as your application code. From inside a JS file, you can require a .styl file (something like require("./my-view.styl");). Those styles, including vendor prefixes, will be automatically loaded into the browser when the requiring JS module is loaded.

LESS / SCSS

Both LESS and SCSS are supported. Any files in frontend/styles with extensions .less or .scss will be compiled by its respective preprocessor, augmented with vendor prefixes, and outputted to the frontend-dist/styles/ directory.

Similar to the Stylus support, LESS and SCSS styles can be required in from your JavaScript modules, and they'll be automatically loaded into the browser.

At this time, only SCSS syntax is supported (SASS is not). This is due to limitations in the C++ SASS compiler and its JavaScript bindings. If you prefer SASS syntax, I recommend taking a look at Stylus or wiring up the Ruby package.

CSS

Any .css files in the frontend/styles/ directory will be run through Autoprefixer to add vendor-specific prefixes, and finally outputted to the frontend-dist/styles/ directory.

A word of warning

If for some reason you decide to mix CSS, LESS and SCSS in your project, be sure to avoid naming conflicts. main.styl, main.less, main.scss and main.css will all be processed and outputted as main.css in the frontend-dist directory.

Project Layout

File/Directory	Description
project.config.js	Defines paths and other global config.
gulpfile.js	Configures the gulp tool with any JS files found under gulp-tasks.
karma.conf.js	Configures Karma to run the test suite.
webpack.config.js	Webpack configuration for building JS files.
webpack.dev.config.js	Webpack configuration for building development-specific JS files.
.eslintrc	JavaScript linting rules - this encourages you to make your code consistent and readable.
wercker.yml	Wercker CI configuration.
.travis.yml	Travis CI configuration.
frontend/	Application and test code.
frontend/assets/	Static files.
frontend/js/	Application JS files. Each .js has a .spec.js counterpart.
frontend/styles/	CSS, Stylus, and LESS files.
frontend/test-runner.js	Configures and executes tests.
frontend-dist/	Builds are generated here.
gulp-tasks/	Component gulp tasks

License

This seed project is provided under the MIT License. This applies to the js-seed project itself, and not to projects generated by it. Attribution in seeded projects is appreciated but definitely not required.

js-seed's Issues

Allow people to opt out of removing .git after setup

I tried using js-seed to convert an old project from grunt -> gulp/webpack and forgot that the start script deletes my .git folder. I had recently pushed to master so I don't think anything was lost but this is a potentially big danger. If you need to do work like this on a branch you run the risk of losing a lot of work.

package.json has the wrong start

npm start will call gulp help

https://github.com/divmain/js-seed/blob/master/package.json#L53

https://github.com/divmain/js-seed/blob/master/gulpfile.js#L22-L24

add .eslintrc for AirBnb code style

The gulp tasks are divided in a (potentially) confusing way

Right now 1/2 the gulp tasks are defined under tasks and the other half are composite tasks defined in the gulpfile. If you think it should be broken up maybe only the ones in the tasks folder shouldn't be exposed in the help list. Thoughts?

I think it might be better to have tasks/composite.js and then just reduce the gulpfile to just the require statements.

How are you versioning this project?

I noticed you're at v.0.6.0 but I'm not sure what your versioning scheme is.

One thought would be to leave it at 1.0.0 (the node recommended starting spot) and let it represent the state of the cloned seed project.

Another would be for that to be to have develop/stable or develop/master and version the project that way. You'd have to add a version clear line to the start.sh script.

Thoughts?

Feature documentation

Introduce what is setup, how it is setup, and how it will benefit a new project.

Consider using require-dir

It's a new recipe on the Gulp site is the "blessed" way of sourcing tasks.

https://github.com/gulpjs/gulp/blob/master/docs/recipes/split-tasks-across-multiple-files.md

Documentation around start.sh

start.sh is amazingly helpful but its not clear from the docs what is going on. Maybe the README should have a section explaining start.

Put `npm install` inside `start.sh`

Move some of project.config.js into package.json?

I was reading about the future of npm and it's about to get crazy. The tldr; of the post is that npm is being broken apart into 3 modules: a registry, a cache and an installer in such a way that you could use BOTH Bower and NPM (of today)'s version of dependency resolution at the same time.

This is largely in response to the fact that lots and lots of people use NPM, a purposefully nody tool as a dependency resolution tool for projects that have nothing to do with node. They are moving to a "roll your own dependency system" to make it more flexible for projects that mix frontend and node. Interestingly the roll your own thing is what Express is doing too with Pilar.js in Express 5.

Anyway, the npm folks issued a call to action on the new plan which involves a few things - one of them is moving more config into your package.json. I thought I'd see what you thought about moving some of project.config.js into the package.json.

Update README with new directory structure for `task`s

Consider renaming tasks

I was reading over some of the Clean Code book the other day and I'm starting to think that tasks/ may not be an appropriate name for the gulp tasks.

When Martin talks about clean functions he talks about how they should only have one level of abstraction. A bad piece of code has some high level concepts. For example a function that has a call to build a chunk of a page mixed in with low level details about adding/removing classes in a specific scenario. It mixes up the essential concepts with the details of doing something, which can be confusing.

The reason I think that tasks/ may not be the best name is that there is no context to tell you what a task is unless you already understand gulp and the strategy to break things up. For a person entering a codebase for the first time, cogent organization is very helpful.

Candidates for the directory name: gulp-tasks/, gulp/, build-tasks/

Better documentation for the gulpfile

There should probably be a big fat comment block explaining that new tasks should be created under ./tasks then required in the gulpfile. Projects with large gulp setups are too new to have established conventions so it might not be obvious.

Decide on and document browser support

I came across this block in the test code which refers to some IE8 polyfil and I didn't really understand why it had to be there. Is this for the test runner? Probably worth documenting that tests won't run in old browsers if that's the case. On the frontend the only opinionated piece of frontend code is the inclusion of lodash which should go down to IE6 so I don't see any reason (other than the tests) the project wouldn't support down that far on that.

add .eslintrc for Google code style