[WIP] create-microbundle-module

Bootstrap your development environment for creating small javascript libraries with no hassle 🎉

Quick Start

npm init microbundle-module my-awesome-module
cd my-awesome-module
npm start

That last command will start Jest testing framework in the --watch mode.

Using your tests in the watch mode is the suggested approach for developing your library with this environment setup.

When you are done, you can prepare your module for publishing with npm run build

Background

For a while now I found myself doing the same repetetive process every time I want to create a small open source library:

• Set up a new project folder structure and initial entry, test files
• Initialize new Git repository
• Install linting, code-formatting, bundling, testing tools
• Set up pre-commit git hooks
• Make an initial commit

So based on that, I decided to normalize all those processes into one toolbox.

OMG, do I really need all that to share code with people?

Depends! 😉

I can't stress this enough, but this is perfectly fine to just do cool stuff in the easiest way possible and publish it in any way that is more comfortable for you: glitch, npm, github, bitbucket, gitlab, github gists, tweets, just a file somewhere in the internet, a piece of paper in your pocket, there are so many options around!

Choose whatever suits you and makes you happy sharing stuff with others and go for it! 🎉

However, if your workflow looks something like the one provided in this tool, you might find this usefull.

What's in the package?

create-microbundle-module

First of all, there is create-microbundle-module CLI that will help you to bootstrap the project.

Usage: create-microbundle-module [options] <module-directory>

  Options:

    -V, --version                                output the version number
    -t, --target <target>                        Your module target environment: web, node (default: web)
    -s, --scripts-version <alternative-version>  Use a non-standard version of microbundle-module-scripts (default: microbundle-module-scripts)
    -n, --no-commit                              If present, will skip initial commit

Calling this CLI can be done in many different ways, here are a few examples:

# With an awesome npx tool (npx <command> is available with npm 5.2+ and higher)
npx create-microbundle-module awesome-lib

# With npm init (npm init <initializer> is available with npm 6+)
npm init microbundle-module awesome-lib
# ... or with yarn create (yarn create <initializer> is available with Yarn 0.25+)
yarn create microbundle-module awesome-lib

# Or with a good old global install
npm install -g create-microbundle-module
create-microbundle-module awesome-lib

microbundle-module-scripts

If your microbundle-module <module-directory> command finished bootstrap process successfully, you now have enviroment ready to work with. Go to your module directory and hack away!

Now we will go into more details what is provided with this toolbox:

Here is the resulting folder structure:

<module-name>
├── .git
├── node_modules
├── package.json
├── src
│   └── <module-name>.js
└── test
    └── <module-name>.test.js

1. Git repository will be already initialized and first "bootstrap commit" will be created.
2. Main entry point will have the same name as the module and will be in the src folder.
3. Main test file for the source entry point will be in test/<module-name>.test.js file.
4. Autogenerated package.json will have microbundle-module-scripts already installed and will have a few scrips and some husky hooks already setup for you.

Let's talk about scripts and hooks.

scrips: npm start

Starts Jest in the --watch mode.

You might be wondering right now why use Jest in a watch mode as a development environment for the library? Before giving you my take on this, I would like to quote a few things from an awesome article by @kenwheeler about his approach to OSS:

These days I don’t write a single line of code until I’ve done a mock fantasy API of what I wish it would work like. It changes over time when you have to make it real, but its a great target to strive for. You’ll know when the API is right because YOU will feel like using it.

If you do anything at all, write some god damn tests. Pretty please. With a cherry on top. It would have saved me so much time and grief.

So there are two important points mentioned here:

1. Think thoroughly about the API before starting the implementation
2. Cover your stuff with tests, this will save you a lot of time later

I strongly agree with with these points (and with all the other ones in the article, so if you never read it before, give it a go!) and I think that using Jest in watch mode puts you in the nicest environment to think about these things while working on your library right away!

scrips: npm test

Runs tests with Jest test framework. All supported Jest CLI flags would be passed to the Jest test runner.

scrips: npm run build

Creates the production build of the library with microbundle. All supported microbundle CLI flags would be passed to the microbundle.

Microbundle is really nice tool that is made with a purpose of producing tiny, optimized modules with the help of Rollup. It also supports TypeScript and JSX out of the box!

scrips: npm run lint-staged

This command is configured to run prettier and eslint on specific files that are being staged in Git. Current setup will take into account only javascript files in src or test folder and also md files all across your project.

For example if you commit a tree of files that looks like this:

my-awesome-lib
├── what.js
├── test
│   └── my-awesome-lib.js
├── src
│   └── my-awesome-lib.test.js
└── README.md

what.js will be ignored, my-awesome-lib.js and my-awesome-lib.test.js will be linted and prettified and README.md will be prettified.

hooks: pre-commit

Pre-commit hook will be triggered every time you commit files to git. This hook will trigger npm run lint-staged command, that will lint and prettify some files in your project.

hooks: pre-push

Pre-push hook will be triggered every time you push your changes. On this hook npm test command will be triggered, preventing you from pushing code that is not passing tests

Hooks toggling

Hooks configuration is under your full control in the package.json file under the husky.hooks key. If you find any of those hooks are too much for you or you want to add more, you can disable them by removing hook keys or adding a new one. All Git hooks are supported by husky:

• pre-commit
• prepare-commit-msg
• commit-msg
• post-commit
• post-checkout
• pre-rebase

More information about these hooks and when they are triggered could be found in Atlassian Git Tutorial under the Local Hooks section

Extension points

[WIP]

Contributing

Feel free to submit issues and/or PRs if you found some bugs! 🐞 The documentation improvements will be super appreciated, if you feel that they are lacking in some places 📝👩🏻‍🔬

The workflow created by this library is opinionated but open for reasonable changes. If you have some ideas how it can be improved or changed, please don't hesitate to open an issue to start a discussion 👋

What's next?

• eject command to easily opt-out of using custom scripts
• TypeScript starter templates
• ReasonML starter templates (developit/microbundle#141)

Kudos

A massive kudos goes to all the awesome tools that are used in this library and toolboxes that inspired this project (in no particular order):

• microbundle: Zero-configuration bundler for tiny modules.
• Jest: 🃏 Delightful JavaScript Testing
• Husky: Git hooks made easy
• lint-staged: Run linters on git staged files
• Prettier: An opinionated code formatter
• ESLint: Pluggable linting utility for JavaScript
• create-react-app: Create React apps with no build configuration.

License

ISC