Streaming & Timestack
Relevant source files
The following files were used as context for generating this wiki page:
The Streaming and Timestack features in vitepress-plugin-chartjs provide advanced temporal data visualization capabilities. Streaming allows for real-time, scrolling data updates, while Timestack introduces a specialized dual-row time scale for better context in time-series analysis. These features are implemented as external plugins that must be registered within the VitePress theme to extend the core Chart.js functionality.
Sources: example/plugins/streaming.md:1-5, example/plugins/timestack.md:1-4, README.md:11-14
Real-time Data Streaming
The streaming feature is powered by @aziham/chartjs-plugin-streaming, which enables automatic scrolling and real-time visualization of live data. It is a modernized fork for Chart.js 4.x.
Architecture and Integration
Streaming charts require a date adapter (typically Luxon) to handle time-based axes. While static YAML configurations can display the initial state of a streaming chart, full dynamic updates require JavaScript callbacks, specifically the onRefresh function, to push new data points into the chart instance at runtime.
The following diagram illustrates the flow of data during a refresh cycle in a streaming chart:
The streaming cycle ensures that data is appended to the dataset while the X-axis (type realtime) shifts to maintain the specified duration window.
Sources: example/plugins/streaming.md:1-8, example/plugins/streaming.md:43-75
Configuration Options
Streaming behavior is configured through the realtime object within scale options or the streaming object within plugin options.
| Option | Type | Default | Description |
|---|---|---|---|
duration | number | 10000 | Total ms of data visible on the chart |
refresh | number | 1000 | Interval between data refreshes in ms |
delay | number | 0 | Delay before data appears on the chart |
ttl | number | - | Time-to-live for data points in ms |
pause | boolean | false | Whether to temporarily stop streaming |
Sources: example/plugins/streaming.md:88-103, example/plugins/streaming.md:113-120
Timestack Scale
The chartjs-scale-timestack provides a specialized temporal scale that renders time information in two stacked rows. This layout is designed to show high-granularity ticks on top (e.g., minutes/hours) while providing broader context on the bottom (e.g., days/months).
Logic and Data Requirements
Unlike standard scales, the Timestack scale requires data points to be provided in an {x, y} object format where x is a millisecond timestamp. The scale does not automatically parse strings or labels as time values.
The dual-row representation allows for dense data visualization without losing temporal context.
Sources: example/plugins/timestack.md:1-18, example/plugins/timestack.md:162-175
Scale-Specific Parameters
The Timestack scale includes unique parameters to control the density and threshold of floating ticks.
| Parameter | Default | Description |
|---|---|---|
density | 0.5 | Target density for labels (0 to 1) |
max_density | 0.75 | Maximum allowed label density |
left_floating_tick_thres | 0.33 | Threshold for rendering floating left ticks |
datetime | {} | Luxon-specific creation options like zone/locale |
Sources: example/plugins/timestack.md:150-160
Plugin Registration and Setup
Both Streaming and Timestack are external extensions that must be registered in the VitePress theme configuration (.vitepress/theme/index.ts). Because these plugins interact with the DOM and browser-specific APIs (like requestAnimationFrame), they must be imported dynamically within a window check to ensure SSR compatibility.
Registration Requirements
- Streaming: Requires
chart.js,chartjs-adapter-luxon, and@aziham/chartjs-plugin-streaming. - Timestack: Requires
luxonandchartjs-scale-timestack. It self-registers upon import. - Core Styles:
vitepress-plugin-chartjs/style.cssmust be imported for the chart containers to render properly.
Sources: example/plugins/setup.md:21-28, example/plugins/streaming.md:23-27, example/plugins/timestack.md:20-24
Summary
The Streaming and Timestack features extend the plugin's capabilities into dynamic and high-density time-series visualization. Streaming enables live monitoring use cases such as server metrics or IoT sensor data through the realtime scale type. Timestack optimizes the presentation of static or historical time-series data by utilizing a dual-row scale architecture, provided the data adheres to strict millisecond timestamp formats. Both features rely on the plugin's build-time resolution for initial configuration while leveraging the client-side theme registration for runtime execution.
Sources: example/plugins/streaming.md:188-195, example/plugins/timestack.md:177-183, src/markdown/index.ts:167-175