Building a Slush Generator5 min read

Building a Slush Generator

Generators are powerful tools that help in quickly scaffolding project structures. You can use them to start off a new project or add new components to an existing project. Generally these projects are collections of best practices that a developer can consume directly. In this post, we will see how to build a simple generator that will create a boilerplate for a building static pages with auto reloading feature.

You can find the completed code here.

So, let us get started.

What is Slush?

Slush is a tool to be able to use Gulp for project scaffolding.

Slush does not contain anything “out of the box”, except the ability to locate installed slush generators and to run them with liftoff.

Getting started

First we will install gulp, slush and slush-generator. slush-generator is a generator for generating slush generators. Yup! this generator will scaffold a project that can be used to scaffold other slush projects.

As mentioned earlier, we are going to build a project that will create a boilerplate for a building static pages with auto reloading feature. Create a new folder named slush-reloader. Open a new terminal/prompt here and run

Windows Mac/*nix

npm i -g gulp slush slush-generator 

  sudo npm i -g gulp slush slush-generator

Once the installation is completed, we will scaffold a new slush project. Run

slush generator

And answer the questions as below

Screen Shot 2014-07-31 at 8.55.47 amPS : Enter the project name as only reloader and not slush-reloader.

Slush will take care of installing the dependencies. The final project structure would be

The project structure is pretty simple. We will be working mostly with slushfile.js and templates folder. Once the development is completed, we will push the changes to NPM repository by updating our package.json. Sounds simple?

Now, open slushfile.js in your favorite editor. You will notice that there are a few includes and and some helper functions. Then you will notice a gulp task.

When building slush generators, you need to be aware that a generator is nothing but a gulp task. And the name of the task is how we would be invoking it. Technically a gulp task also acts a sub-generators. Sub-generators are very much like generators, except they are used once the project is already generated and a few minor monotonous functionalities need to be added.

For example, if you are building a client-side MVC app, a generator will be responsible for scaffolding the app itself, where as a sub-generator will be responsible for scaffolding MVC related files for a new feature/route as the development progresses.

Back to the gulp task, you will notice an array named prompts inside the callback function, this array holds the list of question that you would be asking to user to scaffold a project. Like the once we have answered to generate the current project.

And then these options are fed into a node module named inquirerinquirer is responsible for firing these questions and gathering the answers. Once we receive the answers, we can scaffold a project according to the user’s inputs. Simple?

For our generator, we will only ask the user what is the name of the project. We will use this input to personalize the project for the user.

You can update the prompts array like

If you want to test this locally, you can link this project to a node module. Run

[sudo] npm link

Now, you can locally test the generator as you make changes.

Create another folder named test_reloader elsewhere on the same machine and open terminal/prompt and run

slush reloader

And you should see the question we have configured. You can enter anything or simply hit return and you should see Screen Shot 2014-07-31 at 9.21.30 amNothing happens because we have no files to placed into the destination folder. Back to the slushfile.js, the inquirer part

On line 3, we check if a certain condition is met to start the scaffolding process, else we terminate the execution. On line 6, we clean up the user’s input. On Line 7, using a globbing pattern, we fetch all the files from the templates folder. We pass in the answers to the files we fetched in the templates folder, personalize the content and then save the processed files to the user’s current folder. Once all the files/folders are saved, we run the install()  on the scaffolded project to install dependencies.

For our generator, this is precisely what we need.

The final slushfile.js would be

Now, let us build the project we would like to scaffold. Generally, I build a few projects of a type, prune the best practice and then build a boilerplate/template that can be reused.

Inside the templates folder, create 2 new folders named css and js. And create app.css and app.js in css and js folders respectively. Open app.js and updated it as

And app.css like

Next, create a new file at the root of templates folder and name it index.html. And update it like

Do notice <%= appName %>. This will be updated when we scaffold the template with the answers.

Next, create a new file at the same level as index.html and name it as package.json. Update the file as below

We are going to add gulp-connect module that will be used to host the files locally. And finally the gulpFile. Create a new file named gulpFile.js and update it as

Save all the files and Bam!! we are done with our generator. Now back to the test folder we have created – reloader and run

slush reloader

Answer the question and slush will scaffold the app for us. Once done, run

gulp

This will start the connect server and you can navigate to  http://localhost:8080  and see the scaffolded app.

Simple right? If you want to see more advanced examples you can checkout

Repo

Description

slush-mongo

 A slush generator for MongoDB

slush-meanjs

 A slush generator to scaffold MEAN Apps

slush-bootstrap

 A Slush generator for Bootstrap SASS/LESS/CSS projects

slush-express

 A slush generator to scaffold Express apps

slush-webstarterkit

One command scaffold-er for Google's Web Starter Kit. No questions asked!

slush-h5bp

 A HTML5 Boilerplate generator for Slush

slush-angularfire

 A slush generator to scaffold an Angular-Firebase App

slush-reveal

 A Slush Generator for creating Revealjs presentation

Pushing to NPM

Once you are satisfied with your generator you can push the code to GitHub and publish it to NPM. For this, create a new Github repo named slush-reloader.

Next, push the code to the repo run

git init

git add -A

git commit -am "initial commit"

git remote add origin https://github.com/arvindr21/slush-reloader.git

git push origin master

Next, we will push this repo to NPM. Run

npm publish

You may be asked to enter your NPM credentials. If you do not have one, you can create so here.

Once the command executes, you can checkout  https://www.npmjs.org/package/slush-reloader  to see the package module registered with NPM.

Hope you got a decent idea on how to build your own slush generator.


Thanks for reading! Do comment.
@arvindr21