# Installation and delivery

> The hosted kit, the private npm registry and the source drop, and which one you want.

Section: Start here. Source: https://ortexcharts.com/docs/install

## Three Ways to Get the Library

ORTEX Charts is a commercial library, so the code does not come from public npm. There are
three delivery modes. They share one license-key system and one set of builds; they differ
only in what leaves ORTEX and how much of the plumbing you own.

| Mode | What you do | What you get | Who it suits |
|---|---|---|---|
| Hosted kit | Put one `<script>` tag on the page | A per-customer minified build with the key already installed, served from the ORTEX CDN and locked to the domains on the kit | Most buyers: brokers, data sites, dashboards, content-managed sites |
| Private registry | `npm install` with a token, set the key in code | The same minified builds as npm packages with TypeScript declarations | Product teams with a build pipeline |
| Source access | Clone a mirror of the repository under an OEM contract | TypeScript source, tests and the playground | OEM and enterprise agreements |

The hosted kit is the default because it needs the least trust on both sides: the key never
has to be handled by you, updates within a major version arrive without a deployment, and a
cancelled subscription simply stops being served.

## The Hosted Kit

A kit is a single JavaScript file built for one customer. It contains
`@ortex-charts/financial` and `@ortex-charts/ui` in an immediately-invoked bundle, a small
prelude carrying the kit metadata, and an epilogue that calls `setLicenseKey` with your key.

```html
<div id="chart" style="height: 520px"></div>
<script src="https://cdn.ortexcharts.com/v1/kit/YOUR_KIT_ID.js"></script>
<script>
  const shell = OrtexCharts.createChartShell(document.getElementById("chart"), {
    symbol: "AAPL",
    datafeed: myDatafeed
  });
</script>
```

Everything exported by the two packages is on the `OrtexCharts` global. There is no module
system involved, so `OrtexCharts.createFinancialChart`, `OrtexCharts.createChartShell`,
`OrtexCharts.registerIndicator` and the rest are all reachable directly.

Two properties are worth knowing about:

- `window.__ORTEX_CHARTS_KIT__` carries the kit id, key id, plan, library version and build
  time, which is what you quote in a support request.
- The CDN checks the request `Origin` or `Referer` against the domains registered on the kit
  before the bytes leave the edge, so a copied script tag on another host returns a 403
  rather than a working chart.

Kits auto-update within their major version. A new patch or minor release is picked up the
next time the file is fetched; a major version is a new URL, so nothing breaks under you.

## The Private Registry

Packages live in the GitLab package registry of the `ortex/ortex-charts` project. Two lines
in `.npmrc` point the `@ortex-charts` scope at it and supply a token.

```bash
# .npmrc — commit this file; the token comes from the environment
@ortex-charts:registry=https://gitlab.com/api/v4/projects/86057283/packages/npm/
//gitlab.com/api/v4/projects/86057283/packages/npm/:_authToken=${ORTEX_NPM_TOKEN}
```

The token is issued with the license, is scoped to reading this one package registry, and
expires with the license term. Never commit a real token. Export it in your shell for local
work and set it as a masked variable in continuous integration:

```bash
export ORTEX_NPM_TOKEN="the token from your license email"
npm install @ortex-charts/financial @ortex-charts/ui
```

npm, pnpm and yarn all read `.npmrc` in this form. Yarn Berry users who have moved to
`.yarnrc.yml` need the equivalent `npmScopes` entry pointing at the same URL.

### Which Packages to Install

| Package | Install it when | Depends on |
|---|---|---|
| `@ortex-charts/math` | You want the scales, sessions, resolutions or rolling statistics without a chart | Nothing |
| `@ortex-charts/core` | You are building a chart type of your own on the engine | `math` |
| `@ortex-charts/financial` | You want a price chart; re-exports all of `core` | `core`, `math` |
| `@ortex-charts/indicators-extra` | You want the 78 extra studies as well as the 51 built in, 129 in all | `financial` |
| `@ortex-charts/ui` | You want the toolbar, drawing rail and layouts | `financial` |
| `@ortex-charts/lite` | You want sparklines in a table | `math` only |
| `@ortex-charts/viz` | You want treemaps, heatmaps, XY, pie or Sankey charts | `core`, `math` |
| `@ortex-charts/migrate` | You are coming from TradingView or Highcharts | `ui`, `viz` |
| `@ortex-charts/react` | You prefer components and hooks | All of the above |

Installing `@ortex-charts/ui` pulls in `financial`, `core` and `math` transitively; you do
not have to list them, though listing the ones you import from is good practice.

