google / web-starter-kit

Web Starter Kit - a workflow for multi-device websites

Overview

Web Starter Kit is an opinionated boilerplate for web development. Tools for building a great experience across many devices and performance oriented. Helping you to stay productive following the best practices outlined in Google's Web Fundamentals. A solid starting point for both professionals and newcomers to the industry.

Features

Feature	Summary
Responsive boilerplate	A responsive boilerplate optimized for the multi-screen web. Powered by Material Design Lite. You're free to use either this or a completely clean-slate via basic.html.
Sass support	Compile Sass into CSS with ease, bringing support for variables, mixins and more. (Run gulp serve or gulp for production)
Performance optimization	Minify and concatenate JavaScript, CSS, HTML and images to help keep your pages lean. (Run gulp to create an optimised version of your project to /dist)
Code Linting	JavaScript code linting is done using ESLint - a pluggable linter tool for identifying and reporting on patterns in JavaScript. Web Starter Kit uses ESLint with eslint-config-google, which tries to follow the Google JavaScript style guide.
ES2015 via Babel 6.0	Optional ES2015 support using Babel. To enable ES2015 support remove the line "only": "gulpfile.babel.js", in the .babelrc file. ES2015 source code will be automatically transpiled to ES5 for wide browser support.
Built-in HTTP Server	A built-in server for previewing your site locally while you develop and iterate
Live Browser Reloading	Reload the browser in real-time anytime an edit is made without the need for an extension. (Run gulp serve and edit your files)
Cross-device Synchronization	Synchronize clicks, scrolls, forms and live-reload across multiple devices as you edit your project. Powered by BrowserSync. (Run gulp serve and open up the IP provided on other devices on your network)
Offline support	Thanks to our baked in Service Worker pre-caching, sites deploying dist to a HTTPS domain will enjoy offline support. This is made possible by sw-precache.
PageSpeed Insights	Web performance metrics showing how well your site performs on mobile and desktop (Run gulp pagespeed)

Quickstart

Download the kit or clone this repository and build on what is included in the app directory.

There are two HTML starting points, from which you can choose:

• index.html - the default starting point, containing Material Design layout.
• basic.html - no layout, but still includes our minimal mobile best-practices

Be sure to look over the installation docs to verify your environment is prepared to run WSK. Once you have verified that your system can run WSK, check out the commands available to get started.

Web Performance

Web Starter Kit strives to give you a high performance starting point out of the box. Our median Web Page Test scores for the default template have a Speed Index of ~1100 (1000 is ideal) and a repeat-visit Speed Index of ~550 thanks to Service Worker precaching.

Browser Support

At present, we officially aim to support the last two versions of the following browsers:

• Chrome
• Edge
• Firefox
• Safari
• Opera
• Internet Explorer 9+

This is not to say that Web Starter Kit cannot be used in browsers older than those reflected, but merely that our focus will be on ensuring our layouts work great in the above.

Troubleshooting

If you find yourself running into issues during installation or running the tools, please check our Troubleshooting guide and then open an issue. We would be happy to discuss how they can be solved.

A Boilerplate-only Option

If you would prefer not to use any of our tooling, delete the following files from the project: package.json, gulpfile.babel.js and .travis.yml. You can now safely use the boilerplate with an alternative build-system or no build-system at all if you choose.

Docs and Recipes

• File Appendix - What do the different files here do?
• Using Material Design Lite's Sass - how to get MDL's Sass working with WSK
• Deployment guides - available for Firebase, Google App Engine and other services.
• Gulp recipes - the official Gulp recipes directory includes a comprehensive list of guides for different workflows you can add to your project.

Inspiration

Web Starter Kit is inspired by Mobile HTML5 Boilerplate and Yeoman's generator-gulp-webapp, having taken input from contributors to both projects during development. Our FAQs attempt to answer commonly asked questions about the project.

Contributing

