@valantify/plugin

Vite plugin for serving Valantify assets with on-demand video frame extraction.

Installation

npm install @valantify/plugin

Requirement: FFmpeg must be installed on your system for frame extraction.

Usage

// vite.config.ts
import { defineConfig } from 'vite'
import { valantifyPlugin } from '@valantify/plugin'

export default defineConfig({
  plugins: [valantifyPlugin()]
})

What It Does

Asset Discovery

The plugin automatically finds your valantify/ folder by checking common locations:

1. valantify/
2. public/valantify/
3. assets/valantify/
4. src/assets/valantify/
5. static/valantify/

If not found, it searches up to 5 levels deep.

Dev Server

• Serves valantify assets at /valantify/*
• Extracts video frames on-demand with intelligent precomputation
• Pre-computes transition frames when perspective images are loaded
• Sets proper MIME types for images, videos, and JSON

Build

• Injects import.meta.env.VITE_VALANTIFY_PATH with the correct public path
• Injects import.meta.env.VITE_VALANTIFY_PRODUCTS with product/variation metadata from disk
• Injects import.meta.env.VITE_VALANTIFY_TRANSITIONS with available transitions
• Pre-generates all video frames for production

Frame Extraction

The plugin extracts frames from transition videos on-demand during development and pre-generates them during build. Supports two resolution tiers for progressive loading.

URL Pattern

/valantify/<group>/<variation>/transitions/frames/<direction>/<frame>.webp         # low-res (160px)
/valantify/<group>/<variation>/transitions/frames/<direction>/<frame>-medium.webp  # medium-res (360px)
/valantify/<group>/<variation>/transitions/frames/<direction>/<frame>-high.webp    # high-res (720px)

Resolution Tiers

| Tier | Suffix | Max Dimension | Use Case | |------|--------|---------------|----------| | Low | 50.webp | 160px | Rapid scrubbing only (very fast movement) | | Medium | 50-medium.webp | 360px | Normal scrubbing (default during drag) | | High | 50-high.webp | 720px | When user slows or stops (after a brief pause) |

Example

Rapid scrubbing (very fast movement):

GET /valantify/shoe/red/transitions/frames/front-to-left/50.webp
→ 160px WebP (~2-5KB)

Normal scrubbing:

GET /valantify/shoe/red/transitions/frames/front-to-left/50-medium.webp
→ 360px WebP (~5-10KB)

User pauses:

GET /valantify/shoe/red/transitions/frames/front-to-left/50-high.webp
→ 720px WebP (~15-30KB)

How It Works

Development:

• Intercepts frame requests
• Extracts the frame from the video using FFmpeg at requested resolution
• Caches in memory (LRU, max 100MB or 2000 frames)
• Returns WebP image with aggressive caching headers

Precomputation (Dev):

When a perspective image is fetched (e.g., /valantify/shoe/red/front.png), the plugin automatically pre-computes frames for all related transitions in the background:

1. Detects which transitions involve that perspective (e.g., front-to-side, side-to-front)
2. Extracts all 101 frames (0-100) at both medium and high resolution
3. Prioritizes endpoints (0, 100), then every 10th frame, then remaining
4. Runs with concurrency limit (3) to avoid overwhelming the system

This ensures frames are cached before the user interacts with the camera navigator, resulting in smooth scrubbing without extraction lag.

Production Build:

• Scans for all transitions/*.mp4 files
• Generates 101 frames (0-100) per video at all three resolutions
• Outputs to build directory:

dist/
└── valantify/
    └── shoe/
        └── red/
            └── transitions/
                ├── front-to-side.mp4          # Original video (copied)
                └── frames/
                    └── front-to-side/
                        ├── 0.webp             # Low-res frames
                        ├── 0-medium.webp      # Medium-res frames
                        ├── 0-high.webp        # High-res frames
                        ├── 1.webp
                        ├── 1-medium.webp
                        ├── 1-high.webp
                        ├── ...
                        ├── 100.webp
                        ├── 100-medium.webp
                        └── 100-high.webp

Configuration

valantifyPlugin({
  // Explicit path to valantify folder (skips auto-detection)
  path: './my-assets/valantify',

  // Maximum search depth for auto-detection (default: 5)
  maxSearchDepth: 3,

  // Pre-compute transition frames when perspective images are fetched (default: true)
  // Set to false to disable background precomputation
  precomputeOnFetch: true,

  // Enable debug logging for transition frame generation (default: false)
  debugTransitions: true,
})

Expected Folder Structure

public/
└── valantify/
    └── shoe/                   # Product group
        ├── product.json        # Product metadata (title, description, perspectives)
        ├── red/                # Variation
        │   ├── variant.json    # Variant metadata (features, description)
        │   ├── front.png
        │   ├── side.png
        │   └── transitions/    # Video transitions
        │       ├── front-to-side.mp4
        │       └── side-to-front.mp4
        └── blue/
            ├── variant.json
            └── ...

Environment Variables

VITE_VALANTIFY_PATH

The public URL path to the valantify folder:

const basePath = import.meta.env.VITE_VALANTIFY_PATH
// → "/valantify" (or custom path)

Used by @valantify/runtime to load assets.

VITE_VALANTIFY_PRODUCTS

Product metadata read from product.json and variant.json files:

const products = import.meta.env.VITE_VALANTIFY_PRODUCTS
// → {
//     "shoe": {
//       "title": "Shoe",
//       "description": "A running shoe with...",
//       "perspectives": ["front", "side", "back"],
//       "variations": [
//         { "folder": "./shoe/red/", "features": { "color": "red" }, "description": "Red variant" },
//         { "folder": "./shoe/blue/", "features": { "color": "blue" }, "description": "Blue variant" }
//       ]
//     }
//   }

Used by @valantify/runtime and generated templates to resolve variation metadata for step-option rendering and cascade logic.

VITE_VALANTIFY_TRANSITIONS

Available transition videos, used by the runtime to check availability without network requests:

const transitions = import.meta.env.VITE_VALANTIFY_TRANSITIONS
// → { "shoe": { "red": ["front-to-side", "side-to-back"] } }

Integration

This plugin works with:

• @valantify/runtime - Client-side runtime for displaying variations
• valantify CLI - Generates the assets this plugin serves

TypeScript

import { valantifyPlugin, ValantifyPluginOptions } from '@valantify/plugin'

// Detection utilities
import { findValantifyFolder, calculatePublicPath } from '@valantify/plugin'

Exports

| Export | Description | |--------|-------------| | valantifyPlugin | Main Vite plugin function | | ValantifyPluginOptions | Plugin configuration type | | findValantifyFolder | Auto-detect valantify folder location | | calculatePublicPath | Calculate public URL path for assets | | ProductsManifest | Type for VITE_VALANTIFY_PRODUCTS value | | ProductManifest | Type for a single product entry | | ProductManifestVariation | Type for a single variation entry |