Vela, our next-generation charting platform, is live at vela.luxalgo.com.
LuxAlgo

Server-side storage

Connect every Vela Pro persistence adapter and module storage port to a REST backend for authenticated users.

View as Markdown

By default, Vela Pro stores workspace layouts, drawings, indicator templates, favorites, editor drafts, and module data in localStorage. Connecting every adapter and module port to your backend lets authenticated users access their layouts, drawings, indicators, watchlists, alerts, and trading journal across browsers and devices.

Example REST endpoints

The adapters on this page target a user-scoped REST API where each route stores and returns opaque JSON payloads for the signed-in user:

EndpointHTTP methodsStored payload
/api/users/me/state/:keyGET, PUTWorkspace state document (workspace) and Pine code editor draft (vela-pro-editor)
/api/users/me/drawings/:chart/:symbolGET, PUT, DELETEPer-symbol drawings for a single chart key and symbol
/api/users/me/indicator-templates and /:idGET (list), PUT, DELETESaved indicator templates
/api/users/me/indicator-favoritesGET, PUTStarred built-in, library, and custom script favorites
/api/users/me/watchlistsGET, PUTWatchlists and watchlist display preferences
/api/users/me/alertsGET, PUTAlert rules and alert firing log
/api/users/me/journalGET, PUTTrading journal accounts, fills, notes, and annotations

Each GET endpoint returns 404 when a user has no saved record yet. Your server does not need to inspect or transform the JSON bodies.

Request helper

All adapters below share two helper utilities: request attaches bearer authentication headers, and userDoc wraps a single JSON document endpoint. Crucially, userDoc distinguishes a failed network read from an empty 404 record and blocks outbound writes until an initial read succeeds, preventing transient server errors at page load from overwriting saved user data with empty defaults.

declare function getAccessToken(): string; // application auth token provider

export function request(path: string, init: RequestInit = {}): Promise<Response> {
    const headers = { authorization: `Bearer ${getAccessToken()}`, 'content-type': 'application/json' };
    return fetch(`/api/users/me/${path}`, { ...init, headers });
}

export function userDoc(path: string) {
    let readable = false;
    return {
        /** Returns stored JSON text, or null on 404. Throws on network or server errors. */
        async read(): Promise<string | null> {
            const res = await request(path);
            if (!res.ok && res.status !== 404) throw new Error(`${path}: ${res.status}`);
            readable = true;
            return res.ok ? await res.text() : null;
        },
        /** Fire-and-forget write that never rejects. */
        write(body: string): void {
            if (!readable) return;
            // Browsers cap keepalive request bodies at 64 KiB; larger payloads fall back to standard fetch.
            request(path, { method: 'PUT', body, keepalive: body.length < 60_000 }).catch(() => {});
        },
    };
}

Workspace state and editor draft

VelaStorage reads and writes raw strings by key. Preloading state keys before constructing VelaWorkspace allows storage.get() to return synchronously so the saved layout renders on the first paint rather than flashing default constructor options while awaiting a promise.

import type { VelaStorage } from '@luxalgo/vela/widget';

declare function userDoc(path: string): { read(): Promise<string | null>; write(body: string): void };

export async function loadStateStorage(keys: readonly string[]): Promise<VelaStorage> {
    const docs = new Map(keys.map((key) => [key, userDoc(`state/${encodeURIComponent(key)}`)]));
    const texts = new Map<string, string | null>();
    await Promise.all([...docs].map(async ([key, doc]) => texts.set(key, await doc.read())));
    return {
        get: (key) => texts.get(key) ?? null,
        set: (key, value) => docs.get(key)?.write(value),
    };
}

If an initial read fails, loadStateStorage rejects so your application can display an error state and retry rather than mounting an uninitialized workspace. Because the Pine code editor draft uses the same VelaStorage contract, one preloaded instance serves both 'workspace' and 'vela-pro-editor'. See Layouts and chart state for the full state document specification.

