HTML / JavaScript guide

What you will build

A HTML / JavaScript 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.

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>Files</title>
    <link rel="stylesheet" href="https://cdn.filestorage.io/file-storage.css" />
  </head>
  <body>
    <div id="fm" style="height: 70vh"></div>

    <script src="https://cdn.filestorage.io/file-storage.min.js"></script>
    <script>
      FileStorageSDK.mount({
        el: '#fm',
        apiKey: 'fs_live_…',
        s3: { proxyBaseUrl: 'http://localhost:3847' },
      })
    </script>
  </body>
</html>

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:3000 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:

const apiKey = 'fs_live_…'

FileStorageSDK.mount({
  el: '#fm',
  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

npx serve .

Open http://localhost:3000. 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:3000 and confirm:

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

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.

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

import { defineConfig } from '@playwright/test'

export default defineConfig({
  testDir: './e2e',
  use: { baseURL: 'http://localhost:3000' },
  webServer: {
    command: 'npx serve .',
    url: 'http://localhost:3000',
    reuseExistingServer: !process.env.CI,
  },
})

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()
})

npx playwright test

Go to production

1. Add your production domain under Dashboard → Websites.
2. Set the production API key and storage URL in your host’s environment settings.
3. Upload the HTML file to any static host that serves it over HTTPS.
4. 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.
5. Run the Playwright suite against the deployed URL (set baseURL) as a smoke test.

Troubleshooting

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