Filestack JavaScript SDK

The Filestack Picker is an upload widget that can be initialized from a Filestack client instance using client.picker(options).

Once initialized, the returned picker instance provides the following control methods:

• open(): Creates the application and mounts it into the DOM based on the displayMode provided in options.
• close(): Closes the application and removes its resources from the DOM.
• crop(files): Creates the application, mounts it, and pre-selects the specified files for cropping.
• cancel(): Cancels all uploads currently controlled by this picker instance.

// Example initialization
const picker = client.picker({
  // options from https://filestack.github.io/filestack-js/interfaces/pickeroptions.html
});

// Controlling the picker
picker.open();

Install the Filestack JavaScript SDK using npm to get started with multi-part uploading, image transformations, and the Filestack Picker.

Note: You will need a Filestack API key. You can sign up for a free account at https://dev.filestack.com/signup/free.

npm install filestack-js

By default, Filestack URLs use standard encoding. To avoid issues with special characters in complex transformation parameters or long source URLs, you can enable Base64 encoding using .setBase64(true). When enabled, both the transformation string and the source URL are Base64 encoded within the final URL.

Usage: Call .setBase64(true) on your Filelink instance before calling .toString().

const link = new Filelink('https://example.com/image.jpg', 'YOUR_API_KEY');
link.setBase64(true).resize({ width: 500 });

console.log(link.toString());

To protect your Filestack account and limit client capabilities, you should use server-side generated security policies and signatures. You can set these during initialization via ClientOptions or dynamically using setSecurity().

Using ClientOptions:

const client = filestack.init('apikey', {
  security: {
    policy: 'YOUR_POLICY',
    signature: 'YOUR_SIGNATURE'
  }
});

Using setSecurity():

client.setSecurity({
  policy: 'YOUR_POLICY',
  signature: 'YOUR_SIGNATURE'
});

Note: Both policy and signature are required when providing a security object.

To use Filestack, you must initialize a Client instance with your API key. This instance serves as the entry point for all Filestack operations including uploading, transforming, and managing files.

ES Module usage:

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

UMD (Browser) usage:

<script src="https://static.filestackapi.com/filestack-js/3.x.x/filestack.min.js"></script>
<script>
  const client = filestack.init('apikey');
</script>

The SDK uses the debug library. You can enable debug logging by setting the DEBUG environment variable to fs.*.

Node.js

Set the environment variable before running your script:

DEBUG=fs.* node example_upload.js

Browser

Enable debugging via localStorage and then refresh the page:

localStorage.debug = 'fs:*';

// Browser instruction
localStorage.debug = 'fs:*';

In Node.js environments, use the CommonJS require syntax to initialize the client.

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

If you are using a modern bundler (like Webpack, Rollup, or Parcel) in a browser environment, import the library as an ES module and initialize the client with your API key.

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

For non-module browser environments, include the Filestack library via a <script> tag from the Filestack CDN. The filestack object will be available globally.

<script src="//static.filestackapi.com/filestack-js/3.x.x/filestack.min.js" crossorigin="anonymous"></script>
<script>
  const client = filestack.init('apikey');
</script>

To capture all upload request errors, listen for the upload.error event on the client instance. The error object contains a details field which includes the responseBody, responseHeaders, and a code (specifically when the error type is FilestackErrorType.REQUEST).

Note: An upload abort will throw a FilestackError with the type FilestackErrorType.ABORTED.

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