# Upgrading (/vela-pro/reference/upgrading)



Upgrading Vela Pro involves checking out a newer release tag in your local clone, rebuilding the root package and module packages, and updating the packages in your application. This page covers the upgrade steps, compatible versions of Vela's open-source core (`@luxalgo/vela`), the UI kit, and the Pine Script® engine, and release-by-release migration notes.

## Updating your clone [#updating-your-clone]

Releases in the repository are tagged with a `v` prefix, from `v0.3.3` through `v0.5.12`. Check out an explicit release tag rather than tracking a branch so your builds remain reproducible.

<Steps>
  <Step title="Check out the release tag">
    ```bash
    git fetch --tags
    git checkout v0.5.12
    ```
  </Step>

  <Step title="Review the changelog">
    `CHANGELOG.md` at the repository root lists every release in reverse chronological order. Breaking changes end with a parenthetical note starting with `Breaking:`. Review all entries between your previous release and the target tag.
  </Step>

  <Step title="Install dependencies and build">
    ```bash
    npm install
    npm run build:plugins
    ```

    `npm install` installs dependencies and rebuilds `dist/`. `npm run build:plugins` builds the six domain modules, which are maintained as separate workspace packages under `plugins/` (referred to as plugins in the API).
  </Step>

  <Step title="Update your application">
    Re-pack or re-link the rebuilt packages into your application using the workflow in [Installation](/vela-pro/get-started/setup). If the version table below requires a newer `@luxalgo/vela` release than your application currently declares, update `@luxalgo/vela` in your application's `package.json` in the same change.
  </Step>
</Steps>

## Peer and dependency versions [#peer-and-dependency-versions]

Vela Pro `0.5.12` declares the following dependency ranges in `package.json`. Under npm semver rules, caret ranges on `0.x` versions accept patch updates within the same `0.minor` line only.

| Package                                              | Declared range | Accepted versions                    | Fresh clone version |
| ---------------------------------------------------- | -------------- | ------------------------------------ | ------------------- |
| `@luxalgo/vela` (core)                               | `^0.10.9`      | `0.10.9` and later `0.10.x` releases | `0.10.9`            |
| `@luxalgo/vela-ui` (UI kit, peer dependency)         | `^0.4.2`       | `0.4.2` and later `0.4.x` releases   | `0.4.2`             |
| `@luxalgo/vela-pinets` (Pine Script® engine)         | `^0.3.4`       | `0.3.4` and later `0.3.x` releases   | `0.3.4`             |
| `pinets` (peer dependency of `@luxalgo/vela-pinets`) | `>=0.13.0`     | `0.13.0` and later                   | `0.13.1`            |

All six module packages are at `0.1.2` and build from the same Vela Pro checkout, so their versions always match the root package.

`@luxalgo/vela-ui` is declared as a peer dependency so Vela Pro shares the copy installed alongside the core. A version outside the peer range fails `npm install` rather than bundling a second copy.

<Warning>
  Your application must resolve a single copy of `@luxalgo/vela`. When two copies are present, `enableVelaPro()` registers features into one instance while `VelaWorkspace` reads from the other, causing Vela Pro features to stay hidden with no runtime error. After every upgrade, run `npm ls @luxalgo/vela` in your application and confirm that only one version is listed. See [Installation](/vela-pro/get-started/setup) for details.
</Warning>

If you are upgrading to an earlier `0.5.x` release, check these minimum declared versions:

| Vela Pro             | Core (`@luxalgo/vela`) | UI kit (`@luxalgo/vela-ui`) | Pine Script® engine (`@luxalgo/vela-pinets`) |
| -------------------- | ---------------------- | --------------------------- | -------------------------------------------- |
| `0.5.12`             | `0.10.9`               | `0.4.2`                     | `0.3.4`                                      |
| `0.5.11`             | `0.10.8`               | `0.4.2`                     | `0.3.4`                                      |
| `0.5.9` and `0.5.10` | `0.10.7`               | `0.4.2`                     | `0.3.4`                                      |
| `0.5.4` to `0.5.8`   | `0.10.5`               | `0.4.1`                     | `0.3.4`                                      |
| `0.5.3`              | `0.10.4`               | `0.4.0`                     | `0.3.3`                                      |
| `0.5.0` to `0.5.2`   | `0.10.3`               | `0.3.0`                     | `0.3.3`                                      |

Upgrading `@luxalgo/vela` may also include core changes. See [Upgrading](/vela/user/upgrading) in the core documentation.