Contributions, questions and comments are all welcome and encouraged. For code contributions to Web Starter Kit, please see our Contribution guide before submitting a pull request. Website related issues should be filed on the Web Fundamentals issue tracker.

License

Apache 2.0
Copyright 2015 Google Inc

web-starter-kit's Issues

DevTools won't pop-out in staged version

I tried to pop-out devtools in the staged version of my project, and the devtools just take over the tab. They don't pop-out. It's super annoying especially since we want to be able to use the tools and mess with the sizing of the site as part of checking responsiveness.

Weird transition to mobile layout when resizing window

Start with a wide viewport.
Move the window in about half way, the screen turns into a mobile layout and you see the menu appear on the left-hand side of the screen and then it transitions away.

Sass Direction

Here's the current directory structure:

app/styles/sass/
app/styles/sass/components.scss
app/styles/components.css
app/styles/h5bp.css
app/styles/main.css

Having both components.css and the Sass source in app/styles/sass/components.scss is a way to support those who don't wish to use tooling. However, this structure is a bit confusing. I believe it would be clearer to have a structure like:

-app/styles/sass/
+app/styles/components/
app/styles/components.css
app/styles/h5bp.css
app/styles/main.css

The current directory name sass leads me to believe I can't create a sass file in app/styles/, which we should allow.

The build process is currently a little funky, too. gulp watch (which calls gulp styles), simply takes app/styles/sass/components.scss, processes it, and spits it out as dist/styles/components.css. This has two side effects:

1. You have to run a build to see the results of your edits to the component library.
2. You're left with an out-of-date app/styles/components.css hanging around.

Would it be better to take all app/styles/**/*.scss, and spit them out as .css in app/styles/? This way, you can see the result of your edits as you develop, without having to run a build.

The problem I see with this approach is, assuming you had a custom app/styles/module.scss, you would end up with app/styles/module.css as well.

During development using Yeoman generators, we store the compiled .css in a .tmp directory. During the build, the compiled .css is spit out in dist, leaving only the Sass source files in app/styles. How tricky is it to add this functionality in here?

// @addyosmani @sindresorhus @passy

UX Pattern library/styleguide file

Inspiration:

• http://patterns.alistapart.com/
• http://demo.patternlab.io/

I could imagine this being a more fleshed out version of http://ionicframework.com/docs/components/ if we're using Ionic.

Styleguide JS not picked up in build process

@sindresorhus Our html task currently does pick up and copy the styleguide markup correctly however it doesn't appear to do the same for the script included in that page. Is this a bug in our setup or do we need to manually specific the path as part of this chain?

gulp.task('html', ['styles'], function () {
    return gulp.src('app/**/*.html')
        .pipe($.useref.assets())
        .pipe($.if('*.js', $.uglify()))
        .pipe($.if('*.css', $.csso()))
        .pipe($.if('*.css', $.uncss({ html: ['app/index.html'] })))
        .pipe($.useref.restore())
        .pipe($.useref())
        .pipe($.minifyHtml())
        .pipe(gulp.dest('dist'))
        .pipe($.size({title: 'html'}));
});

Default layout in index.html

We have some basic content in there now. We could probably trim it down. I also wonder if we should right out of the box include some common layout.

e.g Like appbar-navdrawer-sample1.html

Add support for PageSpeed

I really like Google APIs node module: https://www.npmjs.org/package/googleapis.

With it we can add support for the PageSpeed API using something like..

var googleapis = require('googleapis');
googleapis.load('pagespeedonline', 'v1', function(err, client) {

  // set your API key
  client = client.withApiKey('...');

  // Hosted URL (url), Strategy (desktop, mobile)
  var params = { url: '...', strategy: '...' };

  var request = client.pagespeedonline.pagespeedapi.runpagespeed(params);
  request.execute(function (err, result) {
    // Do something with this data
    console.log(err, result);
  });
});

