npm package: @shopify/tophat
Description: Tophat utilities for web development at Shopify
Author: Shopify
Latest version: 0.0.5
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Tophat Web

CLI for Tophatting Typescript packages at Shopify.

## Getting Started

Install this package using [`yarn`](https://yarnpkg.com/en/package/jest):

```bash
yarn add --dev @shopify/tophat
```

Or [`npm`](https://www.npmjs.com/):

```bash
npm install --save-dev @shopify/tophat
```

Next add a `build` key to the `scripts` section of your `package.json`. This is the script that will be run to build the files for tophatting.

_Example Package.json_

```json
{
  "scripts": {
    "build": "tsc -- --watch"
  }
}
```

This `scripts` name can be configured, or a custom command can be used instead. See [Configuration Options](#configuration-options) below.

## Running from command line

`yarn tophat [source] [destination] [package]`

When run with no arguments (`yarn tophat`), prompts will guide you through entering a `source` and `destination`.

### `source` or `[--source <string>]`

This is the package name in the current working directory that you would like to tophat. The default is the current working directory's `name` field in `package.json`. If inside of a `lerna` structured repository, the `source` is automatically resolved to the `packages` directory. This package can optionally be set with the `--source` command line flag.

_Example_

```bash
yarn tophat react-server
```

or

```bash
yarn tophat --source react-server
```

### `destination` or `[--dest <string>]`

This is the destination project that you would like to tophat in. Note, the source must be installed in the destination's `node_modules`.

_Example_

```bash
yarn tophat react-server ../web
```

```bash
yarn tophat --source react-server --dest ../web
```

### `package` or `[--package <string>]`

This is the name of the package that you would like to use. If it is not supplied, the `name` from the `source`'s `package.json` file will be used.

```bash
yarn tophat react-server ../web react-server-next
```

```bash
yarn tophat --source react-server --dest ../web --package react-server-next
```

## Additional Configuration

Tophat uses [cosmiconfig](https://github.com/davidtheclark/cosmiconfig) to provide additional in the form of a configuration file. This means you can provide configuration in the following ways (in order of precedence):

- A `"tophat"` key in your `package.json` file.
- A `.tophatrc` file, written in JSON or YAML, with optional extensions: `.json/.yaml/.yml` (without extension takes precedence).
- A `.tophatrc.js` or `tophat.config.js` file that exports an object.
- A `.tophatrc.toml` file, written in TOML (the `.toml` extension is _required_).

### Configuration Options

#### `buildDirectory`

Specify the build directory that is synced to the consuming repo. The default value is `dist`.

#### `buildScript`

Specify the build script that compiles the project. This is run in watch mode while tophatting. The default value is `build`.

#### `buildCommand`

Specify your custom build command to be used instead of the default. You can specify `<package>` within the command and it will be replaced by the actual name of the package.

For example if you specify the following in `package.json`:
```json
"tophat": {
  "buildCommand": "yarn tsc --build packages/<package> --watch`"
}
```

Then run
```bash
yarn tophat sewing-kit ../web
```

The build command executed by tophat would be
```bash
yarn tsc --build packages/sewing-kit --watch
```

## Common Errors

`Module Y has no exported member X`
**Solution:** run `yarn run build` then run the same command again

`Cannot find source in X or Y. Are you sure it exists?`
**Solution** install the package you are trying to tophat in the destination directory with `yarn add <packageName>`

If you install new modules in the package you are installing, you will need to install them in the destination while tophatting.