{"id":10891,"library":"filestack-js","title":"Filestack JavaScript SDK","description":"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.","status":"active","version":"3.48.4","language":"javascript","source_language":"en","source_url":"https://github.com/filestack/filestack-js","tags":["javascript","filestack","filepicker","upload","files","multipart","S3","transform","cropper","typescript"],"install":[{"cmd":"npm install filestack-js","lang":"bash","label":"npm"},{"cmd":"yarn add filestack-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add filestack-js","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"ES Module import is standard for modern browsers and Node.js projects. CommonJS `require` is supported for Node environments.","wrong":"const filestack = require('filestack-js');","symbol":"filestack","correct":"import * as filestack from 'filestack-js';"},{"note":"The primary interaction is via the `init` factory function, which returns a client instance.","wrong":"const client = new filestack.Client('YOUR_API_KEY');","symbol":"Client","correct":"const client = filestack.init('YOUR_API_KEY');"},{"note":"For TypeScript users, import the `PickerOptions` interface for type-safe configuration of the file picker.","symbol":"PickerOptions","correct":"import type { PickerOptions } from 'filestack-js';"}],"quickstart":{"code":"import * as filestack from 'filestack-js';\n\nconst API_KEY = process.env.FILESTACK_API_KEY ?? 'YOUR_FILESTACK_API_KEY';\n\n// Ensure a valid API key is set\nif (API_KEY === 'YOUR_FILESTACK_API_KEY' || !API_KEY) {\n  console.error('Please replace YOUR_FILESTACK_API_KEY with your actual Filestack API key.');\n  console.error('You can get one from https://www.filestack.com/signup-start/');\n  // Exit or throw error in a real application\n}\n\nconst client = filestack.init(API_KEY);\n\nconst pickerOptions: filestack.PickerOptions = {\n  maxFiles: 5,\n  accept: ['image/*', 'application/pdf'],\n  onUploadDone: (res) => {\n    console.log('Upload successful:', res.filesUploaded);\n    if (res.filesUploaded.length > 0) {\n      console.log('First file URL:', res.filesUploaded[0].url);\n      console.log('First file handle:', res.filesUploaded[0].handle);\n    }\n  },\n  onOpen: () => console.log('Picker opened.'),\n  onClose: () => console.log('Picker closed.'),\n  onError: (error) => console.error('Picker error:', error),\n  uploadInBackground: false,\n  transformations: {\n    crop: true,\n    rotate: true\n  }\n};\n\nasync function openFilePicker() {\n  try {\n    const picker = client.picker(pickerOptions);\n    await picker.open();\n    console.log('File picker process initiated.');\n  } catch (error) {\n    console.error('Failed to open file picker:', error);\n  }\n}\n\n// In a browser environment, you might attach this to a button click:\n// document.getElementById('uploadButton')?.addEventListener('click', openFilePicker);\n\n// For demonstration, immediately open the picker if in a browser-like environment (e.g., CodeSandbox)\nif (typeof window !== 'undefined') {\n  openFilePicker();\n} else {\n  console.log('Running in Node.js environment. Picker UI cannot be displayed directly.');\n}\n","lang":"typescript","description":"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)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=3.x for picker 4.0 integration"},{"fix":"Ensure your file input argument matches the runtime environment: a string file path for Node.js or a Blob/File object for browsers.","message":"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).","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0 (CDN usage)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Log into your Filestack developer portal, check your billing status, and ensure all invoices are paid. Update any expired payment methods.","cause":"This error typically indicates an issue with your Filestack account, most commonly an unpaid invoice.","error":"{\"error\":\"application is blocked\"}"},{"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.","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.","error":"TypeError: Picker is not a constructor (or similar 'Uncaught (in promise) Error: Filestack Picker Initialize Error')"},{"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.","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`).","error":"Content Security Policy (CSP) errors related to Filestack domains"},{"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.","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.","error":"Filestack SDK not working with ad blockers / trackers"}],"ecosystem":"npm"}