node package manager
Stop wasting time. Easily manage code sharing in your team. Create a free org »

rtsn

rtsn npm version Build status

A simple front-end development boilerplate/toolkit

rtsn (/ˌɑː(r)tɪˈzæn/) is a boilerplate/toolkit for front-end development using gulp. It's most important features are:

  • Pug as template engine or plain HTML – whatever you prefer
  • Sass/SCSS or Less as CSS preprocessor, complete with autoprefixing, importing from node_modules/bower_components (including required assets!) and minifying
  • Critical inline CSS for optimized above-the-fold rendering
  • ES6 transpiling for JavaScript via Babel and module bundling via Browserify
  • Automatic image optimization for JPGs, PNGs, GIFs and SVGs via imagemin
  • Automatic copying of everything that doesn't need to be transformed (e.g., fonts)
  • Automatic browser refreshing via Browsersync with optional ngrok tunneling for sharing the preview online
  • 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

First, make sure you have Node.js installed. Using the latest version of Node.js and npm is recommended.

Next, if you don't already have Gulp installed, run the following command:

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

Create a new directory for your project and install rtsn:

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 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 and here .

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.:

"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, you first need to install it:

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):

@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:

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 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:

{
  "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. 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

Alternatively, you can also send me BTC:

Donate BTC
13jRyroNn8QF4mbGZxKS6mR3PsxjYTsGsu

Donations are unnecessary, but very much appreciated. :)

Maintainer

mserajnik

Contribute

You are welcome to help out!

Open an issue or submit a pull request.

License

MIT © Michael Serajnik