esbuild-plugin-object-store-asset

0.0.4 verified Fri May 01 auth: no javascript

An esbuild plugin (v0.0.4) that uploads assets to S3/R2/object storage during builds and rewrites asset URLs to content-hashed CDN paths. Designed for Cloudflare R2 and AWS S3, it integrates into esbuild's output pipeline to automatically manage remote asset hosting. Peer dependency on esbuild ^0.27.3. Ships TypeScript types. Differentiators: lightweight, focuses on object storage backends, supports content-hashed URLs for caching. Release cadence: early development, infrequent updates.

Common errors

error Error: Cannot find module 'esbuild-plugin-object-store-asset' ↓

cause Package not installed or missing from node_modules.

fix

Run npm install esbuild-plugin-object-store-asset --save-dev

error TypeError: plugin is not a function ↓

cause Incorrect import style: used named import instead of default.

fix

Use default import: import plugin from 'esbuild-plugin-object-store-asset'

error Error: esbuild version must be >=0.27.3 ↓

cause Installed esbuild version is too old.

fix

Upgrade esbuild to ^0.27.3: npm install esbuild@^0.27.3 --save-dev

Warnings

breaking Requires esbuild ^0.27.3. Older versions of esbuild may be incompatible. ↓

fix Upgrade esbuild to ^0.27.3.

gotcha Plugin is early stage (v0.0.4). API may change without major version bump. ↓

fix Pin to exact version and test upgrades carefully.

gotcha Sensitive credentials (AWS keys) must be provided via environment variables or secure config. Hard-coding in plugin options is insecure. ↓

fix Use environment variables or a secrets manager. Avoid hard-coding accessKeyId/secretAccessKey in source code.

Install

npm install esbuild-plugin-object-store-asset

yarn add esbuild-plugin-object-store-asset

pnpm add esbuild-plugin-object-store-asset

Imports

default

wrong

import { plugin } from 'esbuild-plugin-object-store-asset'

correct

import plugin from 'esbuild-plugin-object-store-asset'

Package exports a default function.

PluginOptions

wrong

import { PluginOptions } from 'esbuild-plugin-object-store-asset'

correct

import type { PluginOptions } from 'esbuild-plugin-object-store-asset'

PluginOptions is a TypeScript type; use 'import type' for isolated type imports.

require

wrong

const { default: plugin } = require('esbuild-plugin-object-store-asset')

correct

const plugin = require('esbuild-plugin-object-store-asset')

CJS users can directly require the module; it exports the function as module.exports.

Quickstart

Shows basic setup integrating the plugin with esbuild build, uploading PNG/JPG/GIF/SVG assets to S3 and rewriting URLs to CDN.

import esbuild from 'esbuild';
import assetPlugin from 'esbuild-plugin-object-store-asset';

await esbuild.build({
  entryPoints: ['src/index.js'],
  bundle: true,
  outdir: 'dist',
  plugins: [
    assetPlugin({
      bucket: process.env.S3_BUCKET ?? 'my-bucket',
      region: process.env.S3_REGION ?? 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? '',
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? '',
      endpoint: process.env.R2_ENDPOINT ?? '', // for R2
      publicUrl: process.env.CDN_URL ?? 'https://cdn.example.com',
      outputDir: 'assets', // inside S3 bucket
      hashLength: 8,
      filter: /.*\.(png|jpg|gif|svg)$/,
    }),
  ],
});