I Published a NPM Package


laptop mockup with text i published a npm package

If you’re a web developer, then you’re probably no stranger to starting off a new project by using some template or boilerplate code. You’re also probably no stranger to consequently deleting the useless files that the boilerplate came with. I’ve come to repeat this cycle a countless number of times and at some point I decided that there had to be a better way.

Some Context

I am primarily a Next.js developer and more often than not, when I start a new project I use TypeScript. For styling, though I’ve recently gotten quite acquainted with Tailwind CSS, I am still most at home with SCSS. And whenever I need a database in a project, I always reach for MongoDB. Lastly, we all need some linting to catch the inevitable errors we’ll make whilst creating the next big thing. So that’s my usual setup: a Next.js Project that uses TypeScript and SCSS, coupled with a MongoDB database and linting with ESLint.

How I Used To Work

So whenever I wanted to spin up a new project, I’d use create-next-app, which is a very powerful and capable CLI from the guys over at Next.js. It has support for using TypeScript by adding a flag, using an example project to generate the boilerplate, as well as choosing which package manager you’d like to use. And if that isn’t already good enough, it will also initialise a Git repository for you. The problem, as I alluded to earlier, is that I then had to go through the process of deleting what I don’t want, like the logos, the CSS styles and the dummy content and then adding what I actually want, like my SCSS setup, wrapper components, a meta tag component etc. So on 13 August 2021, I did something to improve my workflow.


So here's what I did, I setup a GitHub repository for my personal Next.js templates, you can visit the repo here. I created a branch for each different configuration. With our four variables (TypeScript, SCSS, MongoDB and ESLint) this works out to 16 different combinations so 16 branches. Each branch has its own README with instructions on how to bootstrap it. A typical branch’s README looks like this:

# Clean Next.js with TypeScript and MongoDB Boilerplate

## Usage

1. `git clone https://github.com/TinoMuzambi/CleanNext.jsBoilerplate .`
2. Switch to the `with-typescript-mongodb-eslint` branch
3. `rm -rf .git`
4. `git init`
5. `yarn`
6. Create an .env file and enter your MongoDB connection string in an environment variable named `MONGO_URI`
7. In any file you need to work with your database, import db from the `utils/db.ts` file then run `await db()` then proceed with the rest of your code.

My new workflow became cloning my repo, switching to the relevant branch for that project’s specific needs, deleting the Git folder and reinitialising Git. From there on I’d be off to the races. This worked really well but one day I watched a YouTube video by Traversy Media where Brad was creating a CLI password generator and I got an idea.


I took inspiration from create-next-app, and created my own CLI that leverages my already established boilerplates. This idea excited me because I had never created a CLI before, and I had also never published a package on NPM. So armed with the knowledge from the video I’d watched, as well as a bit more research, I spun up a Node project and installed Commander, Inquirer and Chalk. Commander to run the CLI and scaffold the options and arguments, Inquirer to handle the prompts, and Chalk to make things pretty. It took about 11 hours and tons of debugging, but I eventually managed to publish my NPM package, (in the process deprecating a package) and it’s available for the world to use.

screenshot showing time spent coding CLI

How it Works

You can invoke the CLI by opening up a terminal and running npx @tinotech/clean-next-boilerplate. After, you will be asked the name of your project, if a name isn't provided it defaults to the current working directory. It will then ask whether you want to use TypeScript, SCSS, MongoDB or ESLint, all questions defaulting to yes. The CLI will then do its thing and create all the necessary files and also initialise a Git repository. You can also pass two arguments, the first being the output directory where the files will be written to, (defaults to the current directory) as well as a flag to skip the prompts and answer yes to all the questions.


Default Setup Without Arguments

demo with default setup

Default Setup Passing Argument to Skip Prompts

demo with yes argument

Next Steps

The CLI is still in its infancy and I have a few ideas for the next steps. I’d like to add options for including React’s Context API, as well as support for adding a Tailwind CSS configuration. These two issues are up on the CLI’s GitHub page. And with them completed it would bring the number of combinations up to a dizzying 64. I’m also interested in a more scalable way of producing the necessary files and that’s where you come in.

Contribute to the CLI

The NPM package is available here for you to check out, use, critique and contribute to. Hit me up, create an issue, open a pull request. The package has built-in types as well in an attempt to make it as easy to understand as possible. I’m very open to all suggestions and intend on developing this into a go-to CLI for generating Next.js projects.

For those of you who prefer React, I also have a GitHub repo for a clean React boilerplate. Find me on GitHub, email and whilst you’re here, why not check out my website.