kotsu

Advanced Web Starter Kit

To boldly go where no man has gone before

---

How to use

1. Clone or download and unpack to desired location
2. Download and install latest version of node.js
3. Install grunt-cli globally: npm install -g grunt-cli
4. Install jspm globally: npm install -g jspm
5. Install GraphicsMagick (recommended) or ImageMagick for your OS. Note: it's mandatory to install one of them before running npm install
6. Set your environment variables [guide]
7. Install project dependencies: npm install
8. (optional) Add your repository to Travis for automatic tests
9. (optional) Set up Continuous Deployment with CircleCI or Werker Docker following our guide
10. Code live with: npm start or npm start -- --hmr if you need Hot Module Reloading
11. Build with: npm run build
12. Deploy and enjoy your life

What's inside?

• Reasonable structure for frontend projects
• Static pages generation
• Prepared configs for quick Continuous Deployment and automatic tests setup
• Grunt with pre-configured tasks
• Nunjucks, a full featured templating engine
• In-built Nunjucks globals and filters for formatting numbers, dates, getting current page url, locale, breadcrumb, etc.
• Human readable urls
• Boilerplate files based on best practices
• i18n with node-gettext and configured layouts to properly declare current locale and alternate urls
• Sass compiler with source maps generation, autoprefixing, optimization, minification and linting
• Ekzo Sass framework
• JSPM with ES6 support, managing and bundling JavaScript dependencies and optional hot module reloading or blazing fast watch
• standard for linting and automatic formatting JavaScript
• Live reload powered by Browser Sync
• Runtime type annotation and data validation with tcomb and tcomb-validation, built-in handy refinements.
• Preconfigured meta tags for Open Graph and Twitter Cards
• Commonly used by search providers structured data based on RDFa
• Automatic sitemap.xml generation with grunt-sitemap-xml
• Automatic sprites generation with Spritesmith
• Automatic images compression via TinyPNG
• Automatic responsive images generation with grunt-responsive-images
• Separate not optimized files in development, and
• Compiled and minified files for production

And a lot more under the hood. We just didn't have time to document all features. Yet.

Documentation

Work in progress

• Structure
• Environment variables
• Data
• Structured data
• URLs
• Continuous Delivery
• Recipes

Examples

Deployed version of Kotsu from master branch can be found here.

Note that Examples section so far features only least part of predefined elements and features.

Browsers support

JavaScript

IE	Edge	Chrome	Firefox	Safari	Opera	Opera Mobile	iOS Safari	Android
9+	12+	21+	28+	6.1+	12.1+	12.1+	7+	4+

To enable ES6 features in IE11 and below, uncomment import 'babel-polyfill' in main.js. See details here.

Default build shipped with jQuery 3.1.0+ which doesn't support IE8. Replace it with pre 3.0.0 version if you need support of IE8.

CSS

IE	Edge	Chrome	Firefox	Safari	Opera	Opera Mobile	iOS Safari	Android
10+	12+	21+	28+	6.1+	12.1+	12.1+	7.1+	4.4+

Refer to Ekzo Browsers Support section for details about graceful regression for IE9 and below, which included in Kotsu by default.

To disable graceful regressions for older IE, remove IE() macro call from base layout.

Outdated Browser message

In IE9 and below users will see banner before page content with message about outdated browser and link to Outdated Browser.

To disable Outdated Browser message, remove OutdatedBrowser() macro call from base layout.

License

Copyright 2014 LotusTM. Licensed under the Apache 2.0 license.

Changelog

1.15.0 - 2019-08-06

Added

• [scripts][grunt][tasks] Added basic service worker with Network-first caching strategy, all related scripts and JSPM Grunt configuration. #384

• [grunt] Added ability to exclude pages building by simply specifying _ in the beginning of the directory

  Previously:

  • /templates/test/page.nj — build
  • /templates/_test/page.nj — build
  • /templates/test/_page.nj — exclude
  • /templates/_test/_page.nj — exclude

  With update:

  • /templates/test/page.nj — build
  • /templates/_test/page.nj — exclude
  • /templates/test/_page.nj — exclude
  • /templates/_test/_page.nj — exclude

• [templates] Google Global Tag (Google Analytics) and Yandex Metrica will now track app version by default (note that Google Global Tag requires additional configuration of dimension in admin panel).

• [static][templates] Added favicon-16x16.png and favicon-32x32.png. Some browsers like Chrome refusing to use favicon.ico in their stead.