This is straight-forward enough to add in, but there are two pieces of data that we then need. The URL (which would have to be hosted) and an API key.

@gauntface and I were just discussing this. One alternative is that we treat this strictly as an optional post-deploy task and simply open up the PageSpeed service URL in the browser.

Advantages:

• No API key needed. No rate limiting
• You get the pretty pictures and helpful UI
• You get links to the docs

Any opinions on how we should proceed here?

Docs list support for BlackBerry 1.0

Documentation says support for BlackBerry 1.0, probably should read BlackBerry 10
README.md, line 112

CSS + Styleguide Usage

At the moment the main index.html page pulls in h5bp.css and main.css.

h5bp.css

Has some CSS which is "opinionated defaults". These should be rolled into the style guide - opinionated defaults is what the style guide is for

Pull in styles.css

At the moment the main index.html doesn't pull in the styles which means the style guide is complete separate. My gut instinct is that we should pull in styles.css into the main page and use uncss to remove it OR expect the user to be using tooling, in which case create a "main.sass" and import the necessary styles from sass files which build into the styleguide.

Since we know what the default styles will be for main.sass would could include a build of main.css so non-tool using developers will have the same styles between styleguide and index.

Perhaps name the imported styleguide styles to "imports.sass" and "imports.css"

Todos

• BrowserSync for LiveReload
• Integrate styling
• Integrate static style guide
• Figuring out how better to integrate PatternLab minus the cruft in the current setup (ideally your gulpfile generates the styleguide too). Might be worth keeping in mind https://github.com/assemble/assemble-pattern-lab etc.
• Figuring out whether we should add https://www.npmjs.org/package/stream-throttle as an option for bandwidth throttling
• Hooking up pagespeed. Is there a gulp-pagespeed? equiv of grunt-pagespeed basically.

Include Sass

I spoke with Addy regarding this, to sum up:

1.) I think Sass is super useful and new dev's would benefit from it, flip side, it could be overwhelming for someone starting out.
2.) If we agree to use Sass, which Sass plugin is the most appropriate / reliable

What does it mean to check out a starter file?

Is it just the case of 'git add index.html' to be able to commit changes made to index.html or are there more dependencies on this checkout?

Support for optional screenshot generation?

Review: https://www.npmjs.org/package/gulp-local-screenshots/

Menu line-height issue

@gauntface I just noticed this in the desktop view when condensed down. Is the line height difference here intentional?

Silly question-- do tools optimize app files and files in dist output folder?

With that silly question in mind-- say I update an image in the app/image folder....

I'm wondering as part of development workflow if I should do a git add on the image in app/image folder, or do I add the output in the dist folder? Or maybe both?

Can we improve styles for section class="main-content"?

Feels like the section class should play nice with the menu bar. Right now, it doesn't.

Addressing Context

There's a number of ways you can build a multi-device project. That said, from my experience, you don't always want to ship the same experience for every context.

It goes without saying, the more you know about a user's environment the better equipped you are to serve an optimal experience.

I'm wondering: Will we reference or include projects that look to provide insight to context? (like the few I've listed below) Also, will we try to standardize or consolidate a design approach for developing with context in mind? I think this project would be perfect to do just that.

The below are a number of examples to approach developing an experience based on a unique context. I think we could definitely work to provide a standard way to develop with these tools or structure your project to best tackle this issue.

Examples of current solutions/approaches to context

IE conditional comments (browser detection)

<!--[if IE]><html class="ie"><![endif]-->

.ie .component { ... }

@media queries (viewport detection)

@media (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi) {
  .component { ... }
}

@supports (feature detection)

@supports (animation-name: test) {
  .component { ... }
}

matchMedia() (feature detection) https://github.com/paulirish/matchMedia.js

if( matchMedia('tv').matches ) { ... }

Modernizr (feature detection) https://github.com/Modernizr/Modernizr

if ( Modernizr.touch ) { ... }

