New page about Horizon client packaging

[deontologician]

There are a few different ways you can integrate Horizon client into your frontend app.

Main Horizon.js file

This is a UMD (universal module definition) built with:

• All of RxJS, including all operators
• Polyfills for:
  • Array.from
  • Array.findIndex
  • Array.keys
  • Object.assign

This is the package that is served by Horizon server at /horizon/horizon.js. It's located at require('@horizon/client/dist/horizon.js').

Use this if you are not using a bundler like Webpack or Browserify, and you'd like to get up and running quickly without worrying about polyfills and Horizon dependencies.

<script src="/horizon/horizon.js"></script>

Core Horizon.js file

This is a UMD without RxJS or any polyfills. It's a bit more work to get started with, but if you don't mind bringing your own RxJS and polyfills it is a much smaller bundle than the main horizon.js.

It's located at require('@horizon/client/dist/horizon-core.js')

Use this if you are not using a bundler like Webpack or Browserify, and you have already included RxJS, and you're handling your own polyfills.

<script src="https://npmcdn.com/@reactivex/rxjs/dist/global/Rx.umd.js"></script>
<script src="/horizon/horizon-core.js"></script>

Using Webpack or Browserify with ES5 sources

If you use a bundler like Webpack or Browserify, you can import the es5 sources like:

var Horizon = require('@horizon/client');

RxJS is a dependency, but we only patch in the operators we need in the Horizon library itself. Often you'll want other operators, so you'll have to require the patching modules yourself. For example, to get the toPromise and switchMap operators, you would add these lines somewhere in your source code:

require('rxjs/add/operator/toPromise');
require('rxjs/add/operator/switchMap');

This allows you to control the size of your bundle by not adding operators you don't need, but it may be very tedious adding everything individually. If you'd like to add all operators at once:

require('rxjs/Rx');

Using a bundler with ES6 sources

Horizon is written in es6 currently, so if you'd prefer to do something like to babelify our source along with your own in webpack or browserify, import it like:

import Horizon from '@horizon/client/src';

If you're using Rollup, we already have jsmain:next set, so you can just use:

import Horizon from '@horizon/client';

Similar to es5 above, you'll need to patch in exactly which RxJS operators you want to use. So:

import 'rxjs/add/operator/toPromise';
import 'rxjs/add/operator/switchMap';

Or for the kitchen sink:

import 'rxjs/Rx';

Node.js

If you're requiring the horizon client from Node.js, you'll also get the es5 sources, so everything mentioned there applies here as well. But in addition you'll need to provide a WebSocket polyfill, since that is not part of Node.js. If you install the ws package, you can add such a polyfill like:

global.WebSocket = require('ws');

[deontologician]

Eventually, we'll add stuff like React Native here, but for now this should be mostly everything

[zubair-io]

If I may sugesst a way to work with Typescript

Typescript

horizon/index.d.ts

declare module '@horizon/client' {
    const Horizon
    export default Horizon
}

typescript-file.ts

/// <reference path="horizon/index.d.ts" />
import {default as Horizon} from '@horizon/client';