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

Configuration precedence

Precedence rules between constructor options, saved workspace state documents, per-symbol drawing storage, and runtime API calls.

View as Markdown

Constructor options set the initial defaults for a new workspace. Once persist is enabled and a state document has been saved, Vela Pro restores the user's saved state over most constructor options on reload. This page documents the precedence order between constructor options, saved state documents, per-symbol drawing storage, and runtime API calls.

Saved state vs. workspace options

When persist is enabled, VelaWorkspace restores the saved state document during initialization, treating most constructor options as fallback defaults for new users without saved state.

Constructor optionBehavior when a saved state document exists
layoutRestores the saved layout if its ID is registered. Exception: passing layout: false forces a single-chart workspace regardless of the saved document.
symbol, timeframe, priceStyle, bars, session, and cells overridesCharts present in the saved document restore completely from the document. Constructor options seed only newly added chart slots missing from the document.
visibleRangeApplied only to charts initialized from constructor options; ignored on restored charts.
upColor, downColor, logScale, currentPriceLine, and other appearance optionsApplied first at construction, then overridden by each chart's saved rendererConfig.
timezoneUses the saved timezone from the document.
syncUses the saved sync links when present in the document.
indicators (manifest)Manifest entries with enabled: true mount only on charts that have no saved indicators; restored charts load their saved indicator set.
volumeRestored charts mount the volume study only if "volume" is listed in their saved indicators.
theme, locale options, providers, engines, live, topbar, sidebarExcluded from the state document; constructor options always govern these settings.

With an asynchronous storage adapter, initialization runs in two phases: the workspace first mounts using your constructor options, then applies the saved state document once storage.get() resolves.

Module settings vs. enabler options

Domain modules and Vela Pro features accept initial options in enableVelaPro() while persisting user adjustments in the workspace state document or dedicated stores. Whether changing a default option affects returning users depends on whether that setting is stored as a delta or saved in full:

Feature or module settingPrecedence rule
Trading displayDelta-tracked. Only display toggles explicitly changed by the user are written to ext['velapro.trading']. Untouched display fields always inherit your latest option value, even for returning users.
Trading safety, presets, and order sizeSaved in full inside the state document. Once saved, stored values take precedence over enabler options.
Order book settingsSaved in full. Keys present in ext['velapro.orderbook'] override enabler options.
Calendar settings and minImpactSaved in full. Stored values in ext['velapro.calendar'] override enabler options.
Watchlist defaultSymbolsSeeds the initial watchlist only when WatchlistStorage returns empty state.
Paper broker initialBalance, currency, and nameUsed only when creating the initial paper account; existing persisted accounts keep their stored attributes.
Code editor initialSourceUsed only when no editor draft exists in storage.

Settings marked "saved in full" write every field into the state document on each save regardless of whether the user modified it. Consequently, changing those option values in code affects only new users without saved state, whereas changes to Trading display options roll out automatically for any toggle a user has not overridden.

Applying a state document

Calling workspace.applyState(doc) replaces active workspace state rather than merging incrementally:

  • Each chart's symbol, timeframe, chart type, rendererConfig, drawings, and persisted indicators update to match doc. Tracked indicators absent from doc are removed from the chart.
  • Cross-chart sync links and splitter trackSizes adopt the document's values. Applying a document that omits those fields disables sync links and resets splitter proportions.
  • Workspace-level favorites, timeframeFavorites, and drawingTools are replaced only when those keys exist on doc.
  • Extension entries under ext restore only for keys present in doc. Modules whose keys are absent retain their current in-memory settings.

Always pass complete documents produced by workspace.getState(). See Layouts and chart state for details on when applyState() updates charts in place versus rebuilding cells.

State documents vs. per-symbol drawings

When per-symbol drawing storage is enabled, a chart's drawings for its active symbol can originate from either an applied state document or SymbolDrawingsStorage:

  1. A state document applied to a chart takes precedence when its drawings payload contains at least one drawing, replacing active drawings and updating the per-symbol store for that symbol.
  2. A state document with zero drawings never erases SymbolDrawingsStorage; the chart loads existing drawings for that symbol from the per-symbol store instead.
  3. Only explicit removal (user deletion in the UI or chart.drawings.clear() in code) clears a symbol's stored drawings.
  4. Applying multiple layout documents on the same workspace under a static chartKey causes non-empty layout drawings to overwrite one another under rule 1. Return a layout-specific prefix from chartKey when supporting tabs or saved layouts.

See Drawing persistence for full details and chartKey examples.

Host overrides vs. Vela Pro defaults

enableVelaPro() registers shell, renderer, and engine defaults that per-workspace or per-chart options can override:

Vela Pro defaultHost override with higher precedence
Corner attribution (watermark)enableVelaPro({ watermark }) configures the default read once by workspaces and charts constructed afterward. Calling chart.renderer.set('attribution', ...) overrides it on that individual chart. Attribution is excluded from the state document, so saved state never alters it. See Theming and branding.
Side railPassing an explicit sidebar option (including sidebar: false) to new VelaWorkspace(...).
Default Pine Script® enginePassing an explicit 'pine' entry in the workspace engines option.

Repeated enableVelaPro() calls

The first enableVelaPro() call on a page takes precedence for every feature and module it installs. Because each enabler registers once per page lifecycle, calling enableVelaPro() a second time cannot reconfigure an already-installed feature or disable it; a subsequent call can only enable features that were set to false in the first call and update watermark for workspaces constructed afterward.

This behavior directly affects persistence configuration: passing a custom storage adapter in a second enableVelaPro() call is ignored without throwing a warning. If drawings, templates, or module state continue writing to localStorage despite passing custom storage adapters, verify that no earlier module called enableVelaPro() during application bootstrap.

Resetting saved state

State to resetProcedure
Single workspace back to constructor optionsDelete the stored record under its persist key before constructing VelaWorkspace (with default storage, call localStorage.removeItem('vela-workspace')).
All users' workspaces after shipping new defaultsChange the persist key string passed to VelaWorkspace so previously saved documents are ignored.
Single module's layout preferencesRemove that module's key (such as velapro.trading) from the state document's ext object before applying or returning it from storage.get().
Drawings for one symbol on a chartCall chart.drawings.clear() while that symbol is active on the chart, which writes null to SymbolDrawingsStorage.save().
Indicator templates, favorites, watchlists, alerts, or journalDelete the corresponding backend record or the localStorage key listed in Overview.

VelaWorkspace never invokes storage.remove() and exposes no method to wipe persisted documents. Implement deletions and document schema migrations in your application code or inside your storage adapter's get() method.

On this page