React file manager: install, integrate and test

What you will build

A React app with the File Storage file manager on /, connected to your storage, with tests that prove it mounts, licenses and uploads. The steps work the same way in an existing app; skip the scaffolding step.

Prerequisites

Node.js 20 LTS or newer.
A production API key (fs_live_…) from Dashboard → Keys. Keys only work on an active plan.
Your page hosts registered under Dashboard → Websites. Once any website is registered, the key only works on those hosts, so add localhost for development alongside your production domain.
A storage backend: your own S3 proxy or Managed storage (Free includes 1 GB). See Choose storage.

1. Create the project

Skip this if you already have a React app. Any bundler works; this guide uses Vite.

Terminal

npm create vite@latest my-files-app -- --template react-ts
cd my-files-app
npm install

2. Load the SDK from the CDN

Add the stylesheet and script to the <head> of index.html. A plain (non-deferred) script runs before your app bundle, so window.FileStorageSDK exists by the time React renders.

index.html

<link rel="stylesheet" href="https://cdn.filestorage.io/file-storage.css" />
<script src="https://cdn.filestorage.io/file-storage.min.js"></script>

3. Add environment variables

Create .env.local in the project root (it is git-ignored by the Vite template).

.env.local

VITE_FILESTORAGE_API_KEY=fs_live_…
VITE_FM_PROXY_URL=http://localhost:3847

4. Type the global

The CDN build attaches to window. Declare it once so TypeScript knows the shape.

src/filestorage.d.ts

export {}

declare global {
  interface FileStorageMountOptions {
    el: string | HTMLElement
    apiKey: string
    s3?: {
      proxyBaseUrl: string
      publicObjectBaseUrl?: string
      headers?: () => Record<string, string>
    }
    http?: {
      baseUrl: string
      headers?: () => Record<string, string>
    }
    widget?: 'full' | 'picker' | 'upload' | 'media'
    accessMode?: 'full' | 'read-only' | 'upload-only'
  }

  interface Window {
    FileStorageSDK?: {
      mount(options: FileStorageMountOptions): { unmount(): void }
    }
  }
}

5. Create the component

Mount in useEffect and return unmount as the cleanup. React StrictMode mounts, unmounts and re-mounts in development; the cleanup keeps that safe.

src/FileManager.tsx

import { useEffect, useRef } from 'react'

export function FileManager() {
  const ref = useRef<HTMLDivElement>(null)

  useEffect(() => {
    if (!ref.current || !window.FileStorageSDK) return
    const { unmount } = window.FileStorageSDK.mount({
      el: ref.current,
      apiKey: import.meta.env.VITE_FILESTORAGE_API_KEY,
      s3: { proxyBaseUrl: import.meta.env.VITE_FM_PROXY_URL },
    })
    return unmount
  }, [])

  return <div ref={ref} style={{ height: '70vh' }} />
}

6. Render it

Use the component anywhere. With React Router, put it on its own route.

src/App.tsx

import { FileManager } from './FileManager'

export default function App() {
  return (
    <main>
      <h1>Files</h1>
      <FileManager />
    </main>
  )
}

Choose storage

The UI is the same either way; only the mount option changes.

Your S3 proxy

The examples above already use this: s3.proxyBaseUrl points at a small server you run that holds the AWS credentials. Locally that is usually http://localhost:3847. The routes it must implement are in the S3 proxy contract; for PHP, Laravel or other stacks see Backends & cloud.

