apptension-tools

# apptension-tools [![Build Status](https://secure.travis-ci.org/apptension/apptension-tools.png?branch=master)](https://travis-ci.org/apptension/apptension-tools) ## Description What is `apptension-tools`? * is an opinionated set of tools used by Apptension for development, * is a way to unify infrastructure between various projects, * contains predefined gulp tasks, * contains predefined webpack configuration, * uses eslint to lint your code, * allows you to write in ES6 out of the box, * reduces time necessary to bootstrap your project, * includes multi-environment support. ## Predefined Gulp tasks Apptension-tools contains a set of gulp tasks that you can use in your project. Here you will find each of those briefly explained. Most of them behave a bit differently depending on environment in which they are run. ### BrowserSync Launches browserSync server. ###### Development It will proxy all the calls to webpack dev server. ###### Production It serves files from `dist` directory. Useful to check your build. ### Clean Deletes `.tmp` and `dist` directories together with their content. ### CompileIndex Compiles handlebars template to produce html file. It supports multiple entry points. ###### Development Injects webpack dev server script. ###### Production Removes development scripts. ### CopyBackend ###### Development Not applicable. ###### Production Copies whole `backend` directory to `dist`. ### CopyProduction ###### Development Not applicable. ###### Production Copies all files that contain `*.production.*` in their name from current working directory to `dist`. It removes the `production` part. ### CopyPublicAssets Copies `app/public` directory to output dir. ###### Development Output directory is `.tmp`. ###### Production Output directory is `dist`. ### Eslint It lints all script files in project based on `.eslintrc` file. ### Images Copies files from `images` directory to output dir. ###### Development Output directory is `.tmp`. ###### Production Output directory is `dist`. Also applies imagemin. ### Karma Launches karma server in `test` environment. ### Rev ###### Development Not applicable. ###### Production Appends random hash to styles and scripts filenames in order to bust browser's cache on subsequent deploys. It generates rev manifest file that is later used by CompileIndex task. Outputs files to `dist` directory. ### Rev-replace ###### Development Not applicable. ###### Production Replaces all paths to assets in `.html`, `.js` and `.css` files with those produced by `rev` task. ### Sass Compiles sass files into css using [node-sass](https://github.com/sass/node-sass). It is not a part of the webpack build process in order to support sprites generation. Files are written to `.tmp` directory. ###### Production Additionally css is minified. ### Spritesmith Generates sprites from images located in `app/images/sprites` directory. It expects that retina images are present and are suffixed with `-2x.png`. It also generates sass file that contains variabled and mixins necessary to use images included in the sprite. Example of usage: ```scss .icon-example-filename { @include retina-sprite($example-group); } ``` In above example the task expects those two files to be present in sprites dir: * exampleFilename.png * exampleFilename-2x.png where former is **exactly** twice as big. In case it is not, the task will fail. ### Webpack By default it takes `app/src/main.js` as an entry point and produces bundle out of it. It also can spawn webpack dev server when `watch` argument passed to factory function is `true`. #### node_modules Primarily you should use `npm` as a dependency manager. #### bower_components You can require bower components by using relative path. #### vendor_modules It is a predefined alias. You can put libraries downloaded from other sources into `vendor_modules` directory residing in root. Those can later be used with: ```js import vendorExample from 'vendor_modules/vendorExample'; ``` #### vendor-styles.css All css files required in javascript will be extracted to `vendor-styles.css` which you can add to your index file template. Remember to use `assetPath` helper. ###### Development Additionally includes source maps. By default webpack's devtools are set to `eval` as it is the fastest option. ###### Production Additionally uglifies the script. #### \_\_DEBUG\_\_ Webpack task uses [DefinePlugin](https://webpack.github.io/docs/list-of-plugins.html#defineplugin) to set `__DEBUG__` variable. It allows you to include specific blocks of code only in development bundle. ###### Development ```js if(__DEBUG__) { // this will be included in development bundle } ``` ###### Production ```js if(__DEBUG__) { // this will not be included in production bundle } ``` ### zip ###### Development Not applicable. ###### Production Compresses `dist` directory to `dist.zip`. ## Configure tasks Tasks can be configured through Gulpfile. ```js var tasks = require('apptension-tools/gulp')({ // insert config options here }); ``` ### Options #### port type: `number` Default: '8000' Port of webpack dev server. #### domain type: 'string' Default: '0.0.0.0' Domain of webpack dev server. #### webpack type: 'Object' `webpack` configuration object. Check webpack's [documentation](https://webpack.github.io/docs/configuration.html) for complete option's list. #### webpackDevServer type: 'Object' `webpack-dev-server` configuration object. Check webpack's [documentation](https://webpack.github.io/docs/webpack-dev-server.html)' for complete option's list. #### sass type: 'Object' `node-sass` configuration object. Check [github page](https://github.com/sass/node-sass) for complete option's list. #### karma `gulp-karma` configuration object. Check [github page](https://github.com/karma-runner/gulp-karma) for complete option's list. ## Known issues * As of now due to a bug in autoprefixer sourcemaps for sass are not generated.