UA-Parser (browser, os & device detection) https://github.com/tobie/ua-parser

var r = require('ua-parser').parse(navigator.userAgent);
if ( r.device.family.toLowerCase() == 'iphone' ) { ... }

DevTools port forwarding and screencast support

@PaulKinlan reported that WSK wasn't working with DevTools screencast support. I went about trying to reproduce this.

In order to get port forwarding working with the kit, you need to use the second of the IP addresses supplied (i.e the external friendly one) when running gulp watch. In my case this was 192.168.152.2:3002. You then need to map this to your desired port making sure that both your device and desktop are of course on the same network.

This may be worth documenting. I would also add a note to say that if someone absolutely cannot get this working using the addresses we provide with Gulp watch, a low-fi fallback is to run a local Python simpleHTTPServer in the root directory, which of course works with port forwarding as expected.

Some screenshots of this working:

How exactly does gulp jshint work?

I purposefully added a bug in my JavaScript, and saved the script. The script disappeared from the staged version, but jshint wasn't run in the terminal and no errors were reported.

I fixed the bug, jshint ran in the terminal, and the script started to work again.

I would expect to see the error reported.

Build process: tasks

Off the top of my head:

• Image optimization
• JS concat and minification
• CSS concat and minification
• HTML minification
• BrowserSync
• PageSpeed Insights

Under consideration:

• Support for cloud device testing (BrowserStack)
• Responsive images. Too much?
• Autoprefixer
• Removing unused CSS
• Do we try baking in Telemetry support? V2?

For now, no or out of scope:

• Sass / Compass
• CoffeeScript
• Usemin / Useref
• RequireJS

I think it's important that we provide the best tools for perf optimisation and cross-device testing whilst trying to keep in mind that a verbose build file is gonna scare people off.

Licensing update

We've spoken to the Google OSS licensing team again and have negotiated moving the CC messaging from any HTML or CSS (.css, .sass) files to the main LICENSE file. This should make things more readable.

Furthermore, the messaging now in the LICENSE has been revised to indicate that although the markup and styles in this project are CC, all derivative work created by the user maintains their copyright and not ours nor Google's.

The licensing in JS is going to stay the same, but as we don't really have that much script in this project I think we should be fine.

cc @sindresorhus @paulirish @passy @ianbarber so you're aware.

What's the deal with 'enable compression' rule failing on PageSpeed Insights?

So yay, my user experience score is 100 using Web Starter Kit, index.html.

But I'm failing Speed rule-- compression isn't enabled.

