Filestack JavaScript SDK

Common errors

• {"error":"application is blocked"}

  cause This error typically indicates an issue with your Filestack account, most commonly an unpaid invoice.
  fix Log 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')

  cause 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.
  fix Ensure 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

  cause 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`).
  fix Update 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

  cause 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.
  fix Advise 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.

Warnings

• breaking The 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.
  Fix: Review 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.
• gotcha The `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).
  Fix: Ensure your file input argument matches the runtime environment: a string file path for Node.js or a Blob/File object for browsers.
• gotcha When 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.
  Fix: Consult the Filestack CDN documentation to obtain the cryptographic hash for the specific library version and add the `integrity` attribute to your `<script>` tag.
• gotcha File 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.
  Fix: Implement 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.

Install

• npm install filestack-js npm
• yarn add filestack-js yarn
• pnpm add filestack-js pnpm

Imports

• filestack
  wrong:

  const filestack = require('filestack-js');

  correct:

  import * as filestack from 'filestack-js';

  ES Module import is standard for modern browsers and Node.js projects. CommonJS `require` is supported for Node environments.
• Client
  wrong:

  const client = new filestack.Client('YOUR_API_KEY');

  correct:

  const client = filestack.init('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.

Quickstart

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.');
}