# rtsn [![npm version][npm-image]][npm-url] [![Build status][travis-image]][travis-url]

> A simple front-end development boilerplate/toolkit

__Deprecated: rtsn is no longer in active development and will only receive__
__occasional fixes when stuff breaks. If you're looking for something__
__similar, check out [websn](https://github.com/mserajnik/websn), its__
__spiritual successor.__

rtsn (/ˌɑː(r)tɪˈzæn/) is a boilerplate/toolkit for front-end development using
[gulp](http://gulpjs.com). Its most important features are:

+ [Pug](https://pugjs.org) as template engine __or__ plain HTML – whatever you
prefer
+ [Sass/SCSS](http://sass-lang.com) __or__ [Less](http://lesscss.org) as CSS
preprocessor, complete with autoprefixing, importing from
`node_modules`/`bower_components` (including required assets!) and minifying
+ [Critical](https://github.com/addyosmani/critical) inline CSS for optimized
above-the-fold rendering
+ ES6 transpiling for JavaScript via [Babel](https://babeljs.io) and module
bundling via [Browserify](http://browserify.org)
+ Automatic image optimization for JPGs, PNGs, GIFs and SVGs via
[imagemin](https://github.com/imagemin/imagemin)
+ Automatic copying of everything that doesn't need to be transformed (e.g.,
fonts)
+ Automatic browser refreshing via [Browsersync](https://www.browsersync.io)
with optional [ngrok](https://ngrok.com/) tunneling for sharing the preview
online
+ [Browserslist](https://github.com/ai/browserslist) support for easy browser
version targeting when using Babel and Autoprefixer
+ Project bootstrapping with useful (dot)files
+ Several configuration options to adjust input/output files/directories etc.

## Table of Contents

+ [Install](#install)
  + [Updating](#updating)
+ [Usage](#usage)
  + [CLI](#cli)
  + [Making configuration adjustments](#making-configuration-adjustments)
  + [Using packages from npm or Bower](#using-packages-from-npm-or-bower)
+ [Credits](#credits)
+ [Donate](#donate)
+ [Maintainer](#maintainer)
+ [Contribute](#contribute)
+ [License](#license)

## Install

First, make sure you have [Node.js](https://nodejs.org/en/download) installed.
Using the latest version of Node.js and npm is recommended.

Next, if you don't already have [Gulp](https://gulpjs.com) installed, run the
following command:

```bash
user@local:~$ npm i -g gulp-cli
```

Create a new directory for your project and install rtsn:

```bash
user@local:~$ mkdir <project-name>
user@local:~$ cd <project-name>
user@local:<project-name>$ npm init -y
user@local:<project-name>$ npm i rtsn
```

The installer will prompt you to choose how to handle HTML and CSS in your
project.

After the installation, add your project details to
`<project-name>/package.json` and make configuration adjustments if needed.

### Updating

To update from `3.x` to `4.x` you will need to adjust your `package.json`. See
[here](https://github.com/mserajnik/rtsn/blob/master/install/config.json) for
the current example configuration. Generally speaking, rtsn will add missing
properties when installing, but double-check manually if you run into problems.

You will also need to replace your `.babelrc` and `gulpfile.babel.js` with the
current versions found
[here](https://github.com/mserajnik/rtsn/blob/master/install/.babelrc.example)
and
[here](https://github.com/mserajnik/rtsn/blob/master/install/gulpfile.babel.js)
.

__Updating from `2.x` is not recommended!__

Please make a fresh installation, copy your sources over and go from there if
you have been using an older version. Depending on the project, this might also
be the easier/faster way when updating from `3.x`.

## Usage

By default, your source files will be located in the `<project-name>/src`
directory and your distribution directory will be `<project-name>/dist`. rtsn
automatically adds some example files I personally use as a starting point on
new projects so you can see how it should be structured for rtsn to work
correctly.

### CLI

You can use the following commands (you need to be in your project's directory
for them to work):

+ `gulp`: runs `clean` and `build`
+ `gulp clean`: this cleans the distribution directory
+ `gulp build`: this makes a new build for production with minified files
(HTML, CSS and JS)
  + __Optional:__ `--pretty-html`: keeps the HTML unminified (as preparation
  for integration in other systems like WordPress, TYPO3 or Laravel)
  + __Optional:__ `--critical-css`: injects critical CSS inline (for
  optimized above-the-fold rendering)
+ `gulp serve`: this makes a new build for development and opens a browser
window. It then starts Browsersync: any changes you make in one of the source
files will trigger an injection or refresh the browser window
  + __Optional:__ `--online`: additionally starts an ngrok tunnel for sharing
  the project online

### Making configuration adjustments

To change rtsn's configuration, please take a look at the section `rtsnConfig`
in you `package.json`. Most of it should be self-explanatory, with one
exception:

__If you don't use CSS and/or JS in your project and therefore want to remove
those source files from the build process, please set empty strings as values
for `sassSource`/`lessSource` and/or `jsSource` in the `files` section. You can
leave `cssBuild` and `jsBuild` as they are.__

E.g.:

```json
"files": {
  "sassSource": "",
  "lessSource": "",
  "jsSource": "",
  "cssBuild": "style.min.css",
  "jsBuild": "script.min.js"
}
```

### Using packages from npm or Bower

To use packages installed via npm or Bower, you can just include them in your
source files. E.g., to load the popular
[lightGallery](http://sachinchoolur.github.io/lightGallery/), you first need to
install it:

```bash
user@local:<project-name>$ npm i lightgallery
```

Now you can import the styles in your source file (assuming you are using
Sass/SCSS, if you are using Less you will need to import
`lightgallery/src/css/lightgallery.css` instead – this will vary depending
on what preprocessor the package you want to import uses):

```sass
@import 'lightgallery/src/sass/lightgallery';
```

rtsn automatically looks into `node_modules` and `bower_components` so you
don't need to add the full path.

The same goes for the JavaScript:

```js
require('lightgallery');
```

Not all packages can be imported this way (usually only those that are written
in a module format) and you might need to search the web for how to include
them in your project. But since using a module format when developing reusable
JavaScript packages is pretty much a standard now, it can also be an indicator
of the quality/up-to-dateness of the package and you should think twice before
trying to use anything in your project that is written without it. You usually
won't have a problem finding another package that's more up-to-date – try
[JavaScripting](https://www.javascripting.com) for that purpose.

As a last step, many packages (including lightGallery) come with resources
(images, fonts etc.) that you need to copy over to your project in order for
everything to work correctly. To automate this, you can add rules to the
`vendorCopy` array in your `package.json` that will tell rtsn what to copy from
where to where:

```json
{
  "source": "node_modules/lightgallery/src/fonts/*",
  "build": "fonts/"
}
```

In this example, we copy all the files from
`node_modules/lightgallery/src/fonts` to `fonts` in your source folder. You
need to add one object per source and can add as many as you want.

## Credits

rtsn  is partially based on the awesome
[Scffld](https://github.com/matejsvajger/scffld). Since it's very much tailored
to my personal needs it probably lacks some options which would be nice to have
for some people. Please check out Scffld if you're looking for something that's
more general purpose.

## Donate

If you like rtsn and want to buy me a coffee, feel free to donate via PayPal:

[![Donate via PayPal][paypal-image]][paypal-url]

Alternatively, you can also send me BTC:

![Donate BTC][btc-image]  
`13jRyroNn8QF4mbGZxKS6mR3PsxjYTsGsu`

Donations are unnecessary, but very much appreciated. :)

## Maintainer

[mserajnik](https://github.com/mserajnik)

## Contribute

You are welcome to help out!

[Open an issue](https://github.com/mserajnik/rtsn/issues/new) or submit a pull
request.

## License

[MIT](LICENSE.md) © Michael Serajnik

[npm-url]: https://www.npmjs.com/package/rtsn
[npm-image]: https://img.shields.io/npm/v/rtsn.svg

[travis-url]: https://travis-ci.org/mserajnik/rtsn
[travis-image]: https://img.shields.io/travis/mserajnik/rtsn/master.svg

[paypal-url]: https://www.paypal.me/mserajnik/
[paypal-image]: https://www.paypalobjects.com/webstatic/en_US/i/btn/png/blue-rect-paypal-26px.png

[btc-image]: https://mserajnik.at/external/btc.png