Skip to content

Latest commit

 

History

History
152 lines (99 loc) · 5.32 KB

README.md

File metadata and controls

152 lines (99 loc) · 5.32 KB
Raw

Getting Started

Welcome to the gulp flavor of our web app generator! If you're not familiar with gulp, we suggest checking out their docs.

If you haven't already, install yo and this generator by running:

$ npm install --global yo generator-webapp

Now you can scaffold your very own web app:

$ mkdir my-webapp
$ cd my-webapp
$ yo webapp

To start developing, run:

$ npm run start

This will fire up a local web server, open http://localhost:9000 in your default browser and watch files for changes, reloading the browser automatically.

To run the tests in the browser, run:

$ npm run serve:test

To make a production-ready build of the app, run:

$ npm run build

To preview the production-ready build to check if everything is ok:

$ npm run serve:dist

Tasks

To get the list of available tasks, run:

$ npm run tasks

Gulp plugins

Gulp plugins (the ones that begin with gulp-) don't have to be explicitly imported. They are automatically picked up by gulp-load-plugins and available through the $ variable.

Browser support

You can configure browser support for Autoprefixer and @babel/preset-env by modifying the browserslist configuration, which in this case is the browserslist field in your package.json.

Modernizr

modernizr.json contains Modernizr configuration. You can use this file as a reference for all available options.

Linting

We use ESLint for linting JavaScript code. You can define rules in your package.json under the eslintConfig field. Alternatively, you can add an .eslintrc file to your project root, where you can configure ESLint using JavaScript, JSON or YAML.

The no-undef rule and tests

The ESLint rule no-undef will warn about usage of explicitly undeclared variables and functions. Because our tests use global functions like describe and it (defined by the testing framework), ESLint will consider those as warnings.

Luckily, the fix is easy—add an .eslintrc file to the test/spec directory and let ESLint know about your testing framework. For example, if you're using Mocha, add this to .eslintrc:

{
  "env": {
    "mocha": true
  }
}

Configuration from this .eslintrc will merge with your project-wide configuration.

Serve

We use the .tmp directory mostly for compiling assets like SCSS files. It has precedence over app, so if you had an app/index.html template compiling to .tmp/index.html, http://localhost:9000 would point to .tmp/index.html, which is what we want.

This system can be a little confusing with the watch task, but it's actually pretty simple:

  • notify LiveReload when compiled assets change
  • run the compile task when source assets change

E.g. if you have Less files, you would want to notify LiveReload when Less files have compiled, i.e. when .tmp/styles/**/*.css change, but you would want to compile Less files by running the styles task when source files change, i.e. app/styles/**/*.less.

Adding New Assets

Sass

A common practice is to have a single, "main", Sass file, then use @import statements to add other partials. For example, let's say you created stylesheet for your navigation, app/styles/_nav.scss, you can then import it in app/styles/main.scss like this:

@import "nav";

JavaScript

Our build step uses special build comment blocks to mark which assets to concatenate and compress for production. You can see them at the top and bottom of app/index.html.

You have to add your own JS files manually. For example, let's say you created app/scripts/nav.js, defining some special behavior for the navigation. You should then include it in the comment blocks for your source JS files, where app/scripts/main.js is located:

<!-- build:js scripts/main.js -->
<script src="scripts/main.js"></script>
<script src="scripts/nav.js"></script>
<!-- endbuild -->

Upon build these will be concatenated and compressed into a single file scripts/main.js.

The file name in the comment block and the first source aren't related, their name being the same is a pure coincidence. The file name in the comment block specifies how the final optimized file will be called, while the sources should map to your source files.

Debugging gulpfile.js

Gulp tasks are not meant to be run directly, but instead through npm scripts. However, sometimes you want to run a tasks in order to debug it. If you don't have Gulp install globally, you can run the local CLI using npx gulp, so this is how you would run the lint task:

$ npx gulp lint

Keep in mind that only exported tasks are available to the CLI:

function myPrivateTask() {
  // not available to CLI
}

function myPublicTask() {
}

// available to CLI as "myPublicTask"
exports.myPublicTask = myPublicTask