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.13.0 - 2018-03-30

Added

• [grunt] Added grunt-jspm task which allows launch JSPM watch and build within Grunt.

  JSPM no longer needs to be launched with npm-run-parallel and JSPM running process is now synchronous and predictable.

  Besides, new JSPM task able to handle simultaneous watch of multiple packages.

  Note, that task uses child_process.spawn under the hood. Because JSPM does not expose its watch API, for now it is possible to be launched only with CLI.

  #230

• [grunt] Added grunt-jspm-emitter which is responsible for launching chockidar-socket-emitter, which is watching scripts changes and emits them to SystemJS when Kotsu started in Hot Reloading Module mode, with --hmr flag #230

• [package][modules] Added version NPM script and called by it modules/changelog-version.

  This is a small experimental unility, which will run everytime version will be bumped with npm version command, so that you'll never forget to update CHANGELOG version before release. Of course, if CHANGELOG exists at all.

  Note, that to work CHANGELOG should follow keepchangelog.com specs.

• [modules] Added SITE.matter.$raw internal property, which holds not rendered Front Matter.

• [modules] Added cache module which provides a central cache storage and additional method for memoizing function results based on it's arguments or specified cache store key.

  Cache itself based on lru-cache.

  Examples:

  const { cache, cacheFunc } = require('./modules/cache')
  
  cacheFunc(renderFunc)('{{ value }}', { value: 'test' })
  // -> 'test'
  cacheFunc(renderFunc, 'matter')('{{ value }}', { value: 'test2' })
  // -> 'test2'
  
  cache.get('123er23')
  // -> 'test'
  cache.get('matter')
  // -> 'test2'
  

Changed

• [grunt] Replaced shell:jspm_watch and shell:jspm_build tasks with jspm:watch and jspm:build.

  Besides, jspm:watch is now also part of the serve task.

  #230

• [modules] Matter data is no longer rendered ad hoc (by calling getPage(), etc), and instead rendered only once during environment configuration.

  Raw version of same matter is always available under SITE.matter.$raw.

  Beware that due to those changes, in default rendered and cached version page-specific context variables, like PAGE.locale won't be available. Pieces with such variables should be rendered explicitly with render() filter applied to $raw version of data.

• [modules][nunjucks] Nunjucks getPage() no longer renders Matter data and instead returns rendered and cached data.

  For rare cases, when some additional rendering with specific context required, raw pages data available under $raw property.

  {% set item = getPage('/item').props.title %}
  {# -> 'Якась сторінка' #}
  {% set item = getPage('/item').$raw.props.tile %}
  {# -> '={{ gettext("Some page") }}' #}
  

• [modules] Simplified code related to caching of data.SITE.matter and data.SITE.images.

• [modules] It is now possible to import clear-workid module without causing side effects and run it later. Just in case someone want to, let's say, test it... Like we shouldn't test it too...

  Running it with node will work the same way as before.

• [modules] Improved clear-workid output visuals.

Removed

• [grunt] Removed grunt-shell which was used to launch JSPM watch and build. It has been replaced by grunt-jspm which spawns JSPM process #230

• [package] Removed js:watch script, since it is handled by grunt-jspm by now #230

• [package] Removed npm run start-hmr, npm run serve-hmr and related subtasks.

  Just use npm start -- --hmr or npm run serve -- --hmr to launch Hot Module Reloading.

• [package] Removed npm-run-all package, since due to newly added grunt-jspm and grunt-jspm-emitter it no longer used #230

• [templates] Removed Nunjucks getPage() function forceRender and cached options, because getPage() now always returns rendered and cached pages data, while raw version available with $raw property.

Fixed

• [grunt] Fixed async Nunjucks templates not working by updating grunt-nunjucks-2-html to version 2.2.0 vitkarpov/grunt-nunjucks-2-html#56
• [modules] Fixed lack of colors in JSPM output #90
• [modules] Replaced ES6 imports and exports in some module files with Node require and module.exports.