Build-Time Data Resolver

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
• src/index.ts

The Build-Time Data Resolver is a core architectural component of vitepress-plugin-chartjs responsible for fetching and parsing chart configurations during the VitePress build process. This system ensures that all data resolution—whether from local files, JavaScript modules, or remote HTTP endpoints—happens on the server.

By resolving data at build time, the client-side application receives a pre-computed JSON configuration, eliminating the need for runtime fetching, improving page load speeds, and ensuring charts work in offline or static environments.
Sources: src/markdown/index.ts:219-224, README.md:120-125, example/charts/external.md:5-10

Architecture and Data Flow

The resolver operates as part of the Markdown-it transformation pipeline. When the markdown parser encounters a chart or chartjs code block containing a url: directive, it invokes the resolver to transform that reference into actual data.

Resolution Logic Flow

The following diagram illustrates how the resolver determines the file type and executes the appropriate resolution strategy:

The resolver supports multiple protocols and file formats, utilizing Node.js child processes to handle synchronous execution of asynchronous tasks like fetching or dynamic imports.
Sources: src/markdown/resolver.ts:24-52, src/markdown/index.ts:265-275

Supported Resolution Strategies

The resolver categorizes URLs into three main strategies based on the source and file extension.

1. Local File Resolution (YAML/JSON)

For static configuration files, the resolver uses fs.readFileSync to pull content from the filesystem. It attempts to parse the content as JSON first, falling back to YAML if JSON parsing fails.
Sources: src/markdown/resolver.ts:114-121, src/markdown/resolver.ts:133-154

2. JavaScript Module Resolution (.js/.mjs)

JavaScript files allow for dynamic data generation. The resolver executes these files in a separate Node.js child process using execSync. This allows the plugin to support:

• Static Object Exports: Direct configuration objects.
• Function Exports: Synchronous functions that return data.
• Async Function Exports: Functions that fetch data from APIs or databases during the build.

// Example of a JS module resolved at build time
export default async function() {
  const data = await fetch('https://api.example.com/stats');
  return { type: 'bar', data: await data.json() };
}

Sources: src/markdown/resolver.ts:79-108, example/charts/external.md:73-85

3. Remote HTTP Resolution

The resolver can fetch raw text from remote URLs. Similar to JS modules, it uses a child process to perform a fetch synchronously relative to the main build thread, ensuring the Markdown-it plugin remains synchronous as required by the library.
Sources: src/markdown/resolver.ts:56-75

Components and Data Structures

Key Functions

Function	Location	Description
resolveUrl	resolver.ts:24	Main entry point that routes to specific handlers based on URL and extension.
resolveJsModule	resolver.ts:79	Handles .js and .mjs files using import() in a child process.
resolveHttp	resolver.ts:56	Performs synchronous HTTP requests via Node.js CLI execution.
normalizeData	resolver.ts:158	Ensures the resolved object is valid and contains a required type field.

The ResolveResult Type

The resolver returns a discriminated union to the markdown renderer, ensuring type safety and clear error reporting.

export type ResolveResult =
  | { type: 'data'; data: any }
  | { type: 'error'; error: string };

Sources: src/markdown/resolver.ts:9-12, src/markdown/resolver.ts:158-168

Implementation Details in the Pipeline

The resolution process is integrated into the ChartjsMarkdown plugin. It follows a strict "Data-First" architecture where the build-time environment handles all I/O.

This flow ensures that the Vue component (VpChart) used in the final site only receives a plain JSON object through the data prop, avoiding any client-side complexity or network requests for configuration.
Sources: src/markdown/index.ts:213-228, src/markdown/index.ts:265-285

Conclusion

The Build-Time Data Resolver is essential for maintaining the performance and reliability of vitepress-plugin-chartjs. By centralizing data fetching and parsing in the build phase, it enables advanced features like dynamic JS-generated charts and remote data integration while keeping the client-side footprint minimal and predictable.
Sources: README.md:120-128, example/api.md:180-188