How to use `npm create` to make your quickstart docs better
Tags: javascript, webdev, npm, node
Published: 2024-04-26 11:26:03

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:

```bash
npx yourlib create myproject
```

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

```json
{
  "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](https://svelte.dev/docs/introduction#start-a-new-project) or [Vite](https://vitejs.dev/guide/#scaffolding-your-first-vite-project) 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:

```text
create-<whatever>
```

For instance, the package I created was [create-eos](https://www.npmjs.com/package/create-eos), as it's a CLI for getting set up on the [EOS Network](https://docs.eosnetwork.com/docs/latest/quick-start/introduction) 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](https://docs.npmjs.com/cli/v7/configuring-npm/package-json#bin).

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

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

Now create that file and put this at the top. 
```javascript
#!/usr/bin/env node
require("./index.js");
```

This will call your `index.js` script from the executable using the [node shebang](https://alexewerlof.medium.com/node-shebang-e1d4b02f731d).

What you put inside of your `index.js` is up to you, but you can reference the [CLI I created](https://www.npmjs.com/package/create-eos) 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](https://twitter.com/nsjames_). I write about software development, developer relations, and buildinpublic.