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.
filestack
✓ import * as filestack from 'filestack-js';
✗ const filestack = require('filestack-js');
ES Module import is standard for modern browsers and Node.js projects. CommonJS `require` is supported for Node environments.
Client
✓ const client = filestack.init('YOUR_API_KEY');
✗ const client = new filestack.Client('YOUR_API_KEY');
The primary interaction is via the `init` factory function, which returns a client instance.
PickerOptions
✓ import type { PickerOptions } from 'filestack-js';
For TypeScript users, import the `PickerOptions` interface for type-safe configuration of the file picker.
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.');
}
Debug
Known issues
breakingThe Filestack Filepicker has evolved, with version 4.0 introducing significant enhancements like folder uploads and a mini uploader. While filestack-js is at v3.x, ensure your picker integration script links to the correct major version (e.g., `filestack-js/4.x.x/filestack.min.js` if using CDN, or update the npm package if using framework-specific SDKs like `filestack-react`). This may involve updating configuration options and UI integration patterns to leverage new features and avoid deprecated behavior.fixReview the Filestack documentation for Filepicker 4.0 migration and update your script tags or npm package versions accordingly. Adapt your picker options and callbacks for any renamed or changed properties.
affects: >=3.x for picker 4.0 integration
gotchaThe `client.upload` method behaves differently in Node.js versus browser environments. In Node.js, it expects a file path, whereas in browsers, it anticipates a Blob object (e.g., from an `<input type='file'>` or drag-and-drop).fixEnsure your file input argument matches the runtime environment: a string file path for Node.js or a Blob/File object for browsers.
affects: >=3.0.0
gotchaWhen using `filestack-js` via a CDN in browser environments, it's crucial to implement Subresource Integrity (SRI) to protect against unexpected manipulation of the loaded library. Without SRI, a compromised CDN could serve malicious code.fixConsult the Filestack CDN documentation to obtain the cryptographic hash for the specific library version and add the `integrity` attribute to your `<script>` tag.
affects: >=3.0.0 (CDN usage)
gotchaFile uploads can fail due to various client-side issues, including incorrect filenames (e.g., special characters, spaces), incompatible file extensions not allowed by server configurations, or timeout issues during large file transfers over unstable networks.fixImplement robust client-side validation for file types and sizes using picker options (`accept`, `maxSize`). Educate users on valid filenames. For large files, ensure `uploadConfig.timeout` is sufficient and consider `uploadInBackground` for resilience.
affects: All versions
Errors
Common errors & fixes
{"error":"application is blocked"}
This error typically indicates an issue with your Filestack account, most commonly an unpaid invoice.
fixLog into your Filestack developer portal, check your billing status, and ensure all invoices are paid. Update any expired payment methods.
TypeError: Picker is not a constructor (or similar 'Uncaught (in promise) Error: Filestack Picker Initialize Error')
This can occur if the Filestack picker attempts to mount into a DOM element that doesn't exist yet, especially with conditional rendering in frameworks like React, or if the library is not properly initialized.
fixEnsure the DOM container for the picker is fully rendered before calling `client.picker().open()` or before the `PickerOverlay`/`PickerInline` component is mounted. If using a framework, ensure the component lifecycle correctly handles element availability.
Content Security Policy (CSP) errors related to Filestack domains
Your application's Content Security Policy is blocking scripts, styles, images, or network requests from Filestack's domains (e.g., `filestackapi.com`, `static.filestackapi.com`).
fixUpdate your CSP headers to explicitly allow `*.filestackapi.com` for `script-src`, `style-src`, `img-src`, `connect-src`, and `frame-src` directives, or other specific Filestack domains as needed by your integration. Consult Filestack documentation for required domains.
Filestack SDK not working with ad blockers / trackers
Ad blockers or browser extensions designed to block trackers can interfere with the loading or functionality of Filestack's scripts, especially during initial signup or picker operations.
fixAdvise users to temporarily disable ad blockers or try using a different browser or incognito/private mode to isolate the issue. Ensure your website doesn't have other blocking mechanisms.
Audit
Dependencies
No dependency data recorded yet.