https://github.com/ejirocodes/vite-plugin-asset-manager
Static asset management plugin for Vite projects
https://github.com/ejirocodes/vite-plugin-asset-manager
static-assets vite vite-plugin vitejs
Last synced: 4 months ago
JSON representation
Static asset management plugin for Vite projects
- Host: GitHub
- URL: https://github.com/ejirocodes/vite-plugin-asset-manager
- Owner: ejirocodes
- License: mit
- Created: 2026-01-27T10:04:38.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-02-10T20:56:17.000Z (4 months ago)
- Last Synced: 2026-02-10T23:48:13.814Z (4 months ago)
- Topics: static-assets, vite, vite-plugin, vitejs
- Language: TypeScript
- Homepage: https://npm.im/vite-plugin-asset-manager
- Size: 16.8 MB
- Stars: 10
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
vite-plugin-asset-manager
Stop grepping for image paths.
See exactly where every asset is used, find duplicates, and clean up what's unused.
Installation •
Usage •
Features •
Configuration •
Shortcuts
---
## Installation
```bash
npm install vite-plugin-asset-manager -D
# or
pnpm add vite-plugin-asset-manager -D
# or
yarn add vite-plugin-asset-manager -D
```
## Usage
```ts
// vite.config.ts
import { defineConfig } from 'vite'
import AssetManager from 'vite-plugin-asset-manager'
export default defineConfig({
plugins: [AssetManager()],
})
```
Start your dev server and access the Asset Manager in three ways:
- Visit `/__asset_manager__/` directly in your browser
- Press **`⌥⇧A`** (Option+Shift+A) to toggle the floating panel
- Click the floating icon button injected into your app (drag to reposition)
## Features
| Feature | Description |
|---------|-------------|
| **Fully Responsive** | Mobile-first design that works seamlessly from 320px to 4K+ displays |
| **Asset Discovery** | Automatically scans and catalogs images, videos, audio, fonts, documents, and data files |
| **Real-time Updates** | File changes reflected instantly via Server-Sent Events |
| **Floating Icon** | Draggable & resizable overlay panel with keyboard shortcuts (⌥⇧A), snaps to all 4 edges |
| **Mobile Optimized** | Touch-friendly UI with 44×44px tap targets, bottom sheet preview, drawer navigation |
| **Automatic Theming** | Light/dark mode support based on system preferences |
| **Thumbnail Generation** | Sharp-powered thumbnails with dual-tier caching |
| **Import Tracking** | See which files import each asset with click-to-open-in-editor |
| **Duplicate Detection** | Content-based deduplication using MD5 hashing |
| **Advanced Filtering** | Filter by size, date modified, and file extension |
| **Bulk Operations** | Multi-select for batch download (ZIP), copy paths, or delete |
| **Keyboard Navigation** | Full keyboard support with vim-style bindings |
| **Context Menu** | Right-click for quick actions (copy, reveal in Finder, delete, etc.) |
| **Performance** | Code splitting reduces main bundle to 75 KB, lazy loading for optimal speed |
| **Accessibility** | WCAG 2.1 Level AAA compliant with reduced motion support |
## Framework Support
| Framework | Status | Notes |
|-----------|--------|-------|
| Vanilla | ✅ | Fully automatic |
| Vue | ✅ | Fully automatic |
| React | ✅ | Fully automatic |
| Preact | ✅ | Fully automatic |
| Lit | ✅ | Fully automatic |
| Svelte | ✅ | Fully automatic |
| Solid | ✅ | Fully automatic |
| Qwik | ✅ | Fully automatic |
| **Nuxt 3/4** | ✅ | [Official module](#nuxt-module) |
| **Next.js 14+** | ✅ | [Official package](#nextjs-integration) |
| **TanStack Start** | ✅ | [Manual setup required](./docs/SSR_INTEGRATION.md#tanstack-start-setup) ([playground](./playgrounds/tanstack/)) |
### Nuxt Module
For Nuxt 3/4 projects, use the official module for automatic integration:
```bash
npm install @vite-asset-manager/nuxt -D
```
```ts
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@vite-asset-manager/nuxt'],
})
```
Features:
- Automatic floating icon injection (no manual setup)
- Nuxt DevTools integration
- Supports Nuxt 3 and 4 directory structures
- Dev-only (zero production footprint)
### Next.js Integration
For Next.js 14+ projects, use the official integration package:
```bash
npm install nextjs-asset-manager -D
```
**Step 1:** Wrap your Next.js config to suppress dev server request logging:
```ts
// next.config.ts
import type { NextConfig } from "next"
import { withAssetManager } from "nextjs-asset-manager"
const nextConfig: NextConfig = {}
export default withAssetManager(nextConfig)
```
**Step 2:** Create an API catch-all route:
```ts
// app/api/asset-manager/[[...path]]/route.ts
import { createHandler } from 'nextjs-asset-manager'
const { GET, POST } = createHandler()
export { GET, POST }
```
**Step 3:** Add the client component to your root layout:
```tsx
// app/layout.tsx
import { AssetManagerScript } from 'nextjs-asset-manager'
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
{children}
)
}
```
Features:
- Dev-only (returns 404 in production)
- Automatic floating icon injection via client component
- Suppresses asset manager request logging in dev server
- Default base path: `/api/asset-manager`
- Singleton management for HMR stability
- Composable with other `withX` plugins (`withSentryConfig`, `withBundleAnalyzer`, etc.)
### Other SSR Frameworks
For SSR frameworks (Remix, SvelteKit, Solid Start), manual script injection is required. See the **[SSR Integration Guide](./docs/SSR_INTEGRATION.md)** for setup instructions.
## Configuration
```ts
assetManager({
base: '/__asset_manager__', // Dashboard URL path
include: ['src', 'public'], // Directories to scan
exclude: ['node_modules', '.git', 'dist'],
thumbnailSize: 200, // Thumbnail dimensions (px)
floatingIcon: true, // Show toggle button in host app
watch: true, // Enable real-time updates
launchEditor: 'code', // Editor: code, cursor, webstorm, vim, etc.
debug: false, // Enable debug logging for diagnostics
aliases: { '@/': 'src/' }, // Path aliases for import detection
})
```
## Asset Types
| Type | Extensions |
|------|------------|
| Image | `png` `jpg` `jpeg` `gif` `svg` `webp` `avif` `ico` `bmp` `tiff` `heic` |
| Video | `mp4` `webm` `ogg` `mov` `avi` |
| Audio | `mp3` `wav` `flac` `aac` |
| Document | `pdf` `doc` `docx` `xls` `xlsx` `ppt` `pptx` |
| Font | `woff` `woff2` `ttf` `otf` `eot` |
| Data | `json` `csv` `xml` `yml` `yaml` `toml` |
| Text | `md` `txt` |
## Keyboard Shortcuts
| Action | Shortcut |
|--------|----------|
| Navigate grid | `←` `↑` `→` `↓` or `j`/`k` |
| Focus search | `/` |
| Close preview | `Escape` |
| Toggle selection | `Space` |
| Open preview | `Enter` |
| Select all | `⌘A` / `Ctrl+A` |
| Copy paths | `⌘C` / `Ctrl+C` |
| Open in editor | `⌘O` / `Ctrl+O` |
| Reveal in Finder | `⌘⇧R` / `Ctrl+Shift+R` |
| Delete | `Delete` / `Backspace` |
## API Endpoints
The plugin exposes REST endpoints at `{base}/api/`:
View all endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/assets` | GET | List all assets |
| `/assets/grouped` | GET | Assets grouped by directory |
| `/search?q=` | GET | Search by name/path |
| `/thumbnail?path=` | GET | Get image thumbnail |
| `/file?path=` | GET | Serve original file |
| `/stats` | GET | Asset statistics |
| `/importers?path=` | GET | Files importing the asset |
| `/duplicates?hash=` | GET | Assets with matching content hash |
| `/open-in-editor` | POST | Open file in editor |
| `/reveal-in-finder` | POST | Reveal in system file explorer |
| `/bulk-download` | POST | Download as ZIP |
| `/bulk-delete` | POST | Delete multiple assets |
| `/events` | GET | SSE stream for real-time updates |
## Development
```bash
pnpm install # Install dependencies
pnpm run build:all # Build everything (packages + plugin)
pnpm run build # Build main plugin only
pnpm run dev # Watch mode
# Testing
pnpm run test # Run all tests
pnpm run test:watch # Watch mode
pnpm run test:coverage
# Playgrounds
pnpm run playground:react
pnpm run playground:vue
pnpm run playground:vanilla
pnpm run playground:preact
pnpm run playground:lit
pnpm run playground:svelte
pnpm run playground:solid
pnpm run playground:qwik
pnpm run playground:tanstack
pnpm run playground:nuxt
pnpm run playground:nextjs
```
## License
[MIT](LICENSE)