rtsn
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, its spiritual successor.
rtsn (/ˌɑː(r)tɪˈzæn/) is a boilerplate/toolkit for front-end development using gulp. Its 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
: runsclean
andbuild
-
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)
-
Optional:
-
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
-
Optional:
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:
Alternatively, you can also send me BTC:
13jRyroNn8QF4mbGZxKS6mR3PsxjYTsGsu
Donations are unnecessary, but very much appreciated. :)
Maintainer
Contribute
You are welcome to help out!
Open an issue or submit a pull request.
License
MIT © Michael Serajnik