gt-agent-company/.agents/skills/vite/references/features-assets.md

name, description

name	description
features-assets	Static asset handling in Vite including imports, public directory, and URL handling

Static Asset Handling

Importing Assets as URL

import imgUrl from './img.png'
document.getElementById('hero-img').src = imgUrl
// Dev: /src/img.png
// Build: /assets/img.2d8efhg.png

Common image, media, and font types are detected automatically.

Import Queries

Explicit URL Import

import workletURL from './worklet.js?url'
CSS.paintWorklet.addModule(workletURL)

Import as String (Raw)

import shaderString from './shader.glsl?raw'

Control Inlining

import imgUrl1 from './img.svg?no-inline'  // Never inline
import imgUrl2 from './img.png?inline'      // Always inline as base64

Asset Inlining

Assets smaller than assetsInlineLimit (default 4KB) are inlined as base64:

export default defineConfig({
  build: {
    assetsInlineLimit: 4096,  // 4KB
    // Or use callback for fine control
    assetsInlineLimit: (filePath) => {
      return !filePath.endsWith('.svg')
    }
  }
})

The public Directory

Files in public/ are:

• Served at root path / during dev
• Copied as-is to dist/ root during build
• Not processed or hashed

public/
  favicon.ico  → /favicon.ico
  robots.txt   → /robots.txt

Reference with absolute paths in source:

<img src="/icon.png" />

Configure directory:

export default defineConfig({
  publicDir: 'static'  // or false to disable
})

Extending Asset Types

export default defineConfig({
  assetsInclude: ['**/*.gltf', '**/*.hdr']
})

Dynamic URLs with import.meta.url

// Works natively in modern browsers
const imgUrl = new URL('./img.png', import.meta.url).href

// Dynamic pattern (limited)
function getImageUrl(name) {
  return new URL(`./dir/${name}.png`, import.meta.url).href
}

Limitations:

• URL string must be static for build analysis
• Does not work with SSR (different semantics in Node.js vs browser)

TypeScript Support

Add vite/client to types for asset import recognition:

{
  "compilerOptions": {
    "types": ["vite/client"]
  }
}

URL Handling in CSS

.hero {
  background: url('./img.png');  /* Processed and rebased */
}

For dynamically constructed SVG URLs:

import imgUrl from './img.svg'
element.style.background = `url("${imgUrl}")`  // Note double quotes