Per-symbol drawings

import type { SymbolDrawingsStorage } from '@luxalgo/vela-pro';

declare function request(path: string, init?: RequestInit): Promise<Response>;

const path = (key: { chart: string; symbol: string }): string =>
    `drawings/${encodeURIComponent(key.chart)}/${encodeURIComponent(key.symbol)}`;
const unread = new Set<string>();

export const drawingsStorage: SymbolDrawingsStorage = {
    async load(key) {
        const res = await request(path(key)).catch(() => null);
        if (res?.ok) return await res.json();
        if (res?.status !== 404) unread.add(path(key)); // failed read rather than 404; block overwrites
        return null;
    },
    save(key, doc) {
        if (unread.has(path(key))) return;
        const body = doc ? JSON.stringify(doc) : undefined;
        const keepalive = (body?.length ?? 0) < 60_000;
        request(path(key), { method: doc ? 'PUT' : 'DELETE', body, keepalive }).catch(() => {});
    },
};

The key.chart identifier is produced by chartKey. Configure chartKey explicitly if your application supports workspace tabs or multiple named layouts; see Drawing persistence.

Templates and favorites

import type { IndicatorFavorite, IndicatorFavoritesStorage, IndicatorTemplate, IndicatorTemplatesStorage } from '@luxalgo/vela-pro';

declare function request(path: string, init?: RequestInit): Promise<Response>;
declare function userDoc(path: string): { read(): Promise<string | null>; write(body: string): void };

const one = (id: string): string => `indicator-templates/${encodeURIComponent(id)}`;

export const templatesStorage: IndicatorTemplatesStorage = {
    async list() {
        const res = await request('indicator-templates');
        if (!res.ok) throw new Error(`Templates: ${res.status}`);
        return (await res.json()) as IndicatorTemplate[];
    },
    async save(template) {
        const res = await request(one(template.id), { method: 'PUT', body: JSON.stringify(template) });
        if (!res.ok) throw new Error(`Template: ${res.status}`); // surfaced in the save dialog
    },
    async remove(id) {
        await request(one(id), { method: 'DELETE' });
    },
};

const favorites = userDoc('indicator-favorites');

export const favoritesStorage: IndicatorFavoritesStorage = {
    load: async () => JSON.parse((await favorites.read()) ?? '[]') as IndicatorFavorite[],
    save: (list) => favorites.write(JSON.stringify(list)),
};

See Indicator templates and Indicator persistence for adapter lifecycle details.

Module storage ports

Watchlist, Alerts, and Journal persist user records through dedicated module ports. The Trading module has no client-side storage port because orders, positions, and executions reside on your brokerage backend; see Broker integration.

import type { AlertEvent, AlertRule, AlertsBackend } from '@luxalgo/vela-pro-alerts';
import type { JournalData, JournalStore } from '@luxalgo/vela-pro-journal';
import type { WatchlistState, WatchlistStorage } from '@luxalgo/vela-pro-watchlist';

declare function userDoc(path: string): { read(): Promise<string | null>; write(body: string): void };

const parse = <T>(text: string | null): T | null => (text ? (JSON.parse(text) as T) : null);

const lists = userDoc('watchlists');
export const watchlistStorage: WatchlistStorage = {
    load: async () => parse<WatchlistState>(await lists.read()),
    save: (state) => lists.write(JSON.stringify(state)),
};

const journalDoc = userDoc('journal');
export const journalStore: JournalStore = {
    load: async () => parse<JournalData>(await journalDoc.read()),
    save: async (data) => journalDoc.write(JSON.stringify(data)),
};

/** AlertsBackend.load() is synchronous, so preload alert state before calling enableVelaPro(). */
export async function loadAlertsBackend(): Promise<AlertsBackend> {
    const doc = userDoc('alerts');
    const kept = parse<{ rules: AlertRule[]; events: AlertEvent[] }>(await doc.read());
    return { load: () => kept ?? { rules: [], events: [] }, save: (state) => doc.write(JSON.stringify(state)) };
}

