---
name: vitepress-data-loading
description: Build-time data loaders for fetching remote data or processing local files
---

# Data Loading

VitePress data loaders run at build time to load arbitrary data that's serialized as JSON in the client bundle.

## Basic Usage

Create a file ending with `.data.js` or `.data.ts`:

```ts
// example.data.ts
export default {
  load() {
    return {
      hello: 'world',
      timestamp: Date.now()
    }
  }
}
```

Import the `data` named export:

```vue
<script setup>
import { data } from './example.data.ts'
</script>

<template>
  <pre>{{ data }}</pre>
</template>
```

## Async Data

Fetch remote data:

```ts
// api.data.ts
export default {
  async load() {
    const response = await fetch('https://api.example.com/data')
    return response.json()
  }
}
```

## Local Files with Watch

Process local files with hot reload:

```ts
// posts.data.ts
import fs from 'node:fs'
import { parse } from 'csv-parse/sync'

export default {
  watch: ['./data/*.csv'],
  load(watchedFiles) {
    // watchedFiles = array of absolute paths
    return watchedFiles.map(file => {
      return parse(fs.readFileSync(file, 'utf-8'), {
        columns: true,
        skip_empty_lines: true
      })
    })
  }
}
```

## createContentLoader

Helper for loading markdown content (common for blogs/archives):

```ts
// posts.data.ts
import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md')
```

Returns array of `ContentData`:

```ts
interface ContentData {
  url: string                    // e.g. /posts/hello.html
  frontmatter: Record<string, any>
  src?: string                   // raw markdown (opt-in)
  html?: string                  // rendered HTML (opt-in)
  excerpt?: string               // excerpt HTML (opt-in)
}
```

With options:

```ts
// posts.data.ts
import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md', {
  includeSrc: true,     // Include raw markdown
  render: true,         // Include rendered HTML
  excerpt: true,        // Include excerpt (content before first ---)
  
  transform(rawData) {
    // Sort by date, newest first
    return rawData
      .sort((a, b) => +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date))
      .map(page => ({
        title: page.frontmatter.title,
        url: page.url,
        date: page.frontmatter.date,
        excerpt: page.excerpt
      }))
  }
})
```

## Usage Example: Blog Index

```ts
// posts.data.ts
import { createContentLoader } from 'vitepress'

export default createContentLoader('posts/*.md', {
  excerpt: true,
  transform(data) {
    return data
      .filter(post => !post.frontmatter.draft)
      .sort((a, b) => +new Date(b.frontmatter.date) - +new Date(a.frontmatter.date))
  }
})
```

```vue
<!-- posts/index.md -->
<script setup>
import { data as posts } from './posts.data.ts'
</script>

<template>
  <ul>
    <li v-for="post in posts" :key="post.url">
      <a :href="post.url">{{ post.frontmatter.title }}</a>
      <span>{{ post.frontmatter.date }}</span>
    </li>
  </ul>
</template>
```

## Typed Data Loaders

```ts
// example.data.ts
import { defineLoader } from 'vitepress'

export interface Data {
  posts: Array<{ title: string; url: string }>
}

declare const data: Data
export { data }

export default defineLoader({
  watch: ['./posts/*.md'],
  async load(): Promise<Data> {
    // ...
    return { posts: [] }
  }
})
```

## In Build Hooks

Use in config for generating additional files:

```ts
// .vitepress/config.ts
import { createContentLoader } from 'vitepress'

export default {
  async buildEnd() {
    const posts = await createContentLoader('posts/*.md').load()
    // Generate RSS feed, sitemap, etc.
  }
}
```

## Accessing Config

```ts
// example.data.ts
import type { SiteConfig } from 'vitepress'

export default {
  load() {
    const config: SiteConfig = (globalThis as any).VITEPRESS_CONFIG
    return { base: config.site.base }
  }
}
```

## Key Points

- Data loaders run only at build time in Node.js
- File must end with `.data.js` or `.data.ts`
- Import the `data` named export (not default)
- Use `watch` for local file hot reload during dev
- `createContentLoader` simplifies loading markdown collections
- Keep data small - it's inlined in the client bundle
- Heavy data should use `transform` to reduce payload

<!--
Source references:
- https://vitepress.dev/guide/data-loading
-->