Configuration precedence
Precedence rules between constructor options, saved workspace state documents, per-symbol drawing storage, and runtime API calls.
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 option | Behavior when a saved state document exists |
|---|---|
layout | Restores 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 overrides | Charts present in the saved document restore completely from the document. Constructor options seed only newly added chart slots missing from the document. |
visibleRange | Applied only to charts initialized from constructor options; ignored on restored charts. |
upColor, downColor, logScale, currentPriceLine, and other appearance options | Applied first at construction, then overridden by each chart's saved rendererConfig. |
timezone | Uses the saved timezone from the document. |
sync | Uses 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. |
volume | Restored charts mount the volume study only if "volume" is listed in their saved indicators. |
theme, locale options, providers, engines, live, topbar, sidebar | Excluded 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 setting | Precedence rule |
|---|---|
Trading display | Delta-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 size | Saved in full inside the state document. Once saved, stored values take precedence over enabler options. |
Order book settings | Saved in full. Keys present in ext['velapro.orderbook'] override enabler options. |
Calendar settings and minImpact | Saved in full. Stored values in ext['velapro.calendar'] override enabler options. |
Watchlist defaultSymbols | Seeds the initial watchlist only when WatchlistStorage returns empty state. |
Paper broker initialBalance, currency, and name | Used only when creating the initial paper account; existing persisted accounts keep their stored attributes. |
Code editor initialSource | Used 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 matchdoc. Tracked indicators absent fromdocare removed from the chart. - Cross-chart
synclinks and splittertrackSizesadopt the document's values. Applying a document that omits those fields disables sync links and resets splitter proportions. - Workspace-level
favorites,timeframeFavorites, anddrawingToolsare replaced only when those keys exist ondoc. - Extension entries under
extrestore only for keys present indoc. 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:
- A state document applied to a chart takes precedence when its
drawingspayload contains at least one drawing, replacing active drawings and updating the per-symbol store for that symbol. - A state document with zero drawings never erases
SymbolDrawingsStorage; the chart loads existing drawings for that symbol from the per-symbol store instead. - Only explicit removal (user deletion in the UI or
chart.drawings.clear()in code) clears a symbol's stored drawings. - Applying multiple layout documents on the same workspace under a static
chartKeycauses non-empty layout drawings to overwrite one another under rule 1. Return a layout-specific prefix fromchartKeywhen 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 default | Host 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 rail | Passing an explicit sidebar option (including sidebar: false) to new VelaWorkspace(...). |
| Default Pine Script® engine | Passing 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 reset | Procedure |
|---|---|
| Single workspace back to constructor options | Delete the stored record under its persist key before constructing VelaWorkspace (with default storage, call localStorage.removeItem('vela-workspace')). |
| All users' workspaces after shipping new defaults | Change the persist key string passed to VelaWorkspace so previously saved documents are ignored. |
| Single module's layout preferences | Remove 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 chart | Call chart.drawings.clear() while that symbol is active on the chart, which writes null to SymbolDrawingsStorage.save(). |
| Indicator templates, favorites, watchlists, alerts, or journal | Delete 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.