Automate Creating New NodeJS Projects

Recently I’ve taken to heart the Single Responsibility Principle. That means I’ve been focused on creating NodeJS modules that do only one thing. In other words have only one responsibility.

My approach has been to take anything that is in a projects lib or controller folder and break it out as its own component (or module) project. You can see some of the results in my account out on npmjs.com/~mitchallen.

There are several advantages to breaking modules out into their own projects:

  • Code Reuse – if you’ve ever copied and pasted a module from one project into another, then you should put it into it’s own project
  • Less Build Complexity – since parts were built and tested in isolation, I just have to pull them out of the repo
  • Easier to Track Down Bugs – every component now has its own test suite – when was the last time you wrote a test for something in your lib folder?
  • Versioning – if a change in some other component becomes a problem, I can just pull a previous version from the repo
  • Better Documentation – when was the last time you documented how something in your lib folder worked?
  • Reduces Unused Code – I can only include the parts I need

The biggest disadvantage is that now I have to create a lot more NodeJS projects. There’s a lot of manual steps involved and they are prone to error. Next I’ll review those steps.

Manual Steps

Here is a list of the things that I had to do to setup a project:

  • Create a project folder
  • Create subfolders (test and examples)
  • Run npm init
    • make sure I remember to put my npm scope name in the description
    • make sure I set the version to 0.1.0
    • Copy and paste chunks of settings from another projects package.json file
    • Edit the new settings to make sure they not only don’t refer to the old project, but get the references to the new project right (without type-os)
    • Run npm install to install the dependencies I pasted into package.json
  • Create an index.js file and do the following:
    • Refer to other projects for how to setup the basic structure
    • Add my name and module name
  • Create a test/smoke-test.js file
    • Refer to other projects for how to setup the basic structure
    • Add my name and module name
  • Copy .npmignore from another project (I haven’t had much luck with the global setting)
  • Copy a README.md from another project as a template and remove all references to the other project
    • Change title for new project name
    • Change usage to show installing new project
    • Edit the references to the Bitbucket and GitHub repos
  • Copy Gruntfile.js from another project
  • Run grunt to make sure it works and my files are lint free
  • Run npm test to make sure that testing has been setup propery
  • Run git init
  • Add and commit the files to git
  • Create a Bitbucket repo for the project
  • Create a GitHub repo for the project
  • Set the remotes to allow pushing to both repos at the same time

Clearly there needs to be a better way to do this. Wouldn’t it be nice if I could automate it? Well I did! I’ll go over that next.

Automated Steps

Out on Bitbucket you can find my script for automating the creation of new NodeJS projects. It’s a work in progress. You can find it here:

I broke out some of the user specific variables. But by default they are still hard-coded for me. Feel free to copy the script and customize the values. I didn’t see a need to get everything from the environment.

Here is what the script currently does:

  • Accepts one argument – the package name which will also be the new folder name
  • If a folder in the current directory already exists with that name, the script exits
  • If a folder does not exist, it is created
  • Creates two subfolders (test and examples)
  • Clones a starter kit – this is another repo that I have out on Bitbucket which can be found here:
  • Copies files from the kit, sometimes renaming or moving them
    • package.json – my default version with dependencies and sctipts
    • README.md – something basic to build on
    • .npmignore – so I don’t end up publishing the examples and test folders to npm
    • Gruntile.js – my custom build routines used by grunt
  • Removes the folder containing the clone
  • Runs sed against the files to replace template variables with values for the current project (such as the package name)
  • Removes *.bak files (a side effect of using sed to do inplace replacement)
  • Runs npm install to install dependencies listed in package.json
  • Runs git init
  • Adds and commits the files to git
  • Creates a Bitbucket repo from the command line using my account name and the name of the package
    • For security, it prompts me for my Bitbucket password
  • Adds the new repo as a remote for fetch and push operations
  • Creates a GitHub repo from the command line using my account name and the name of the package
    • For security, it prompts me for my GitHub password
  • Adds the new repo as an additional remote for push operations
  • Pushes everything to Bitbucket and GitHub
  • Pushes tags (if any) to Bitbucket and GitHub
  • Runs grunt which by default will lint check index.js
  • Runs npm test to make sure testing is setup properly
  • Informs the user that the projects have been setup

It was a lot of work to setup. Glad I no longer have to do it by hand!  Now, whenever I want to create a new NodeJS project I just need to do this:

$ ./node-starter.sh my-new-project

Then my new project will be setup locally and on both Bitbucket and GitHub. I have everything I need to run tests, push changes to both repos and even use grunt to lint check and publish to npm.


Mitch Allen is a game developer and tech writer. To download his latest games and books please visit his Web site at mitchallen.com