vite-plugin-arraybuffer

0.1.4 verified Mon Apr 27 auth: no javascript

A Vite plugin that enables importing binary files (images, videos, audio, etc.) as ArrayBuffer or Uint8Array directly in your JavaScript/TypeScript code. Version 0.1.4 is the latest stable release, with no scheduled release cadence. Unlike typical asset imports that return URLs or base64 strings, this plugin gives raw binary access, making it ideal for WebSocket streams, WebAssembly preprocessing, or custom binary formats. It is specifically designed for Vite's build system and does not work with other bundlers.

Common errors

error Error: 'vite-plugin-arraybuffer' resolution failed: module not found ↓

cause The package is not installed or the import path is incorrect.

fix

Run 'npm install vite-plugin-arraybuffer' and ensure the import is from 'vite-plugin-arraybuffer' (not './vite-plugin-arraybuffer').

error TypeError: Cannot read properties of undefined (reading 'arraybuffer') ↓

cause Importing a file without the query parameter and trying to use it as an ArrayBuffer.

fix

Append '?arraybuffer' to the import path, e.g., import data from './file.bin?arraybuffer'.

error SyntaxError: Cannot use import statement outside a module ↓

cause Using import syntax in a CommonJS file or without proper Vite setup.

fix

Ensure your file is an ES module (use type: 'module' in package.json or .mjs extension) and run via Vite.

error Uncaught (in promise) RangeError: Array buffer allocation failed ↓

cause Importing a file that is too large to fit in memory as a single ArrayBuffer.

fix

Use streaming or chunked loading for large files. Consider using the Web Streams API instead of direct import.

Warnings

gotcha The plugin only transforms imports with explicit query parameters (?arraybuffer or ?uint8array). Without the query, the file will be treated as a regular asset import (URL string). ↓

fix Always append ?arraybuffer or ?uint8array to import paths to get binary data.

gotcha The plugin does not support CommonJS (require) imports. It relies on Vite's ESM transform pipeline. ↓

fix Convert require statements to import statements, or use Vite's CJS compatibility mode.

breaking In versions prior to 0.1.0, the default behavior was to return ArrayBuffer without a query parameter. This changed in 0.1.0 to require explicit query. ↓

fix Update imports to include ?arraybuffer or ?uint8array query parameter.

deprecated The option 'outputType' in the plugin configuration is deprecated and will be removed in future versions. ↓

fix Use query parameters on imports instead; they override the config-based output type.

gotcha Large binary files may cause memory issues when imported directly as ArrayBuffer. The plugin loads the entire file into memory. ↓

fix For large files, consider using fetch() with streaming or a WebWorker to avoid blocking the main thread.

Install

npm install vite-plugin-arraybuffer

yarn add vite-plugin-arraybuffer

pnpm add vite-plugin-arraybuffer

Imports

default

wrong

const vitePluginArraybuffer = require('vite-plugin-arraybuffer')

correct

import vitePluginArraybuffer from 'vite-plugin-arraybuffer'

ESM-only; CJS require does not work.

default (type import)
```
import type { UserConfig } from 'vite';
```
The plugin doesn't export types; use Vite's UserConfig type.

(re-export in vite.config.ts)

wrong

import vitePluginArraybuffer from 'vite-plugin-arraybuffer/src/index'

correct

import { defineConfig } from 'vite';
import vitePluginArraybuffer from 'vite-plugin-arraybuffer';
export default defineConfig({ plugins: [vitePluginArraybuffer()] });

Import from root package; avoid deep imports.

Quickstart

Configures Vite to import .bin files as ArrayBuffer and .dat files as ArrayBuffer (default) or Uint8Array using query parameters.

// vite.config.js
import { defineConfig } from 'vite';
import vitePluginArraybuffer from 'vite-plugin-arraybuffer';

export default defineConfig({
  plugins: [
    vitePluginArraybuffer({
      // Optional: include specific file extensions
      include: ['**/*.bin', '**/*.dat'],
      // Optional: exclude certain directories
      exclude: ['node_modules/**'],
    }),
  ],
});

// In your component/script
import myBuffer from './example.bin?arraybuffer';  // returns ArrayBuffer
import { default as myUint8 } from './example.bin?uint8array';  // returns Uint8Array

console.log(myBuffer.byteLength);
console.log(myUint8.length);