vite-plugin-dvc

Vite plugin that reads DVC .dvc files at build time and exposes a virtual:dvc-data module mapping tracked file paths to their resolved URLs.

• Dev mode (vite serve): returns local relative paths (e.g. /data.geojson)
• Build mode (vite build): returns S3 HTTPS URLs pointing at the DVC cache

Install

This package isn't published to npm yet. Install from the GitHub dist branch:

pnpm add runsascoded/vite-plugin-dvc#dist

Or pin a specific commit:

pnpm add "github:runsascoded/vite-plugin-dvc#<sha>"

pnpm-dep-source (pds) can manage switching between local, GitHub, and npm sources:

pds init ../../path/to/vite-plugin-dvc  # register as a pds-managed dep
pds gh vite-plugin-dvc                  # point at latest dist branch build
pds local vite-plugin-dvc              # switch to local build for development

Usage

// vite.config.ts
import dvc from 'vite-plugin-dvc'

export default defineConfig({
  plugins: [dvc({ root: 'public' })],
})

// app code
import { resolve } from 'virtual:dvc-data'

fetch(resolve('my-data.geojson'))

TypeScript

Add a reference to vite-plugin-dvc/client in your env.d.ts (or any .d.ts file included by your tsconfig.json):

/// <reference types="vite-plugin-dvc/client" />

This provides type declarations for the virtual:dvc-data module.

Options

interface DvcPluginOptions {
  /** Path to .dvc/ directory (default: auto-detect walking up from vite root) */
  dvcDir?: string
  /** Glob pattern for .dvc files (default: '**\/*.dvc') */
  glob?: string
  /** Search root for .dvc files, relative to vite root (default: '.') */
  root?: string
  /** Remote name (default: default from .dvc/config) */
  remote?: string
  /** Override base URL (e.g. CloudFront domain) */
  baseUrl?: string
  /** Dev mode behavior: 'local' returns relative paths, 's3' returns S3 URLs (default: 'local'). Overridden by VITE_PLUGIN_DVC_DEV env var. */
  dev?: 'local' | 's3'
}

Environment variables

Variable	Values	Description
VITE_PLUGIN_DVC_DEV	local, s3	Overrides the dev plugin option. Useful for testing S3 URLs during development without changing vite.config.ts.

Virtual module API

The virtual:dvc-data module exports:

• urls: Record<string, string> — map of file path to resolved URL
• resolve(path: string): string — look up a path in the URL map; returns the input path unchanged if not found

How it works

1. The plugin walks up from the Vite root to find a .dvc/ directory
2. Reads .dvc/config to get the S3 remote URL
3. Globs for *.dvc files, parses their YAML to extract md5 hashes and file paths
4. In dev mode (default), maps each file to a local relative path (/filename.ext)
5. In build mode, maps each file to its S3 DVC cache URL (https://{bucket}.s3.amazonaws.com/.../files/md5/{xx}/{rest})