Refer to Watchlist, Alerts, and Journal for each port's schema. Client-side alerts evaluate only while the page is open in a browser; to trigger notifications while the user is offline, evaluate saved AlertRule definitions on your server as well.

Complete initialization

Preload the synchronous stores (loadStateStorage and loadAlertsBackend) in parallel before calling enableVelaPro() and constructing VelaWorkspace. All remaining stores load asynchronously in the background. Optional domain modules such as Trading and Journal are registered via the plugins array.

import { VelaWorkspace } from '@luxalgo/vela/workspace';
import type { VelaStorage } from '@luxalgo/vela/widget';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro, type IndicatorFavoritesStorage, type IndicatorTemplatesStorage, type SymbolDrawingsStorage } from '@luxalgo/vela-pro';
import type { AlertsBackend } from '@luxalgo/vela-pro-alerts';
import { journal, type JournalStore } from '@luxalgo/vela-pro-journal';
import { trading, type Broker } from '@luxalgo/vela-pro-trading';
import type { WatchlistStorage } from '@luxalgo/vela-pro-watchlist';

declare function loadStateStorage(keys: readonly string[]): Promise<VelaStorage>;
declare function loadAlertsBackend(): Promise<AlertsBackend>;
declare const drawingsStorage: SymbolDrawingsStorage;
declare const templatesStorage: IndicatorTemplatesStorage;
declare const favoritesStorage: IndicatorFavoritesStorage;
declare const watchlistStorage: WatchlistStorage;
declare const journalStore: JournalStore;
declare const myBroker: Broker;

const [stateStorage, alertsBackend] = await Promise.all([loadStateStorage(['workspace', 'vela-pro-editor']), loadAlertsBackend()]);

enableVelaPro({
    symbolDrawings: { storage: drawingsStorage },
    indicatorTemplates: { storage: templatesStorage },
    indicatorLibrary: { favorites: favoritesStorage },
    codeEditor: { storage: stateStorage },
    watchlist: { storage: watchlistStorage },
    alerts: { backend: alertsBackend },
    plugins: [trading({ broker: myBroker }), journal({ store: journalStore })],
});

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    timeframe: '60',
    live: true,
    providers: { binance: () => new BinanceProvider() },
    persist: 'workspace',
    storage: stateStorage,
});

Pass all storage adapters in that single enableVelaPro() call. Because each feature installs once per page, storage options passed to a subsequent enableVelaPro() call are ignored.

Implementation notes

Initial loading behavior

StoreWhen load / get runsUI state while awaiting an async response
Workspace state documentOnce during new VelaWorkspace(...)Async promises render constructor defaults first, then switch to the saved layout. Preload before construction (as shown above) to avoid a layout switch.
Per-symbol drawingsWhenever a chart displays a symbol while holding zero drawingsRenders the chart without drawings until resolved. Drawings created by the user before resolution take precedence over the response.
Templates and favoritesOnce during enableVelaPro()Empty list until resolved; stars toggled in the meantime are preserved.
WatchlistsOnce during enableVelaPro()Empty panel until resolved; defaultSymbols seeds a starter list only after load() resolves with null.
AlertsSynchronously during enableVelaPro()Preload before calling enableVelaPro().
JournalOnce during enableVelaPro()Empty journal view until resolved.
Editor draftOn first editor open or programmatic editor API callStarter script template or configured initialSource.

Write timing and page unload

StorePayload writtenDebounce / triggerUnload behavior
Workspace state documentFull state document500 ms after last changeFlushed on beforeunload
Per-symbol drawingsSingle chart + symbol document, or null300 ms after last changeFlushed on pagehide
Indicator templatesSingle IndicatorTemplateImmediate on save, rename, or deleteNo queued writes
Indicator favoritesFull IndicatorFavorite[] array400 ms after last changeNot flushed on unload
WatchlistsFull WatchlistStateImmediate on every changeNo queued writes
AlertsAll AlertRule items plus up to 300 recent firing events200 ms after last changeNot flushed automatically; call alertsController()?.flush() on pagehide
JournalFull JournalData snapshot250 ms after last changeNot flushed on unload
Editor draftScript source string400 ms after last editNot flushed on unload

