# @mapbox/typehead

> Refreshingly simple CLI for TypeScript packages.

Latest version **1.2.1** (published 2022-04-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @mapbox/typehead
pnpm add @mapbox/typehead
yarn add @mapbox/typehead
bun add @mapbox/typehead
```

Provides the commands `typehead`, `typehead-build`, `typehead-serve`.

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 1.2.1 |
| Published | 2022-04-01 |
| First published | 2021-09-03 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=14.17.6 |
| Dependencies | 6 |
| Unpacked size | 29.8 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 24 |
| Author | Michael Bullington |
| Maintainers | mapbox-npm-01, mapbox-npm-02, mapbox-npm-07, mapbox-npm-03, mapbox-npm-04, mapbox-npm-09, mapbox-npm-05, mapbox-npm-06, mapbox-npm-08, mapbox-npm-advanced-actions, mapbox-npm-ci, mapbox-npm, mapbox-admin, mapbox-machine-user |

## Links

- npm: https://www.npmjs.com/package/@mapbox/typehead
- Repository: https://github.com/mapbox/typehead
- Homepage: https://github.com/mapbox/typehead#readme
- Issues: https://github.com/mapbox/typehead/issues
- npm.io page: https://npm.io/package/@mapbox/typehead

## Dependencies (6)

- [chalk](https://npm.io/package/chalk.md) ^4.1.2
- [esbuild](https://npm.io/package/esbuild.md) ^0.14.19
- [commander](https://npm.io/package/commander.md) ^8.1.0
- [deepmerge](https://npm.io/package/deepmerge.md) ^4.2.2
- [cosmiconfig](https://npm.io/package/cosmiconfig.md) ^7.0.1
- [esbuild-plugin-lodash](https://npm.io/package/esbuild-plugin-lodash.md) ^1.1.0

## Recent versions

- 1.2.1 (latest) — 2022-04-01
- 1.2.0 — 2022-03-31
- 1.1.0 — 2022-02-07
- 1.0.3 — 2021-11-05
- 1.0.2 — 2021-09-13
- 1.0.1 — 2021-09-03
- 1.0.0 — 2021-09-03

## README

![logo](./assets/logo.png)

Typehead is a thin wrapper around [ESBuild](https://esbuild.github.io/) that makes it refreshingly simple to develop NPM packages using TypeScript.

📦 `npm install --save-dev @mapbox/typehead typescript`

# How?

In your `package.json`:

```json
{
  "main": "dist/index.js",
  "module": "dist/index-esm.js",
  "typings": "dist/index.d.ts",
  "scripts": {
    "build": "typehead build",
    "watch": "typehead build --watch",
    "serve": "typehead serve"
  }
}
```

Typehead will not check types or generate declaration files. While this seems initially counter-intuitive, this operation is costly and usually covered by IDE tools (VSCode) and CI (using `tsc`).

We recommend setting this up with `tsc`, which is included with TypeScript.

Here's an example that builds types before publishing to NPM:

`tsconfig.types.json`:

```json
{
  "extends": "./tsconfig.json",
  "compilerOptions": {
    "declaration": true,
    "emitDeclarationOnly": true,
    "outDir": "./dist"
  },
  "include": ["src/*", "src/**/*"]
}
```

`package.json`:

```json
{
  "scripts": {
    "types": "tsc -p tsconfig.types.json",
    "prepare": "npm run types && npm run build"
  }
}
```

## Build

`typehead build` will automatically set the entry point to `src/index`. You can use either `.ts`, `.tsx`, `.jsx`, or `.js` files. We heavily recommend the use of TypeScript for all packages.

Output files will live in `dist/`:

This behavior is configurable ([see below](#Customization)).

- A development CSM build `index-development.js` that is **not** minified.
- A production CSM build `index.js` that is minified.
- A production ESM build `index-esm.js` that is not minified.

### Global name

If `globalName` is specified in [customization](#customization), then a fourth build will be created with that name.

- A production IIFE build `{globalName}.js` that is minified and includes all dependencies statically.

The IIFE build is suitable for distribution on CDNs and [UNPKG](https://unpkg.com/).

`package.json`:

```
{
  "unpkg": "dist/{globalName}.js"
}
```

## Serve

`typehead serve` will start a web server for the `web` directory (if present).

Inside `web`, `web/index.{js,jsx,ts,tsx}` will be bundled by ESBuild for browser use. From this file, you can import your main module from `../src` and do things like demos, benchmarking, etc...

The bundle will be accessible from the web server at `/index-bundle.js`. Make sure to use `type="module"` in your `<script>` tag.

#### Recommended way to add to your project

`web/index.html`:

```html
<!DOCTYPE html>
<html>
  <body>
    <script type="module" src="/index-bundle.js"></script>
  </body>
</html>
```

`web/index.ts`:

```javascript
// ... you can import your main module here, or anything really!
import myModule from '../src/';
```

## Optimizations

### Lodash

`typehead` will automatically rewrite your Lodash calls using [esbuild-plugin-lodash](https://github.com/josteph/esbuild-plugin-lodash).

```typescript
import { pick, omit } from 'lodash';

// Will be rewritten to...
import pick from 'lodash/pick';
import omit from 'lodash/omit';
```

## Customization

You can add additional ESBuild options by adding `typehead` in any way [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) supports. This will be deep merged with the internal config.

Aside from the disclaimer below, any options in the [ESBuild Build API](https://esbuild.github.io/api/#build-api) may be specified.

**Warning:** The following options may be overwritten: `entryNames`, `format`, `minify`.

To specify a different `outdir` than `dist`, here's an example using `package.json`:

`package.json`:

```json
{
  "typehead": {
    "outdir": "notDist"
  }
}
```

`typehead.config.js`:

```typescript
export default {
  // Add ESBuild options here!
  // https://esbuild.github.io/api/#build-api
  plugins: [],
};
```

**`typehead serve` only:**

The following options `entryPoints` and `outdir` are not respected in `typehead serve`. You can specify values for the serve command with `webEntryPoints` and `webOutdir`.

# Why?

This was created to consolidate a lot of small packages at Mapbox with vastly different build setups.

As we adopt TypeScript, it makes sense to have a common system that:

1. Works out of the box.
2. Allows for customization.
3. Doesn't introduce too many artifical layers.

`typehead` was heavily inspired by, and still has a soft spot for, [TSDX](https://github.com/formium/tsdx).

`typehead` was created as a CLI tool instead of a boilerplate repo. This is so changes in our config could be propagated throughout our packages.

# License

Typehead is provided under the terms of the [MIT License](https://github.com/mapbox/typehead/blob/main/LICENSE)

---
_Source: https://npm.io/package/@mapbox/typehead · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._