npm package: @inthepocket/hubble-mirror
Description: The heart of the Hubble Design System
Author: In the Pocket
Latest version: 1.0.3

![Hubble Mirror logo][logo]

[![LICENSE](https://badgen.net/badge/license/MIT/blue)][license]
[![Releases](https://badgen.net/github/releases/inthepocket/hubble-mirror)][releases]
![Last commit](https://badgen.net/github/last-commit/inthepocket/hubble-nirror)
[![Latest release](https://badgen.net/github/release/inthepocket/hubble-mirror/stable)][latest release]

> Hubble mirror is the core of the hubble system, it is used to apply the HST system to a specific project.

# Prerequisites

- A recent node version (node@8 recommended)

# Usage

## Automatic install in a project

Use the provided install script and run this from your project root to create the required files for hubble-mirror:

```console
# Install for a generic project:
$ curl -o- https://storage.googleapis.com/hubble-static/install_hubble-mirror.sh?latest=true | bash

# Install for an iOS project
$ curl -o- https://storage.googleapis.com/hubble-static/install_hubble-mirror.sh?latest=true | bash -s -- --platform ios

# Show help for the installer script
$ curl -o- https://storage.googleapis.com/hubble-static/install_hubble-mirror.sh?latest=true | bash -s -- --help

# Alternatively, download install_hubble-mirror.sh from this repo, modify and run it:
$ chmod +x install_hubble-mirror.sh
$ ./install_hubble-mirror.sh --help
```

## Manual install in a project

`npm i @inthepocket/hubble-mirror`

### Create a .hubble-mirror.json

- The .hubble-mirror.json file should be in the root of the project
- The relative paths inside .hubble-mirror.json should always be defined relative to its position (best to put it at the root of the project)
- Data structure:

```json
{
  "source": {
    "assets": ".hubble/src/design-systems-demo/assets",
    "hst": ".hubble/src/design-systems-demo/hubble.json"
  },
  "postProcess": "hubble-postprocess.sh",
  "target": {
    "assets": "/assets",
    "hst": "./hst.json"
  },
  "deployPreview": {
    "publishDirectory": "/build",
    "previewUrl": "hubble-mirror-domain-preview-url"
  }
}
```

## Available scripts

### Hubble process

Process the current .hubble config and assets into the project.
`hubble-mirror:process`

### Hubble post-process

Run your custom made postprocess script. To handle the changes specific to your project.
For example:

- auto generate css
- auto generate xml files for your android project
- update color files
- update links inside your source files where needed

Create a file somewhere inside your root directory: `postprocess.sh`, specify its location in the `.hubble-mirror.json` file and run `hubble-mirror:postProcess`.

**Make sure this file is executable, if postprocess.sh is not executable by a shell, the process will fail!**

### Hubble deployPreview

Deploy the processed changes on a preview url with surge.
Run `hubble-mirror:deployPreview`.

Optionally add:

- domainsuffix: the domain on which we deploy with a unique suffix, for example the jenkins build number
- rootDir: the absolute path to the root directory where the hubble-mirror file can be found (default to the current directory)

Conventions:

- add a hubble:buildPreview script inside the package.json if you need a custom build step for your website
- add SURGE_LOGIN and SURGE_TOKEN as process environment variables to be able to publish with surge
- add the directory you want to publish to the .hubble-mirror.json
- add the previewUrl you want to the .hubble-mirror.json
  - this will be concatenated with the optional domainsuffix and .surge.sh
  - to become for example: https://hubble-mirror-domain-preview-url-build_25.surge.sh
- add the baseUrl if you have a paid version of surge
  - this will be concatenated with the optional domainsuffix
  - to become for example: https://hubble-mirror-domain-preview-url-build_25.inthepocket.design

### Create Pull Request

To autogenerate a Pull Request on your repo, we've added a utility script: `hubble-mirror:createPR`

Optionally add:

- domainsuffix: the domain on which we deploy with a unique suffix, for example the jenkins build number
- rootDir: the absolute path to the root directory where the hubble-mirror file can be found (default to the current directory)
- commitMessage: the title of the PR
- changelog: the description of the PR
- commitDate: the date related to the PR
- branch: the bitbucket source branch
- repo: the bitbucket repoPath

## Development

### Releasing

Bump version correctly, then run the `release` run-script. It will test the code before publishing and tag it with the correct git tag.

```shell
# To go from 0.0.4 to 0.1.0

$ npm version minor
$ npm run release
```

If you are making changes to the install script, make sure to deploy it. This sends the script + its assets to a _public_ Google Cloud bucket.
You will need [gsutil] installed, must be logged in with it and have access to the `hubble-static` bucket

```shell
$ npm run deploy:install-script
```

[logo]: https://github.com/inthepocket/hubble-mirror/blob/master/.github/hubble-mirror-banner.png
[license]: https://github.com/inthepocket/hubble-mirror/blob/master/LICENSE
[releases]: https://github.com/inthepocket/hubble-mirror/releases
[latest release]: https://github.com/inthepocket/hubble-mirror/releases/latest
[gsutil]: https://cloud.google.com/storage/docs/gsutil