Keep the following operational characteristics in mind when sizing and securing your endpoints:

  • Unawaited writes: Most stores (VelaWorkspace, Watchlist, Journal, per-symbol drawings) invoke write methods without awaiting or catching returned promises. Handle network errors inside your adapter methods, as userDoc.write() does above.
  • Unload delivery limits: Use fetch(..., { keepalive: true }) so unload flushes survive page navigation. While navigator.sendBeacon also survives navigation, it cannot send custom Authorization headers and works only with cookie-authenticated endpoints. Browsers cap concurrent keepalive and beacon payloads at 64 KiB.
  • Payload growth: Workspace state documents embed the full Pine Script® source of every indicator added from the menu across all chart cells, and JournalStore writes the complete journal dataset on each trade fill. Configure backend request body limits accordingly, and disable keepalive when payloads approach 64 KiB.
  • Last-write-wins concurrency: Stores fetch their state once at startup and write full snapshots on change without merging across open browser tabs or multiple devices. Enforce optimistic concurrency or document versioning on your backend if required, and call indicatorTemplatesController()?.reload() when refreshing templates externally.

Session and user switching

Feature stores and module ports initialize once when enableVelaPro() executes. When a user signs out or switches accounts, perform a full page reload so no cached in-memory state carries over between sessions.

If you retain localStorage persistence on shared devices instead of using backend storage, namespace every key with the authenticated user's ID: pass user-specific persist strings to VelaWorkspace and codeEditor, a user prefix to new LocalSymbolDrawingsStorage(prefix), and user-scoped keys to new LocalIndicatorTemplatesStorage(key), localIndicatorFavoritesStorage(key), new LocalWatchlistStorage(key), new LocalAlertsBackend(key), new LocalJournalStore(key), and trading({ paper: { persist: key } }).

Migrating from localStorage

When migrating an existing application from localStorage to server-side storage, run a one-time upload of existing browser records before calling enableVelaPro(). Refer to Overview for the default localStorage keys. For single-key stores, check whether your backend returns 404, read the local value (localStorage.getItem('vela-workspace'), new LocalWatchlistStorage().load(), and equivalents), upload it via PUT, and remove the local key upon success.

Per-symbol drawings store one localStorage entry per chart and symbol under vela-pro.drawings:<chart>:<symbol>:

import { DEFAULT_SYMBOL_DRAWINGS_KEY } from '@luxalgo/vela-pro';

declare function request(path: string, init?: RequestInit): Promise<Response>;

/** Uploads locally cached per-symbol drawings without overwriting existing server records. */
export async function migrateLocalDrawings(): Promise<void> {
    const prefix = `${DEFAULT_SYMBOL_DRAWINGS_KEY}:`;
    for (const entry of Object.keys(localStorage).filter((k) => k.startsWith(prefix))) {
        const name = entry.slice(prefix.length);
        const at = name.lastIndexOf(':'); // default symbol keys strip the provider colon
        if (at < 0) continue;
        const path = `drawings/${encodeURIComponent(name.slice(0, at))}/${encodeURIComponent(name.slice(at + 1))}`;
        const existing = await request(path);
        if (existing.status === 404) {
            const put = await request(path, { method: 'PUT', body: localStorage.getItem(entry) });
            if (!put.ok) continue; // retain local entry to retry on next load
        } else if (!existing.ok) continue;
        localStorage.removeItem(entry);
    }
}

If your server-side chartKey naming convention differs from the default DOM-derived chart names stored in localStorage, remap the chart key segment before uploading.

On this page