• [package] Added NPM scripts lint:scripts and lint:styles to quickly invoke linting of scripts or styles-only.

• [configs] Forced standard to lint jsx files too.

• [modules] Added new tcomb refinements:

  • MsDate — expect timestamp in ms
  • DigitString — expect strings with digits only
  • Email — expect valid email

• [modules] Grunt task writeJSON now allow to compile into json file or into js file with ES6 exports (which allows it to be effectively destructured and tree shacked).

• [tests] Added better Jest watch experience with jest-watch-typeahead.

Changed

• [package] Updated dependencies:

  • autoprefixer to 9.6.1
  • babel-eslint to 10.0.2
  • gettext-parser to 4.0.1
  • grunt-contrib-clean to 2.0.0
  • grunt-contrib-htmlmin to 3.1.0
  • grunt-csso to 2.2.4
  • grunt-sass to 3.0.2
  • grunt-spritesmith to 6.7.1
  • grunt-uncss to 0.8.6
  • grunt-webfont to 1.7.2
  • grunt to 1.0.4
  • hash-sum to 2.0.0
  • jest to 24.8.0
  • lodash to 4.17.15
  • lru-cache to 5.1.1
  • markdown-it to 9.0.1
  • numbro to 2.1.2
  • onecolor to 3.1.0
  • snazzy to 8.0.0
  • sprintf-js to 1.1.2
  • standard to 13.1.0
  • stylelint-config-standard to 18.3.0
  • stylelint-scss to 3.9.3
  • stylelint to 10.1.0
  • time-grunt to 2.0.0

• [submodule] Updated Ekzo to 2.7.1 which included fixes of the linting errors.

• [templates] Replace Google Analytics with newer Google Global Tag.

• [templates] Replace Yandex Metrica with v2.

• [scripts] Improved logging of the site info to the console:

  - Kotsu v1.10.0 #23, SHA1 e9e5043d16df6d8f03b4a328407a75d711182ebe
  + Kotsu v1.10.0+23.e9e5043d16df6d8f03b4a328407a75d711182ebe, production (staging)
  

• [grunt] Changed tasks to Explicitly call clean:build and clean:temp instead of the generic clean to avoid accidentally cleaning everything when users adds additional cleaning tasks.

• [grunt] Styles sourcemaps are now preserved after build.

• [grunt] Ensured CSS sourcemaps to be generated when using CCSO.

• [grunt] Changed styles watcher to watch for all *.scss files in source and temp directories instead of only styles directory. That's nice addition for projects which prefer to group component's scripts and styles.

• [grunt] Updated grunt-sass task configuration to work with new implementation option.

• [grunt][data][configs] Precompile scripts data into ES6 JS file scripts.js instead of the JSON-file to make it tree shakable. It also makes it possible to be used directly by 3rd-party scripts, like Jest, without the need to run again whole compilation which due to Grunt massiveness can take some time.

• [templates] Renamed components and layouts Nunjucks files to not use leading _ in names since due to changes in related Grunt task configuration it is enough to use leading _ in directory that houses them to prevent building into standalone pages.

• [data] Made SOCIAL.url optional since in some cases social service might not require one.

• [data][templates][locales] Provided better default placeholders. Instead of too abstract company added following properties:

  • name — project name
  • shortName — project short name
  • description — project description

• [config] Enabled some new Stylelint rules:

  • unit-no-unknown
  • block-opening-brace-newline-after
  • block-closing-brace-newline-before
  • string-no-newline
  • no-empty-source
  • selector-max-pseudo-class
  • no-empty-first-line
  • function-calc-no-invalid
  • at-rule-property-requirelist
  • max-nesting-depth: added ignoring of the pseudo-classes
  • scss/dollar-variable-colon-newline-after: always-multi-line
  • scss/at-each-key-value-single-line: true
  • scss/function-quote-no-quoted-strings-inside: true
  • scss/function-unquote-no-unquoted-strings-inside: true
  • scss/selector-no-union-class-name: true
  • scss/comment-no-loud: true

[configs][package] Make Jest use for @data mapping precompiled temporary file temp/data/scripts.js instead of the modules/scripts-data.js. That makes tests running significantly faster because it avoids precompilation of the data for each test file. To make it work, pretest NPM script has been added, which ensures that data is always precompiled before running any tests.

Fixed

• [modules] Fixed grunt-jspm not counting built files properly.
• [modules] Fixed lru-cache initialization — newer versions should always use new keyword.