@happyvertical/smrt-assets-local

Local image processing for the s-m-r-t asset runtime. It extracts normalized image metadata and generates deterministic WebP variants with Sharp, while asset identity, storage, tenancy, and publishing policy remain owned by @happyvertical/smrt-assets.

Choose this adapter for local development, single-node deployments, and apps that need practical image handling without a media-asset-management service.

Installation

pnpm add @happyvertical/smrt-assets @happyvertical/smrt-assets-local

sharp is installed by this adapter and is not pulled into core s-m-r-t asset consumers.

Quick start

import { createAssetRuntime } from '@happyvertical/smrt-assets';
import { createLocalAssetProcessor } from '@happyvertical/smrt-assets-local';

const runtime = await createAssetRuntime({
  db: 'assets.db',
  storage: './data/assets',
  capabilityProviders: [createLocalAssetProcessor()],
});

const source = await runtime.storeSourceAsset(
  'photo.png',
  imageBytes,
  { mimeType: 'image/png', typeSlug: 'image' },
);

const processed = await runtime.processAsset(source, {
  variants: [{ variant: 'thumb' }, { variant: 'card' }],
});

console.log(processed.metadata, processed.variants);

The processor saves normalized metadata onto the source asset and creates derived assets linked back to that source.

Standard variants

| Name | Size | Fit | | --- | --- | --- | | thumb | 160×160 | cover | | card | 480×270 | cover | | preview | 960×960 | inside | | publish | 1200×630 | cover |

Override presets or output quality when creating the processor:

const processor = createLocalAssetProcessor({
  quality: 85,
  variants: {
    card: { width: 640, height: 360, fit: 'cover' },
  },
});

Unknown variant names must provide explicit width and height. Repeated requests reuse a matching derived asset when the source version and parameters have not changed.

Metadata

extractAssetImageMetadataFromBuffer() normalizes orientation before reporting dimensions and returns stable metadata for MIME type, dimensions, captured time, and GPS coordinates when available. GPS values retain enough precision for nearby-photo search.

Non-image assets are explicitly skipped so a later registered provider can handle them.

Public API

| Export | Purpose | | --- | --- | | createLocalAssetProcessor() | Create an asset capability provider | | extractAssetImageMetadataFromBuffer() | Extract normalized image metadata | | normalizeAssetImageMetadata() | Normalize raw Sharp/EXIF metadata | | LocalAssetProcessorOptions | Configure variant presets and quality |

Development

pnpm --filter @happyvertical/smrt-assets-local test
pnpm --filter @happyvertical/smrt-assets-local typecheck
pnpm --filter @happyvertical/smrt-assets-local build

See AGENTS.md for determinism, metadata, and provider-boundary requirements.