TypeScript icon, indicating that this package has built-in type declarations

    3.25.0 • Public • Published

    Javascript SDK for the Filestack API and content management system.

    Table of Contents

    What's in the box?

    • A multi-part uploader powered on the backend by the Filestack CIN.
    • An interface to the Filestack Processing Engine for transforming assets via URLs.
    • The Filestack Picker - an upload widget for the web that integrates over a dozen cloud providers and provides pre-upload image editing.


    npm install filestack-js

    To get your free API key, sign up for a Filestack account here:

    API Documentation



    ES module

    import * as filestack from 'filestack-js';
    const client = filestack.init('apikey');

    UMD module

    <script src="//{MAJOR_VERSION}.x.x/filestack.min.js" crossorigin="anonymous"></script>
      const client = filestack.init('apikey');

    where {MAJOR_VERSION} is one of the MAJOR versions of the filestack-js ie:

    <script src="//" crossorigin="anonymous"></script>
      const client = filestack.init('apikey');


    Subresource Integrity (SRI) is a security feature that enables browsers to verify that files they fetch (for example, from a CDN) are delivered without unexpected manipulation. It works by allowing you to provide a cryptographic hash that a fetched file must match

    To obtain sri hashes for filestack-js library check manifest.json file on CDN:{LIBRARY_VERSION}/manifest.json
    <script src="//{LIBRARY_VERSION}/filestack.min.js.gz" integrity="{FILE_HASH}" crossorigin="anonymous"></script>

    Where {LIBRARY_VERSION} is currently used library version and {FILE_HASH} is one of the hashes from integrity field in manifest.json file


    CommonJS module

    const client = require('filestack-js').init('apikey');

    Module Overview

    The package.json specifies two separate modules:

    • main for the CommonJS module (intended for Node runtimes)
    • browser for the pre-bundled ES module (intended for browser runtimes)

    Node projects which depend on filestack-js will follow the main field in package.json. When building for the browser, newer tools (like Webpack, Rollup, and Parcel) follow the browser field, which will resolve to the pre-bundled ES module. Both modules follow the same API, but some methods behave differently based on their runtime. For example, client.upload treats the file argument as a file path in Node but in browsers it assumes a Blob object.

    The pre-bundled browser module is also available in UMD format. This is useful if you are using script tags on a web page instead of bundling your application. It can be retrieved from both the Filestack CDN and the unpkg CDN:

    Releases Info

    Major releases will bo listed (with detailed examples) in releases folder starting from version 3.0.0

    Live examples (JSFiddle)

    Upload image
    Open picker
    Open picker in inline mode
    Crop images
    Multiple drop panes
    Import using RequireJS
    Retrieve image data
    Transform image
    Custom Picker CSS
    Assign file to user

    Examples can be run locally with:

    npm run examples

    Picker Quick Start

    If you are here to use the picker widget, it can be initialized from the Filestack client by calling client.picker(options). Options for the picker are documented here.

    The picker instance returned from client.picker can be controlled with a few methods:

    • open - Create the application and mount it into the DOM based on the displayMode.
    • close - Close the application and remove its resources from the DOM.
    • crop(files) - Create the application, mount it, and pre-select the passed files for cropping.
    • cancel - Cancel all uploads controlled by this instance.

    Please see our examples above to learn more about customizing the picker for your use case.


    If you target IE11 or iOS before 8.0 you will need to add additional polyfills to your page or application. (We are no longer support IE11 and older browser, so it can stop working on this browser)

    Polyfills we recommend:**

    Module (for bundling):

    Script (for script tag):


    Most tests in this library are expected to interface with actual backend services. Because we like to run tests during development, these services are mocked during unit testing.

    All tests are using Jest.

    To run units:

    npm test


    Filestack-js uses debug, so just run with environmental variable DEBUG set to fs.*.


    DEBUG=fs.* node example_upload.js


    Debug's enable state is persisted by localStorage

    localStorage.debug = 'fs:*'

    And then refresh the page.

    Error event

    The upload.error event was added to sdk. To obtain every upload request error just add callback to it. Error contains details field with responseBody, responseHeaders, code (only when error type is FilestackErrorType.REQUEST)

      const client = filestack.init('apikey');
      client.on('upload.error', (filestackError) => {

    Upload abort throws an FilestackError with type FilestackErrorType.ABORTED

    Sentry Integration

    If you're using Sentry to monitor your application, Filestack will automatically report upload errors to Sentry, and tag them with helpful diagnostic information via @sentry/minimal.


    We use SemVer for versioning. For the versions available, see the tags on this repository.


    We follow the conventional commits specification to ensure consistent commit messages and changelog formatting.


    npm i filestack-js

    DownloadsWeekly Downloads






    Unpacked Size

    8.59 MB

    Total Files


    Last publish


    • filestack-dev