vite-git-plugin

A Vite plugin that allows you to load files from git references (branches, tags, commits) instead of the working directory.

Features

• 🔀 Load any file from a git reference by adding ?git=<ref> query parameter
• 🔄 Automatic propagation: imported modules inherit the git reference from their importers
• 🏷️ Works with branches, tags, and commit hashes
• 🧪 Fully tested with unit and integration tests

Installation

npm install vite-git-plugin

Usage

Basic Setup

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import { viteGitPlugin } from 'vite-git-plugin';

export default defineConfig({
  plugins: [viteGitPlugin()],
});

Loading Files from Git

Load any HTML file with a git reference:

http://localhost:5173/index.html?git=main
http://localhost:5173/page.html?git=v1.0.0
http://localhost:5173/app.html?git=feature/new-feature

When you load page.html?git=main, all modules it imports will automatically use the same git reference:

<!-- page.html?git=main -->
<script type="module" src="/src/index.ts"></script>
<!-- This will load src/index.ts?git=main -->

And if index.ts imports other modules:

// src/index.ts?git=main
import { helper } from './helper.ts';
// This will load src/helper.ts?git=main

Plugin Options

viteGitPlugin({
  debug: true, // Enable debug logging
})

How It Works

1. When a file is requested with a ?git=<ref> query parameter, the plugin uses git show <ref>:<path> to read the file content from that git reference
2. The plugin's resolveId hook propagates the git reference to all imported modules
3. Files are loaded from git history instead of the working directory
4. The plugin runs with enforce: 'pre' to process files before other Vite plugins

Development

# Install dependencies
npm install

# Run tests
npm test

# Run integration tests
npm run test:integration

# Build
npm run build

Requirements

• Git must be installed and available in PATH
• The project must be in a git repository

License

MIT