# nikita kickstarter - <%= config.get('template') %> - <%= config.get('jsFramework') %>

This is our toolbelt how to start a new project from scratch. It is generated by [generator-nikita](https://github.com/nikita-kit/generator-nikita) powered by [yeoman](http://yeoman.io/).
Feel free to re-run the generator to change or update the nikita kickstarter with `npm run generator`.

If you want to know more about folder structure, coding standards and conventions, please have a look at our sub projects:

* [nikita.html](https://github.com/nikita-kit/nikita-html)
* [nikita.css](https://github.com/nikita-kit/nikita-css)
* [nikita.js](https://github.com/nikita-kit/nikita-js)



## Requirements

<% if (config.get('features').includes('docker')) { -%>
- [__Docker__](https://www.docker.com/)

  OR
<% } -%>
- [__Node.js__](http://nodejs.org) >= 8
- [__Grunt CLI__](http://gruntjs.com/getting-started)(optional) – install with `npm install -g grunt-cli` or use `npm run grunt`


## Project-Setup

- [__Grunt__](http://gruntjs.com/) – JavaScript task runner
- [__Webpack__](https://webpack.js.org/) – module bundler
- [__Babel__](https://babeljs.io/) – next generation JavaScript compiler
<% if (config.get('jsFramework') === 'react') { -%>
- [__React__](https://reactjs.org/) – JS library for building user interfaces
<% } -%>
- [__twigRender__](https://github.com/stefanullinger/grunt-twig-render) – static site generator
<% if (config.get('jsFramework') === 'jsb') { -%>
- [__EJS__](http://ejs.co/) - client side templates
<% } -%>
- [__SCSS__](http://sass-lang.com/) with [__LibSass__](http://libsass.org/) – css preprocessing
- [__PostCSS__](http://postcss.org/) – css postprocessing
- [__Jest__](https://facebook.github.io/jest/) – JS testing framework
- [__ESLint__](http://eslint.org/) – linter for JS files
- [__stylelint__](https://stylelint.io/) – linter for SCSS files
- [__Browsersync__](https://browsersync.io/) – synchronised browser testing


## Getting started

<% if (config.get('features').includes('docker')) { -%>
1. launch docker node container with `make node-cli`
<% } -%>
1. run `npm install` - install dependencies
1. run `grunt` – start dev build script
1. open [http://localhost:3000/](http://localhost:3000/) – watch your build-directory in the browser
* run `grunt dist` – start distribution build script

If you want to specify a different port, you can start the script with the `--port` option:
`grunt --port=9000` will launch the Browsersync webserver on [http://0.0.0.0:9000/](http://0.0.0.0:9000/) and will start the Browsersync UI on port 9001 (= 9000 + 1).
If a port is already in use, BrowserSync will auto detect that case and increases the port number until a free port is found.


## Project structure

The nikita-setup provides the three main folders `<%= config.get('rootFolder') %>src/`, `<%= config.get('rootFolder') %>static/` and `grunt/`.
All source-files will be put to the `<%= config.get('rootFolder') %>src`-folder like html templates, js- and scss-files.
These files will be processed by several grunt tasks and then stored in the `<%= config.get('rootFolder') %>static/generated/`-folder.
Depending whether you called `grunt` or `grunt dist`, these files are minified or not.

Besides these generated files, several other static files like images will be put into the `<%= config.get('rootFolder') %>static/`-folder.

In the `grunt`-folder you find the task configurations and custom grunt tasks.
Have a look at `grunt/aliases.js` to see all available task group definitions, aliases and options.

```
<% if (config.get('features').includes('docker')) { -%>
├── .docker
<% } -%>
├── grunt
│   ├── config
│   ├── tasks
├── <%= config.get('rootFolder') %>src
│   ├── components
│   ├── html
│   │   ├── data
│   │   ├── macros
│   │   ├── layouts
│   │   ├── pages
│   │   └── partials
│   ├── js
│   ├── scss
│   │   ├── bg-svg-icons
│   │   ├── blocks
│   │   ├── extends
│   │   ├── mixins
│   │   └── variables
│   └── tests
│       └── setup
├── <%= config.get('rootFolder') %>static
<% if (config.get('features').includes('webfonts')) { -%>
│   ├── fonts
<% } -%>
│   ├── generated
│   └── img
│       ├── appicons
│       └── temp
└── tmp
```


## HTML

For the HTML structure, please have a look at [nikita.html](https://github.com/nikita-kit/nikita-html). This sub project
describes the HTML coding standards and conventions.

the `src/html`-folder provides an static-page-generator based on twig.js. It aims to be an alternative to assemble.io.
See the [twig documentation](http://twig.sensiolabs.org/documentation) and the [twig intro for designers](http://twig.sensiolabs.org/doc/templates.html) if you wonder how twig is working in general.
You can add custom twig functions, filters and tags in the grunt config file at `grunt/config/twigRender.js`.
See the [grunt-twig-render documentation](https://github.com/stefanullinger/grunt-twig-render) for examples.
Also, you find a list of supported twig features in the [twig.js wiki](https://github.com/twigjs/twig.js/wiki).


## CSS

For the CSS structure, please have a look at [nikita.css](https://github.com/nikita-kit/nikita-css). This sub project
describes the CSS coding standards and conventions.

The master layout at `src/html/layouts/master.twig` includes the main stylesheet `styles.css`.

We use Foundation as (S)CSS framework.
In our default setup only the settings and mixins are loaded.
Feel free to activate more Foundation features by changing `src/scss/foundation.scss` and modify settings at `src/scss/variables/_foundation-settings.scss`.
We strongly recommend to use [Foundation Grid](https://foundation.zurb.com/sites/docs/xy-grid.html#importing) and [Foundation Breakpoints](https://foundation.zurb.com/sites/docs/media-queries.html#sass) mixins if needed.
Please take a look at [Foundation Docs](https://foundation.zurb.com/sites/docs/) for more information.


## JavaScript

For the JS structure, please have a look at [nikita.js](https://github.com/nikita-kit/nikita-js). This sub project
describes the JS coding standards and conventions.

The master layout at `src/html/layouts/master.twig` includes the JavaScript at the end of the file (before the closing `</body>` tag).

The `static/generated/main.js` file is generated by webpack.
This file contains everything, which is `require`d or `import`ed in your JS entry files (`src/js/_main.js` by default).
Aside from modules, babel will add all needed polyfills according to browserlist declaration at `Gruntfile.js` automatically for you.
<% if (config.get('features').includes('modernJsBuild')) { -%>

For modern browsers, another file `static/generated/main.modern.js` is generated.
It's the same as main.js file but without polyfills and transformations that modern browsers don't need.
<% } -%>

Run `grunt analyze-js` to see bundled content of `static/generated/main.js` as convenient interactive zoomable treemap.

For environment specific code, you can check `process.env.NODE_ENV` for `development` or `production`.
Besides that, any values from `.env` file can be accessed with `process.env.<NAME>`.

Please check [webpack docs](https://webpack.js.org/guides/code-splitting/) if you're interested in code splitting to speed up loading time.

<% if (config.get('jsFramework') === 'jsb') { -%>
Within the JavaScript modules it's also possible to use client side templates with EJS syntax (see sample component).
<% } -%>

### Libraries included

<% if (config.get('jsFramework') === 'react') { -%>
- [react](https://reactjs.org/)
- [react-router](https://reacttraining.com/react-router/web/)
- [react-waterfall](https://github.com/didierfranc/react-waterfall)
- [react-helmet-async](https://github.com/staylor/react-helmet-async)
<%     if (config.get('libraries').includes('react-select')) { -%>
- [react-select](https://react-select.com)
<%     } -%>
<%     if (config.get('libraries').includes('swiper')) { -%>
- [swiper](http://idangero.us/swiper/)
<%     } -%>
<%     if (config.get('libraries').includes('react-a11y-dialog')) { -%>
- [react-a11y-dialog](https://github.com/HugoGiraudel/react-a11y-dialog)
<%     } -%>
- [classnames](https://github.com/JedWatson/classnames)
- [prop-types](https://github.com/facebook/prop-types)
- [logging.js](https://github.com/DracoBlue/logging-js)
<% } else { -%>
- [jsb](https://github.com/DracoBlue/jsb)
- [logging.js](https://github.com/DracoBlue/logging-js)
<%     if (config.get('libraries').includes('choices')) { -%>
- [choices](https://joshuajohnson.co.uk/Choices/)
<%     } -%>
<%     if (config.get('libraries').includes('swiper')) { -%>
- [swiper](http://idangero.us/swiper/)
<%     } -%>
<%     if (config.get('libraries').includes('a11y-dialog')) { -%>
- [a11y-dialog](https://github.com/edenspiekermann/a11y-dialog)
<%     } -%>
<% } -%>
<% if (config.get('libraries').includes('lodash')) { -%>
- [lodash](https://lodash.com/)
<% } -%>
<% if (config.get('libraries').includes('date-fns')) { -%>
- [date-fns](https://date-fns.org/)
<% } -%>


## Components

If you have small, independent and reusable modules, this is the right place for it.
Just store your component files in a subfolder of the `src/components`-folder and all files will be processed by the grunt tasks.
This way you have all related files at one single place. Supported are JavaScript Files, EJS templates, SCSS partials, twig partials and test files.


## Tests

You'd like to test your JavaScript code? The kickstarter comes with Jest testing framework<% if (config.get('jsFramework') === 'react') { %> and Enzyme<% } %>!
Just add your tests at `src/tests`-folder with `.test.js`-suffix and run `grunt test`. To launch Jest in watch mode, just run `grunt test --watch`.
If you're interested in code coverage, run `grunt test-coverage`.


## Code linting

The kickstarter comes with tasks for linting your JS and SCSS code.
Just run `check-css` or `check-js`.<% if (config.get('features').includes('preCommitHook')) { %>
In addition, the SCSS and the JS code linting will be executed as a pre-commit hook.<% } %>
This ensures a basic code style in nikita projects.
Run `grunt fix-scss` or `grunt fix-js` to call the linter with the `--fix` option.
This will fix most of the common problems like indention, brace style and style property order automatically.
Run `grunt check-code` or `grunt fix-code` to lint SCSS and JS in a row.


## Images

Put all your images-files into `static/img`-folder.
If you wont to minify your source images in the `static/img`-folder using imagemin, just run `grunt minify-images` and commit them.
Imagemin is very expensive, so this step is not part of build task to save time.

### App icons

App icons like favicon, apple-touch-icon or windows tile icon are generated by grunt. A default icons set is already included.
To change this icons, simply change the source image at `static/img/appicons/_source.png` and run `grunt generate-appicons`.
Be aware that this source image should have a minimum resolution of 310x310 pixel.
The related html partial can be found at `src/html/partials/appicons.twig`.

<% if (config.get('features').includes('svgBackgrounds')) { -%>
### SVG images as Data-URIs

To include svg icons as background-images, just put your SVG-icons into `src/scss/bg-svg-icons`-folder.
All SVG-files will be processed with svg2scss-task which creates a sass map containing the SVGs as data-URI strings.
Now you can include your svg icons by using the `_svg-background.scss` mixin. Just type `@include svg-background(name-of-your-icon);`.

<% } -%>
### Temp-Folder

Put your temporary image files in here, e.g. your dummy teaser-images or product-photos, which are included as `img` elements in your layouts.


<% if (config.get('features').includes('webfonts')) { -%>
## Fonts

Put all your webfonts into `static/fonts`-folder and add the style definitions to `src/scss/_webfonts.scss`-file.

<% } -%>
## Questions?

If you're asking yourself »Why not …?« have a look at my [WHYNOT.md](https://github.com/nikita-kit/nikita-kickstarter/blob/master/WHY-NOT.md) file. There we might answer some common questions. :)


## Contributing

Please make contributions on the [generator-nikita project](https://github.com/nikita-kit/generator-nikita#Contributing).


## License

nikita kickstarter is licensed under [CC0](http://creativecommons.org/publicdomain/zero/1.0/): Public Domain Dedication, please see
[NIKITA-LICENSE.md](https://github.com/nikita-kit/nikita-kickstarter/blob/master/NIKITA-LICENSE.md) for further information.