Theme Setup & Plugin Registration

Relevant source files

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

• example/plugins/setup.md
• example/api.md
• README.md
• src/index.ts
• src/chartjs-plugin.ts
• example/index.md

The Theme Setup & Plugin Registration process is the foundational step for enabling Chart.js functionality within a VitePress project. It involves two primary stages: the build-time configuration via VitePress and the client-side enhancement of the theme to support interactive charts and external Chart.js plugins. Sources: src/index.ts:25-48, README.md:54-72

By default, the core plugin only includes Chart.js itself. To utilize extended features such as zooming, data labels, or advanced chart types (e.g., treemaps or geographic maps), developers must register these components within the VitePress theme's enhanceApp hook. This architecture ensures a lean bundle size by allowing users to control exactly which dependencies are included. Sources: example/plugins/setup.md:3-10, example/api.md:120-131

Core Plugin Integration

The integration starts by wrapping the VitePress configuration with the withChartjs function. This utility modifies the Markdown parser to recognize chart blocks and pushes a custom Vite plugin to handle the registration of the <VpChart /> component. Sources: src/index.ts:25-36, src/chartjs-plugin.ts:16-25

chart blocks]
VP --> Reg[Register VpChart Component]
Parse --> Tag[Generate VpChart Tag]

The diagram above illustrates how the `withChartjs` wrapper distributes functionality between the Markdown parser and the Vite build system. Sources: [src/index.ts:25-42](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/src/index.ts#L25-L42), [src/chartjs-plugin.ts:14-30](https://github.com/s00d/vitepress-plugin-chartjs/blob/HEAD/src/chartjs-plugin.ts#L14-L30)

### VitePress Config Setup
In `.vitepress/config.mts`, the `withChartjs` function is used to decorate the standard `defineConfig` object.

```typescript
import { defineConfig } from 'vitepress'
import { withChartjs } from 'vitepress-plugin-chartjs'

export default withChartjs(defineConfig({
  chartjs: {
    defaultHeight: '400px',
    enableZoom: false // Global options
  }
}))

Sources: example/api.md:14-25, README.md:54-72

Theme Enhancement

To render charts correctly, the plugin's CSS must be imported, and Chart.js must be registered within the theme. This must be done in .vitepress/theme/index.ts. Sources: example/api.md:27-32, example/plugins/setup.md:14-16

Required Styles

A critical step in the setup is importing the plugin styles. Without this import, the chart containers will not scale or render correctly.

import 'vitepress-plugin-chartjs/style.css'

Sources: example/api.md:34-36, example/plugins/setup.md:18-20

Client-Side Registration

Because Chart.js requires access to the browser's Document Object Model (DOM), all registrations must be wrapped in a check for the window object to ensure SSR (Server-Side Rendering) compatibility. Sources: example/api.md:41-43, example/plugins/setup.md:22-24

The sequence above shows the dynamic loading of Chart.js and its plugins only when the code is running in a browser environment. Sources: example/api.md:41-52, example/plugins/setup.md:5-13

Advanced Plugin Registration

The architecture is plugin-agnostic, meaning any third-party Chart.js plugin can be added. Registration involves importing the plugin and calling Chart.register(). Sources: example/plugins/setup.md:26-30, README.md:23-25

Common Plugins and Extensions

The following table lists popular plugins and their respective registration requirements.

Category	Package	Controllers/Elements to Register
Interactivity	chartjs-plugin-zoom	zoomPlugin
Labels	chartjs-plugin-datalabels	datalabelsPlugin
Statistical	@sgratzl/chartjs-chart-boxplot	BoxPlotController, BoxAndWiskers, ViolinController, Violin
Geographic	chartjs-chart-geo	ChoroplethController, GeoFeature, ProjectionScale
Hierarchy	chartjs-chart-treemap	TreemapController, TreemapElement

Sources: example/plugins/setup.md:35-85, example/api.md:120-131

Comprehensive Setup Example

For a project requiring multiple features, the enhanceApp hook should look like this:

import DefaultTheme from 'vitepress/theme'
import 'vitepress-plugin-chartjs/style.css'

export default {
  extends: DefaultTheme,
  async enhanceApp({ app }) {
    if (typeof window !== 'undefined') {
      const { Chart } = await import('chart.js')
      
      // Register Zoom
      const zoom = (await import('chartjs-plugin-zoom')).default
      Chart.register(zoom)

      // Register Matrix/Heatmap
      const matrix = await import('chartjs-chart-matrix')
      Chart.register(matrix.MatrixController, matrix.MatrixElement)
    }
  }
}

Sources: example/plugins/setup.md:30-74, example/api.md:41-52

Plugin Configuration Options

Configuration can be passed globally through the VitePress config file via the chartjs property. Sources: src/index.ts:40, example/api.md:54-55

Option	Type	Description
defaultHeight	string	Sets the default height for all charts (e.g., '400px').
colorPalette	string[]	Customizes the default color array for datasets.
enableZoom	boolean	Enables the zoom plugin globally if registered in the theme.
enableDatalabels	boolean	Enables the datalabels plugin globally if registered.
root	string	Sets the base directory for resolving external chart files.

Sources: example/api.md:57-67, README.md:175-183

Summary

Setting up vitepress-plugin-chartjs requires a two-fold approach: enabling the build-time infrastructure via withChartjs and performing client-side registration in the theme's enhanceApp. This design allows for a modular system where developers only pay the performance cost for the specific Chart.js features and plugins they actually use. Sources: README.md:195-202, example/plugins/setup.md:3-8