npm package: @inspire11/create
Description: A CLI for quickly creating new Inspire11 projects
Author: Robert Hameetman
Latest version: 0.0.28

![@inspire11/create][logo]

![Version](https://img.shields.io/npm/v/@inspire11/create)
![Downloads](https://img.shields.io/npm/dt/@inspire11/create)
![Build](https://img.shields.io/bitbucket/pipelines/inspire11/create/master)
![License](https://img.shields.io/npm/l/@inspire11/create)

# 📦 @inspire11/create

Run one simple command with interactive project generator to install bootstrapped packages designed to let you hit the ground running.

1. [🛠 Creating Projects](#markdown-header-creating-projects)
2. [🧾 Features](#markdown-header-features)
3. [🔩 Setting Up Your Editor](#markdown-header-setting-up-your-editor)
4. [🙌🏼 Contributing](#markdown-header-contributing)
5. [ℹ️ FAQs](#markdown-header-faqs)
6. [📯 Thanks](#markdown-header-thanks)

## 🛠 Creating Projects

You'll need [Node](https://nodejs.org/) `v10` or later.

```bash
npm init @inspire11
```

The interactive CLI will help you create and configure your project automatically.

> Since this repo includes [the CLI and it's tests](./src/cli), you'll only need to fork or clone
> this project if you want to contribute. If you find this project useful, please consider
> [leaving feedback](https://bitbucket.org/inspire11/create/issues/new) so others can find
> it. Thanks!

## 🧾 Features

* Write **standard, future javascript** – with stable ESNext features – today ([stage 3](https://github.com/tc39/proposals) or [finished](https://github.com/tc39/proposals/blob/master/finished-proposals.md) features)
* [Optionally use typescript](https://medium.freecodecamp.org/its-time-to-give-typescript-another-chance-2caaf7fabe61) to improve tooling, linting, and documentation generation
* Export as a [javascript module](http://jsmodules.io/), making your work **fully tree-shakable** for consumers capable of using [es6 imports](https://github.com/rollup/rollup/wiki/pkg.module) (like [Rollup](http://rollupjs.org/), [Webpack](https://webpack.js.org/), or [Parcel](https://parceljs.org/))
* Export type declarations to improve your downstream development experience
* Backwards compatibility for Node.js-style (CommonJS) imports
* Both strict and flexible [typescript configurations](config/tsconfig.json) available

So we can have nice things:

* Generate API documentation (HTML or JSON) [without a mess of JSDoc tags](https://blog.cloudflare.com/generating-documentation-for-typescript-projects/) to maintain
* Collocated, atomic, concurrent unit tests with [Cypress](https://www.cypress.io/)
* Automatic linting and formatting using [ESLint](https://github.com/palantir/tslint)

## 🔩 Setting Up Your Editor

Before you start, consider using an [editor with good typescript support](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Editor-Support).

[VS Code](https://code.visualstudio.com/) (below) is a popular option. Editors with typescript support can provide helpful autocomplete, inline documentation, and code refactoring features.

Also consider installing editor extensions for [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint). These extensions automatically format your code each time you save, and may quickly become invaluable.

## 🙌🏼 Contributing

To work on the CLI, clone and build the repo, then use `npx` to test it globally.

```bash
git clone git@bitbucket.org:inspire11/create.git
cd create
npm i
npm run build
npm run prod
```

The following tasks make development faster and more interactive:

| Command |                                                                                  Description |
|---------|---------------------------------------------------------------------------------------------:|
| `build` |                                                                Clean and rebuild the project |
| `dev`   | Run the pre-processed script directly via [`ts-node`](https://www.npmjs.com/package/ts-node) |
| `prod`  |                                 Run the compiled script via [`node`](https://nodejs.org/en/) |
| `test`  |                                                               Lint and unit test the project |

To start working, run the `dev` task using [`npm`](https://docs.npmjs.com/getting-started/what-is-npm).

```bash
npm run dev
```

The `dev` task will run the script directly via [`ts-node`](https://www.npmjs.com/package/ts-node); the `test` task will run the test suite in watch mode with [Jest](https://jestjs.io/en/). Each time you save, any changes will be rebuilt and retested.

Since only changed files are rebuilt and retested, this workflow remains fast even for large projects.

## ℹ️ FAQs

**Why are there two builds? (`main` and `module`)**

The `src` of `@inspire11/create` is compiled into two separate builds: `main` and `module`. The `main` build is [configured to use the CommonJS module system](/tsconfig.json#lines-4). The `module` build [uses the new es6 module system](/tsconfig.module.json).

Because Node.js LTS releases do not yet support the es6 module system, some projects which depend on your project will follow the `main` field in [`package.json`](/package.json). Tools which support the new system (like [Rollup](https://github.com/rollup/rollup), [Webpack](https://webpack.js.org/), or [Parcel](https://parceljs.org/)) will follow the `module` field, giving them the ability to statically analyze your project. These tools can tree-shake your `module` build to import only the code they need.

**Why put tests next to the source code?**

By convention, sample tests in this project are adjacent to the files they test.

* Such tests are easy to find.
* You see at a glance if a part of your project lacks tests.
* Nearby tests can reveal how a part works in context.
* When you move the source (inevitable), you remember to move the test.
* When you rename the source file (inevitable), you remember to rename the test file.

## 📯 Thanks

Using `@inspire11/create` for your project? Please send a pull request to add it to the list!

[logo]: /.bitbucket/logo.png "@inspire11/create"