Build-Time Dynamic Data

Relevant source files

The following files were used as context for generating this wiki page:

• src/markdown/resolver.ts
• src/markdown/index.ts
• example/charts/external.md
• README.md
• example/api.md
• example/public/charts/dynamic-line.js

Build-time dynamic data resolution is a core architectural feature of vitepress-plugin-chartjs that allows chart configurations to be generated or fetched during the documentation build process. This system ensures that the client-side bundle contains only pre-computed, static JSON configurations, eliminating the need for runtime fetching, reducing page load times, and enabling charts to work in offline or static environments.

The system supports loading data from various sources including local YAML/JSON files, JavaScript/ES modules (which can execute Node.js code), and remote HTTP(S) endpoints. By executing JavaScript at build time, developers can use Node.js APIs such as fs and path or perform complex mathematical computations to populate chart datasets.

Sources: README.md:12-16, example/charts/external.md:3-9

Architectural Overview

The plugin follows a Data-First architecture where all parsing, validation, and file I/O operations are offloaded to the build stage. The Markdown-it plugin identifies chart blocks and utilizes a build-time resolver to handle url: directives.

The diagram shows the transition of chart configuration from raw markdown or external files into a pre-validated JSON structure passed to the client-side component.
Sources: src/markdown/index.ts:161-174, src/markdown/resolver.ts:25-30

Build-Time Resolver Logic

The resolver is responsible for identifying the file type and selecting the appropriate execution or parsing strategy. It operates synchronously within the Markdown-it rendering lifecycle using Node.js child processes to handle asynchronous operations like dynamic imports and network requests.

Supported Resolution Strategies

Source Type	File Extension	Resolution Method	Capability
Static Data	.yaml, .json	fs.readFileSync	Direct parsing of static configuration.
JS Modules	.js, .mjs	execSync + import()	Executes code in Node.js; supports fs, path, and npm packages.
Remote API	http://, https://	execSync + fetch()	Fetches external data via HTTP during the build.

Sources: src/markdown/resolver.ts:31-62, example/charts/external.md:112-117

JavaScript Module Execution

JavaScript files are resolved by spawning a child process that dynamically imports the module. The resolver identifies the default export, which can be an object, a function, or an asynchronous function. If it is a function, it is executed, and the resulting object is serialized to JSON for the client.

Dynamic Data Generation Patterns

Because JavaScript modules run in a Node.js context at build time, they can perform operations impossible in a standard browser-based chart configuration.

1. Mathematical Computation

Complex datasets, such as sine waves or scatter plot clusters, can be computed programmatically rather than manually defined in YAML.
Sources: example/charts/external.md:86-89

2. Node.js API Integration

Modules can utilize the full power of Node.js. A common pattern involves reading local data files that are not part of the public web directory.

// Example: Reading a local JSON file via Node.js FS
import { readFileSync } from 'fs';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';

export default function () {
  const __dir = dirname(fileURLToPath(import.meta.url));
  const data = JSON.parse(readFileSync(join(__dir, 'data.json'), 'utf-8'));

  return {
    type: 'bar',
    data: {
      labels: data.labels,
      datasets: [{ data: data.values }]
    }
  };
}

Sources: example/charts/external.md:144-168

3. Build-Time API Fetching

By exporting an async function, the plugin can fetch data from external APIs during the build process. The client receives the data as if it were local, removing the latency of client-side fetch calls.
Sources: example/charts/external.md:58-62, README.md:110-116

Validation and Normalization

Before the resolved data is passed to the Vue component, it undergoes strict validation:

1. Zod Schema Validation: Ensures the configuration contains required fields like type and follows the ChartConfig structure.
2. Color Application: If datasets lack colors, the plugin applies the colorPalette or DEFAULT_COLORS at build time.
3. Option Merging: Global defaultOptions from the plugin configuration are merged with the specific chart's options.
4. Error Handling: If a file is missing, an HTTP request fails, or a JS module throws an error, the plugin renders a descriptive error box in the documentation instead of crashing the build.

Sources: src/markdown/index.ts:133-159, src/markdown/index.ts:223-238, src/markdown/resolver.ts:152-162

Summary

Build-Time Dynamic Data provides a robust bridge between static documentation and dynamic data sources. By shifting the complexity of data retrieval and computation to the build stage, vitepress-plugin-chartjs maintains high performance and reliability for the end-user while offering developers the flexibility of a full Node.js environment for chart configuration.