Tophat Web

CLI for Tophatting Typescript packages at Shopify.

Getting Started

Install this package using yarn:

yarn add --dev @shopify/tophat

Or npm:

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

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

This scripts name can be configured, or a custom command can be used instead. See 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

yarn tophat react-server

or

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

yarn tophat react-server ../web

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.

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

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

Additional Configuration

Tophat uses 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:

"tophat": {
  "buildCommand": "yarn tsc --build packages/<package> --watch`"
}

Then run

yarn tophat sewing-kit ../web

The build command executed by tophat would be

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.