## Release notes and breaking changes [#release-notes-and-breaking-changes]

Releases are listed newest first. Versions omitted below (`0.5.1` to `0.5.4` and `0.5.6` to `0.5.10`) require no code changes beyond meeting the minimum dependency versions above.

### 0.5.12 [#0512]

**Per-symbol drawing storage.** Previously, drawings remained on the chart at the same price levels when switching symbols. Each chart now scopes drawings to the symbol they were created on, removing them when switching symbols and restoring them when returning. Drawings are persisted automatically as the user draws, defaulting to browser `localStorage` unless you provide a custom adapter via `symbolDrawings: { storage }`.

Two scenarios require explicit configuration:

* Pass `symbolDrawings: false` to retain the previous symbol-independent behavior.
* If your application loads multiple documents (such as tabs or named layouts) into the same workspace, configure `chartKey` so drawings from one document do not overwrite drawings saved under another document for the same symbol:

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';

let documentId = 'layout-1';

enableVelaPro({
    symbolDrawings: { chartKey: ({ cellId }) => `${documentId}/${cellId}` },
});

// Update the key before applying another document to the same workspace:
documentId = 'layout-2';
```

`chartKey` is evaluated on every save and load, so update `documentId` before calling `applyState()`. See [Drawing persistence](/vela-pro/persistence/stores/drawings) for storage key details.

**Minimum core version `0.10.9`.** Applications pinning `@luxalgo/vela` to `0.10.8` must bump the version range to install `0.5.12`.

**Partial persistence for `trading({ display })`.** Only display settings explicitly toggled by the user are persisted, while untouched settings inherit your `display` option. Returning users who have not customized a display setting now see updates to your `display` configuration. States saved by earlier releases are migrated using the same rule by preserving values that differ from Vela Pro's built-in defaults.

### 0.5.11 [#0511]

Requires `@luxalgo/vela` `0.10.8` or later, where zooming out is no longer clamped once all loaded bars fit inside the chart. Short bar series can shrink into a narrower band with empty space on both sides. No application code changes are required.

### 0.5.5 [#055]

**Removed `@luxalgo/vela-pro/components` subpath.** The economic calendar previously exported from `@luxalgo/vela-pro/components` is now distributed as the `@luxalgo/vela-pro-calendar` module package. Import `calendar` from `@luxalgo/vela-pro-calendar` and pass it in `plugins`, or call `enableCalendar()` from the same package:

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';
import { calendar, type CalendarSource } from '@luxalgo/vela-pro-calendar';

declare const myCalendarSource: CalendarSource;

enableVelaPro({ plugins: [calendar({ source: myCalendarSource })] });
```

### 0.5.0 [#050]

Upgrading from `0.4.x` introduces the domain modules. No `0.4.x` options or exports were removed or renamed, though minimum dependency versions increased (see the table above) and `enableVelaPro()` enables additional interface features by default.

**Expanded `enableVelaPro()` defaults.** Calling `enableVelaPro()` now enables the side rail (`sideRail`), bottom dock (`bottomDock`), Watchlist (`watchlist`), Alerts (`alerts`), Order Book (`orderBook`), enhanced symbol search (`symbolSearch`), rich tooltips (`richTooltips`), drawing context menus (`drawingMenus`), and indicator templates (`indicatorTemplates`) by default. Pass `false` for any feature you want to disable:

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';

enableVelaPro({ orderBook: false, symbolSearch: false });
```

Additional behavioral changes in `0.5.0`:

* While the Alerts module is enabled, the topbar bell button is replaced by the Alerts entry in the side rail. Pass `alerts: { topbarBell: true }` to retain the topbar bell.
* The bottom dock displays one active panel at a time, toggled from the side rail without a tab strip. Custom panels registered with `registerBottomPanel` receive a side rail button automatically (pass `rail: false` to omit the button) and can render custom headers (`chrome: 'none'`).
* Vela Pro side panels occupy a full-height column next to the charts. Custom side panels can use the same layout by setting `placement: 'column'` in the core SDK.
* Modules store user data (watchlists, alerts, paper trading accounts, and journal entries) in browser `localStorage` until you supply backend ports. See [Modules and widgets](/vela-pro/modules/overview).
* For single-chart pages, construct `VelaWorkspace` with `layout: false`.

## Related [#related]

* [Installation](/vela-pro/get-started/setup)
* [Troubleshooting](/vela-pro/reference/troubleshooting)
* [Configuration precedence](/vela-pro/persistence/precedence)