Allow your app origin on the proxy (http://localhost:5173 in development) or uploads will fail with CORS errors.

Managed storage

File Storage provisions an isolated prefix for your account on our AWS bucket, so there is no proxy to run and no AWS keys to hold. Replace the s3 option in FileManager.tsx:

src/FileManager.tsx

const apiKey = import.meta.env.VITE_FILESTORAGE_API_KEY

const { unmount } = window.FileStorageSDK.mount({
  el: ref.current,
  apiKey,
  http: {
    baseUrl: 'https://api.filestorage.io/v1/managed',
    headers: () => ({ 'X-FileStorage-Api-Key': apiKey }),
  },
})

The exact base URL and your tenant status are shown in Dashboard → Managed storage.

Run it locally

Terminal

npm run dev

Open http://localhost:5173. You should see a short license check, then the file manager listing the root folder.

Test

Manual checklist

With DevTools open on the Network tab, reload http://localhost:5173 and confirm:

POST https://api.filestorage.io/v1/license/validate returns 200 with "valid": true.
The first list call returns 200: /list on your proxy, or /v1/managed/api/files/list on Managed.
Upload a file, then rename it, move it into a new folder, and delete it. Each action should succeed without a console error.
Reload the page. The folder you created is still there, which proves the files reached storage.
Navigate away and back (or unmount the component). Exactly one file manager appears.

Unit test

Unit tests should not hit the network. Stub window.FileStorageSDK and assert that the component mounts into its element and cleans up.

Terminal

npm install -D vitest jsdom @testing-library/react

vite.config.ts

/// <reference types="vitest/config" />
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'

export default defineConfig({
  plugins: [react()],
  test: { environment: 'jsdom' },
})

src/FileManager.test.tsx

import { render } from '@testing-library/react'
import { afterEach, expect, test, vi } from 'vitest'
import { FileManager } from './FileManager'

const unmount = vi.fn()
const mount = vi.fn(() => ({ unmount }))

afterEach(() => vi.clearAllMocks())

test('mounts File Storage into its host element and cleans up', () => {
  window.FileStorageSDK = { mount }
  const view = render(<FileManager />)

  expect(mount).toHaveBeenCalledTimes(1)
  expect(mount).toHaveBeenCalledWith(
    expect.objectContaining({ el: expect.any(HTMLDivElement) }),
  )

  view.unmount()
  expect(unmount).toHaveBeenCalledTimes(1)
})

Terminal

npx vitest run

End-to-end (Playwright)

This runs your real app in a browser against the real license API and storage, so it catches what unit tests cannot: CDN loading, domain registration, CORS and uploads.

Terminal

npm init playwright@latest -- --quiet --lang=ts --gha

playwright.config.ts

import { defineConfig } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  use: { baseURL: 'http://localhost:5173' },
  webServer: {
    command: 'npm run dev',
    url: 'http://localhost:5173',
    reuseExistingServer: !process.env.CI,
  },
})

e2e/file-manager.spec.ts

import { expect, test } from '@playwright/test'

test('File Storage mounts with a valid license', async ({ page }) => {
  const license = page.waitForResponse((r) => r.url().includes('/v1/license/validate'))
  await page.goto('/')

  expect((await license).status()).toBe(200)
  await expect(page.locator('[data-filestorage-license="denied"]')).toHaveCount(0)
  await expect(page.getByRole('button', { name: 'Upload', exact: true })).toBeVisible()
})

test('uploads a file into the current folder', async ({ page }) => {
  const name = `e2e-${Date.now()}.txt`
  await page.goto('/')

  await page.getByRole('button', { name: 'Upload', exact: true }).click()
  const dialog = page.getByRole('dialog', { name: 'Upload files' })
  await dialog.locator('input[type="file"]').setInputFiles({
    name,
    mimeType: 'text/plain',
    buffer: Buffer.from('hello from playwright'),
  })
  await dialog.getByRole('button', { name: /^Upload \(1\)$/ }).click()

  await expect(page.getByText(name).first()).toBeVisible()
})

Terminal

npx playwright test

Go to production

Add your production domain under Dashboard → Websites.
Set the production API key and storage URL in your host’s environment settings.
Build with npm run build and deploy the output.
If you use a Content Security Policy, allow cdn.filestorage.io in script-src and style-src, and api.filestorage.io plus your proxy origin in connect-src.
Run the Playwright suite against the deployed URL (set baseURL) as a smoke test.

Troubleshooting

Symptom	Fix
Two file managers appear in development	The effect is missing its cleanup. Return `unmount` from `useEffect`.
`import.meta.env.VITE_…` is `undefined`	The variable needs the `VITE_` prefix, and you must restart `npm run dev` after editing `.env.local`.
`FileStorageSDK is undefined`	The CDN script did not load before mount. Check the Network tab for a 200 on `file-storage.min.js` and any Content Security Policy errors.
`DOMAIN_NOT_ALLOWED`	The page host is not in Dashboard → Websites. Add `localhost` for local work and your production domain before deploying.
`UNPAID_PLAN` or `INVALID_API_KEY`	Use a non-revoked production key from an account with an active plan.
CORS error on `/list` or `/upload`	Your proxy must allow the app origin (`http://localhost:5173` locally) for `POST` with `Content-Type` and multipart bodies.
File manager renders with zero height	The host element needs an explicit height (the examples use `70vh`).

All mount options, store contracts and widget modes are in the integration guide.