Filestack-js is the official JavaScript SDK for integrating Filestack's comprehensive file management services into web and Node.js applications. It provides functionalities for secure content ingestion from various sources (local, URL, social media, cloud storage), powerful real-time transformations (image, video, document), and optimized delivery via a global CDN. Currently at version 3.48.4, the library receives regular updates to ensure compatibility with modern web frameworks and browsers, as well as to introduce new features like folder uploads and a mini uploader. Key differentiators include its highly customizable UI picker, built-in image editor, security features like virus scanning and content moderation, and simplified APIs for complex file workflows, aiming to streamline file handling from upload to delivery.
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ES Module import is standard for modern browsers and Node.js projects. CommonJS `require` is supported for Node environments.
import * as filestack from 'filestack-js';
The primary interaction is via the `init` factory function, which returns a client instance.
const client = filestack.init('YOUR_API_KEY');
For TypeScript users, import the `PickerOptions` interface for type-safe configuration of the file picker.
import type { PickerOptions } from 'filestack-js';
This quickstart initializes the Filestack client with an API key and opens a file picker, configured to accept images and PDFs, allowing up to 5 files, and logging the URLs of uploaded files upon completion. It also enables basic image transformations (crop, rotate).
import * as filestack from 'filestack-js';
const API_KEY = process.env.FILESTACK_API_KEY ?? 'YOUR_FILESTACK_API_KEY';
// Ensure a valid API key is set
if (API_KEY === 'YOUR_FILESTACK_API_KEY' || !API_KEY) {
console.error('Please replace YOUR_FILESTACK_API_KEY with your actual Filestack API key.');
console.error('You can get one from https://www.filestack.com/signup-start/');
// Exit or throw error in a real application
}
const client = filestack.init(API_KEY);
const pickerOptions: filestack.PickerOptions = {
maxFiles: 5,
accept: ['image/*', 'application/pdf'],
onUploadDone: (res) => {
console.log('Upload successful:', res.filesUploaded);
if (res.filesUploaded.length > 0) {
console.log('First file URL:', res.filesUploaded[0].url);
console.log('First file handle:', res.filesUploaded[0].handle);
}
},
onOpen: () => console.log('Picker opened.'),
onClose: () => console.log('Picker closed.'),
onError: (error) => console.error('Picker error:', error),
uploadInBackground: false,
transformations: {
crop: true,
rotate: true
}
};
async function openFilePicker() {
try {
const picker = client.picker(pickerOptions);
await picker.open();
console.log('File picker process initiated.');
} catch (error) {
console.error('Failed to open file picker:', error);
}
}
// In a browser environment, you might attach this to a button click:
// document.getElementById('uploadButton')?.addEventListener('click', openFilePicker);
// For demonstration, immediately open the picker if in a browser-like environment (e.g., CodeSandbox)
if (typeof window !== 'undefined') {
openFilePicker();
} else {
console.log('Running in Node.js environment. Picker UI cannot be displayed directly.');
}
Upgrade
Version history
Breaking-change detection hasn't run for this library yet.
Audit
Security & dependencies
CVE tracking and dependency tree are planned for a later release.