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

• 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
• The plugin's resolveId hook propagates the git reference to all imported modules
• Files are loaded from git history instead of the working directory
• 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