Is there a logical reason why this is for staging (I'll document it)?

How do I enable compression as part of build step?

Markup review

Update: many of these have now been addressed.

Having gone through the release of h5bp and its lifetime, I think the current state of the markup in w-s-k is too heavy. There are some things in here that are low value and unnecessary.. but some higher value things that I think could be considered to be a non-default as they just add to perception that this is too heavy and bloated. We can avoid that, while still delivering a lot of value with the project.

I'm sorry that I dumped a bunch of issues into a single ticket. :(

Details below.

---

       <meta name="HandheldFriendly" content="True">
        <meta name="MobileOptimized" content="320">

These are in for barely legitimate reasons. It's time for them to die.

---

<meta http-equiv="cleartype" content="on">

cleartype

cleartype on for mobile IE? Lets let mobile IE handle its own type rendering. This is the sort of feature that will be considered bloat.

---

#### touch-icons, favicon

h5bp killed the markup reference for these.
h5bp/html5-boilerplate#1367
It makes the markup feel wayyy better. let's copy that.

---

   <!-- Tile icon for Win8 (144x144 + tile color) -->
        <meta name="msapplication-TileImage" content="images/touch/ms-touch-icon-144x144-precomposed.png">
        <meta name="msapplication-TileColor" content="#3372DF">

This also feels low-value. I would prefer it's in https://github.com/h5bp/html5-boilerplate/blob/master/doc/extend.md and we say, consider whats in there if you want.

---

   <!-- Disable Tap Highlight for Windows Devices -->
        <meta name="msapplication-tap-highlight" content="no">

why disable?

---

#### prevents links from opening in Mobile Safari.

seems risky.

---

#### microdata

does it really make sense to declare every page built with this as a Article?
and meanwhile also default to being a standalone app?

---

 <meta name="created-with" content="Web Starter Kit">

This isn't valid, nor registered. http://wiki.whatwg.org/wiki/MetaExtensions

---

<!-- SEO: If mobile URL is different from desktop URL, add a canonical link to the desktop page -->
        <!--
        <link rel="canonical" href="http://www.example.com/" >
        -->

I swear that google recommends a different pattern for defining the mobile site vs desktop site. It's in Smus's multidevice h5r article from a while ago.

---

#### styles difference

what's the difference between what's in styles.scss vs main.css ?

---

<html class="no-js no-touch" 

are no-js and no-touch removed somewhere?

Running gulp watch from within the app directory doesn't launch a working server

Try running gulpjs from within the app directory - the server starts and opens a tab but the server doesn't actually work.

Style guide: add code-blocks for recreating elements.

I.e in typeography say it is <h1> etc.

Same with grids etc.

Search box in mobile view does not appear when clicking on the magnifying glass

Homepage content

1-2 lines of text for each feature we offer. Maybe with some iconography (which I can help source)

• Multi-screen optimized boilerplate
• Responsive layouts
• Living Component Style guide
• Live-reload
• Cross-device sync: scroll, click, navigation
• Sass out of the box
• Build-process
• Optimizes images
• Concats/minifies CSS
• Concats/minifies JS
• PageSpeed launcher

Delete-key friendly. Easy to remove what you don't use.

Maybe a strap-line about the project. Web Starter Kit helps you build multi-screen webapps with ease.

Should we include support for UnCSS?

If we do we should include a one liner about how to remove it.
https://github.com/ben-eb/gulp-uncss

Add support for HTML minification

Tested with: https://googledrive.com/host/0BxcraNy3sgspLVdlZmQyZjB2WVk/index.html

We're currently doing well on PageSpeed scores. One thing I noticed was missing is that we currently don't appear to minify HTML (I thought we had this at one point). We can get that added fairly easily.

Browser testing results.

For anyone that needs a live semi-public URL for testing, I'm using:

https://googledrive.com/host/0BxcraNy3sgspUElwZU9KNlM4aU0/index.html

Should npm install automatically install gulp?

I had to manually install gulp (sudo npm install gulp-g)-- it didn't install as part of npm install.

Also, does the order matter here? So after npm install and gulp install, will I have all the gulp plugins that I need?

Search box is not input type=search

It should be.

Port Forwarding doesn't work

It is not possible to set up port forwarding after doing a gulp watch. If you enter the IP addresses in Chrome's port forwarding config and then make a request to the server the server will not return a response and instead lock.

Homepage

This is how the page is collapsing on my machine: ff v30.0 Ubuntu

Boilerplate: CSS library

Sushi is targeting a 60fps experience from the get-go, meaning that we have high performance requirements of any CSS library that we opt to suggest.

We also want to make sure that the solution we provide is small, focused and offers sufficient CSS UI components to be useful to developers that want a basic, clean UI for the apps they are building.

Libraries currently under consideration:

• TopCoat
• PureCSS
• Ionic
• Foundation

Note that this is a preliminary review and any benchmarks used are nuanced and should only be used as a rough guide.

Line endings in `.gitattributes`

I'm always wondering what's the best default, if the one you guys have now * text=auto or * text eol=lf that enforces the lf line endings —which are a pain in the ass if developers work on different environments like Linux or Windows.

What do you think?

Make it a download too.

Can you make it a download too (and have the documentation reflect that). I don't want people to have to install git.... If you have git, all is cool and you can clone. But those who can't I want them to DL a zip file.

Target devices

How old devices should we target?

100% PageSpeed score is not a thing. (README.md)

The scores are numbers and not percentages (a nit I know - sorry)

Add a project specific metatag so we can find projects using us

Meta-tag or comment?

e.g

<!-- Built with love using Web Starter Kit -->

or

<meta name="created-with" content="Web Starter Kit"/>

Any other ideas?

Build process: Grunt or Gulp

Sushi is going to include minimal tooling for building a fast, multi-device experience. We're also aiming to be useful for developers who fall into the beginner or intermediate camps.

With this in mind, should we be using Grunt for this project or Gulp? Most of us find Gulp incredibly easy to work with and the files easy to read, but I think Grunt will probably make more sense for this project. Lower barrier of entry + larger ecosystem + maturity.

Thoughts?

Btw: @ianbarber is looking at building either a desktop app for Sushi that you can drag/drop a directory in to build your project (for those terrified of the command-line) or build-tools as a service. We'll share some more info on this once it's clearer which of them is feasible.

Boilerplate: Basic layout

I've landed basic layout for the project in sample.html, but I wonder if we should aim to provide something more prescriptive that demonstrates how to handle say, view switching. Is that too much? Worth including?.

cc @ianbarber

Decide on how we consume/offer PatternLab

The way I've seen a few developers use PatternLab is by including the patternlab-node repo as part of their patterns directory, allowing them to just use the default build process for generating the style guide.

This allows your main build process and pattern process to be separate. Unfortunately, this isn't very clean and as we're using Gulp would mean using two different build systems (Grunt AND Gulp).

We have a few options for how we can work around this.

1. Only include the output of patternlab-node (CSS and or Sass files) in Sushi. If a developer wants to generate their own they will need to install patternlab-node and we can provide instructions of how to do so. Cons: effort by the developer to make use of PatternLab.

2. Re-write the patternlab build process so that it can be called from our Gulpfile. This allows the user to have one place where they can look for all of their build tasks. I believe https://github.com/growdigital/creeky/blob/master/gulpfile.js tried to do something similar. Cons: slightly beefier Gulp file.

3. Use something other than patternlab for generating the styleguide and styles for the project. PatternLab is used by lots of RWD designers as a baseline so it would be useful to stick with it if possible.

Broken layout in latest Firefox (29.0.1)

Trim down the Styleguide styles

Kill the browsersync pop up

It's just annoying during development.

Some bugs we need to fix pre-launch

• If you try to extend index.html with your own content, you will catch some things. e.g. Side Menu doesn't close when a link is selected (I was linking to in-page content).
• <body> needs a min-height:100%, else it's boundaries are squished up at the top, while the content is flowing out.
• Furthermore, scrolling up literally scrolled the boundaries of the div up, as opposed to leaving the divs placement as is, and scrolling the content in it. (iOS)
• Had to add a z-index of 1 to both the header and nav, otherwise the clicks in the nav area fall through to the content of behind it
• Also need an overflow:hidden or text eclipsing in the header, as on mobile, titles longer than a couple words go out into the document

Accessibility review

In @alice's own words "pre v1.0 is the best time for a11y review" :)

Pieces to review:

• Layout boilerplate in /app (index.html, basic.html)
• Style guide (app/styleguide)

If you have any further suggestions, please feel free to shout.

Clean-up samples

@ianbarber do you know what the plans are around samples for Web Fundamentals before I/O? e.g will they be getting moved to their own repo.

At the moment we include three selected directories of them as part of this project.

They could be linked up to the index but before doing any changes to whats there I just thought it would be useful to touch base.

Improve PageSpeed scores [currently: 89/100]

https://8fc5908aefbc10e402bb4a2c06976a46c88f04e4.googledrive.com/host/0BxcraNy3sgspZ2hIT1BBNWxGZXM/index.html

Current scores: