How to use `npm create` to make your quickstart docs better

The #1 primary goal of developer-facing software and tooling is making it as easy as possible for developers to use them.

It's the reason that Quickstart sections in documentations are so important, and why the length of those sections matters a lot. Too long? Didn't read.

So how can you shorten those?

Enter npx

If you don't know about npx, it stands for "Node Package eXecute", and is a way to execute scripts on the package.json from command-line without first installing the packing manually. You could do something like this:

npx yourlib create myproject

That will run whatever you have in your create script in your package.json. For example:

{
  "name": "@your/lib",
  "version": "1.0.0",
  "scripts": {
      "create": "node index.js"
  }
}

This is great, but if you look at big modern projects like Svelte or Vite you'll notice they don't use npx.

They use npm create.

One possible reason is that new developers know they have npm installed, but they don't realize they also have npx. That gives them pause, and makes them reconsider whether to use the tech if they have to install something additional onto their OS.

So, how does that work?

npm create isn't magic

It's basically doing the same thing as npx lib create, but it uses a specifically named npm package, and the bin property in your package.json.

Package name format

In order for your package to be picked up by npm create its name needs to follow this exact format:

create-<whatever>

For instance, the package I created was create-eos, as it's a CLI for getting set up on the EOS Network quickly.

Bin files

Your package.json supports specifying a bin file, which is a way to tell tooling that there's an executable script in your package.

Edit your package.json and add the bin property that points to a file called bin.js.

{
  "bin": {
    "create-<whatever>": "./bin.js"
  }
}

Now create that file and put this at the top.

#!/usr/bin/env node
require("./index.js");

This will call your index.js script from the executable using the node shebang.

What you put inside of your index.js is up to you, but you can reference the CLI I created if you want a starting point.

That's it!

Now all you need to do is push that up to npm using npm publish and anyone can call npm create <whatever>@latest.

Use this in your quickstart guides to give developers using your software and tools a better and modern experience. The more work you do for them, the less docs you have to write.

Did you like what you read? Follow me on Twitter. I write about software development, developer relations, and buildinpublic.