@molecule/app-file-upload-filepond

FilePond file upload provider for the molecule file upload interface.

Implements FileUploadProvider from @molecule/app-file-upload using a headless upload engine with validation, progress tracking, concurrency control, and image preview generation following FilePond's patterns.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { provider } from '@molecule/app-file-upload-filepond'
import { setProvider } from '@molecule/app-file-upload'

setProvider(provider)

Type

provider

Installation

npm install @molecule/app-file-upload-filepond @molecule/app-file-upload @molecule/app-i18n

API

Interfaces

`FilepondConfig`

Configuration options for the FilePond file upload provider.

interface FilepondConfig {
  /**
   * Timeout in milliseconds for individual upload requests.
   * Set to `0` for no timeout. Defaults to `0`.
   */
  timeout?: number
}

Functions

`createFilepondProvider(config)`

Creates a FilePond-style file upload provider.

function createFilepondProvider(config?: FilepondConfig): FileUploadProvider

config — Optional FilePond-specific configuration.

Returns: A FileUploadProvider backed by FilePond-style processing.

Constants

`provider`

Default FilePond file upload provider instance.

const provider: FileUploadProvider

Core Interface

Implements @molecule/app-file-upload interface.

Bond Wiring

Setup function to register this provider with the core interface:

import { setProvider } from '@molecule/app-file-upload'
import { provider } from '@molecule/app-file-upload-filepond'

export function setupFileUploadFilepond(): void {
  setProvider(provider)
}

Injection Notes

Requirements

Peer dependencies:

@molecule/app-file-upload >=1.0.1
@molecule/app-i18n >=1.0.1

Runtime Dependencies

@molecule/app-file-upload
@molecule/app-i18n

Transport is ONE multipart/form-data request per file to destination.url (default method POST, default field name 'file', additionalData appended as extra fields); the response is parsed as JSON when possible (else raw text) and can be reshaped with destination.parseResponse. This is NOT FilePond's process/revert server protocol — any endpoint accepting a multipart POST works. Files that fail validation are reported via events.onValidationError and NEVER enter the queue (they won't appear in getFiles()). timeout defaults to 0 (no timeout). Every error/validation message routes through t() under the fileUpload.error.* namespace with an English defaultValue, so English works out of the box. There is no dedicated companion locale bond yet — to translate these, register fileUpload.error.* keys with your i18n provider (e.g. addTranslations('fr', { 'fileUpload.error.timedOut': '…' })). Interpolated messages expose {{maxSize}}, {{minSize}}, {{type}}, {{extension}}, {{maxFiles}}, and {{status}}.

E2E Tests

Integration checklist — drive the real UI (live preview, no mocks), adapt each item to this app's actual screens/flows, and check every box off one by one. A box you can't check is an integration bug to fix — not a skip:

Picking a valid file via the picker starts the upload and shows per-file progress through to a completed state.
Dragging and dropping a file onto the drop zone uploads it the same way.
The completed upload appears wherever this app uses it (file list, avatar, attachment) — completion is not just a toast.
A file that fails validation (too large, wrong type) is rejected with a visible message and is never sent to the server.
With multiple files (if enabled), each file's progress and completion track independently and all complete.
Canceling/removing a queued or in-flight file stops it and clears it from the queue.

`@molecule/app-file-upload-filepond`

How it works

Live demos

Reference