Every package is published at the same version — see [Release
notes](https://ortexcharts.com/docs/changelog) — ships ECMAScript modules with declaration files, is marked
side-effect free, and has a single entry point. There are no CommonJS builds and no source
maps outside the OEM mode.

## Source Access Under OEM

An OEM or enterprise agreement includes read access to a mirror of the repository: the
TypeScript source of every package, the unit and visual test suites, and the playground
application. Building it is `pnpm install && pnpm build`, which writes
`packages/*/dist`. The contract, not the code, is what makes this mode different, and it
is the only mode in which the source and the tests leave ORTEX.

## Bundler Notes

The packages are plain ECMAScript modules with `"sideEffects": false`, which is all a modern
bundler needs. A few specifics:

- **Tree shaking works, and it matters.** A chart built with `createFinancialChart` and no
  toolbar is about 56 KB gzipped; adding `@ortex-charts/ui` brings the full chart to about
  89.9 KB gzipped. Importing `@ortex-charts/viz` when you only wanted a sparkline is the usual
  way to pay for something you are not using.
- **Vite, Rollup, esbuild, webpack 5 and Next.js need no configuration.** There is no
  `require`, no Node built-in, and no import of CSS from a package other than
  `@ortex-charts/ui`, which injects its own stylesheet at runtime rather than shipping a
  `.css` file to import.
- **Webpack 4 and other bundlers without ECMAScript module support will not work**, because
  no CommonJS build is published.
- **There is nothing else to install.** No `@ortex-charts/*` package has a third-party
  runtime dependency, so an install adds the packages you asked for and nothing behind them.
  The maths that used to come from D3 is ours; where an algorithm was ported rather than
  rewritten, the file carries the ISC notice and the third-party notices list it.

## TypeScript

Declarations ship with every package, so no `@types` package is needed. The library is
written against `"module": "NodeNext"` semantics with explicit `.js` specifiers internally,
which means your `tsconfig.json` should use a modern module resolution mode:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "strict": true
  }
}
```

`"moduleResolution": "Bundler"` (or `"NodeNext"`) is required; the legacy `"Node"` mode
does not read the `exports` field and will not find the types. TypeScript 5.0 or later is
expected.

One import path is worth memorizing: **the data types live in `@ortex-charts/math`**.
`Bar`, `Tick`, `BarSeries`, `ValueSeries`, `Resolution` and `Session` are exported from
there, while everything about drawing a chart comes from `@ortex-charts/core` (re-exported
by `@ortex-charts/financial`). Installing `financial` puts `math` in `node_modules`
transitively, but listing it in `package.json` is worth it if you import the types.

```ts
import { createFinancialChart } from "@ortex-charts/financial";
import type { Bar, Tick } from "@ortex-charts/math";
```

Two further typing habits make the API pleasant. Options objects are `DeepPartial`, so you only
write the keys you are changing. Series options are keyed by series type, so
`chart.addSeries("candlestick", { … })` narrows to `CandlestickSeriesOptions` and
`chart.addSeries("histogram", { colorMode: "sign" })` type-checks without a cast.

## Server-Side Rendering

The library is browser-only. It creates canvases, reads `devicePixelRatio`, attaches
pointer listeners and observes element sizes, none of which exist on a server. There is no
server-side rendering mode and none is planned; chart images for emails and social cards
are a separate problem, better solved by a rendering service.

In practice this means one rule: **create the chart inside an effect, never during render.**

```tsx
"use client";

import { useEffect, useRef } from "react";
import { createFinancialChart, type Bar } from "@ortex-charts/financial";

export function PriceChart({ bars }: { bars: Bar[] }) {
  const ref = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (!ref.current) return;
    const chart = createFinancialChart(ref.current, { data: bars, resolution: "1D" });
    return () => chart.remove();
  }, [bars]);

  return <div ref={ref} style={{ height: 460 }} />;
}
```

The components in [`@ortex-charts/react`](https://ortexcharts.com/docs/react) already do this: they create the
chart in a layout effect guarded by a `typeof window` check, so they render an empty
container on the server and fill it on hydration. In Next.js the file still needs the
`"use client"` directive, because the effect only runs in a client component.

## Content Security Policy

The library needs no `unsafe-eval` and makes no network requests of its own, with one opt-in
exception: `setLicenseKey(key, { revocationList })` reads one JSON document from the URL you
name, once, after the key verifies. Hosted kits set it to the ORTEX CDN. Three directives are
worth checking:

- `img-src data:` is needed if the ORTEX mark is shown, because the wordmark is drawn from
  an inline data URI. It is also needed for symbol logos supplied as data URIs.
- `connect-src` must allow your own feed hosts when you use `websocketSource` or a datafeed;
  the library uses the browser `fetch` and `WebSocket` you would have used yourself.

Hosted-kit users additionally need `script-src https://cdn.ortexcharts.com` and
`connect-src https://cdn.ortexcharts.com` for the revocation list; a registry install that
does not pass `revocationList` needs neither.

## Verifying the Installation

The fastest check that everything resolved, the key is valid and the browser is happy:

```ts
import { createFinancialChart, licenseStatus, setLicenseKey } from "@ortex-charts/financial";

await setLicenseKey(KEY);
console.log(licenseStatus());
// { state: "valid", verified: true, message: "Licensed", payload: { customer, tier, features, domains, exp } }

const chart = createFinancialChart(document.body.appendChild(document.createElement("div")), {
  height: 300,
  data: [{ time: Date.now(), open: 1, high: 2, low: 0.5, close: 1.5, volume: 10 }],
});
```

A `state` of `unlicensed`, `expired`, `domain` or `invalid` is explained in
[license keys](https://ortexcharts.com/docs/licensing). On `localhost` none of them stop the chart from drawing; on
any other host every one of them does, and the chart paints a licence notice instead.