Vue 3 file manager: install, integrate and test

What you will build

A Vue 3 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 Vue app. When prompted, enable TypeScript and Vitest (used in the test step).

Terminal

npm create vue@latest my-files-app
cd my-files-app
npm install

2. Load the SDK from the CDN

Add the stylesheet and script to the <head> of index.html. The plain script runs before your app bundle, so the SDK is ready in onMounted.

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.

.env.local

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

4. Type the global

Files under src/ are included by the generated tsconfig.app.json.

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 onMounted and unmount in onBeforeUnmount.

src/components/FileManager.vue

<script setup lang="ts">
import { onBeforeUnmount, onMounted, ref } from 'vue'

const host = ref<HTMLElement | null>(null)
let handle: { unmount(): void } | undefined

onMounted(() => {
  if (!host.value || !window.FileStorageSDK) return
  handle = window.FileStorageSDK.mount({
    el: host.value,
    apiKey: import.meta.env.VITE_FILESTORAGE_API_KEY,
    s3: { proxyBaseUrl: import.meta.env.VITE_FM_PROXY_URL },
  })
})

onBeforeUnmount(() => handle?.unmount())
</script>

<template>
  <div ref="host" style="height: 70vh" />
</template>

6. Render it

Use it in App.vue, or as a route component with Vue Router.

src/App.vue

<script setup lang="ts">
import FileManager from './components/FileManager.vue'
</script>

<template>
  <main>
    <h1>Files</h1>
    <FileManager />
  </main>
</template>

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.vue:

src/components/FileManager.vue

const apiKey = import.meta.env.VITE_FILESTORAGE_API_KEY

handle = window.FileStorageSDK.mount({
  el: host.value,
  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

If you did not enable Vitest when scaffolding, install it first. Stub window.FileStorageSDK so the test stays offline.

Terminal

npm install -D vitest jsdom @vue/test-utils

src/components/__tests__/FileManager.spec.ts

import { mount } from '@vue/test-utils'
import { afterEach, expect, test, vi } from 'vitest'
import FileManager from '../FileManager.vue'

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

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

test('mounts File Storage into its host element and cleans up', () => {
  window.FileStorageSDK = { mount: sdkMount }
  const wrapper = mount(FileManager)

  expect(sdkMount).toHaveBeenCalledWith(
    expect.objectContaining({ el: wrapper.element }),
  )

  wrapper.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
Blank area after navigating back to the page	Make sure `onBeforeUnmount` calls `unmount()`, so the next mount starts from a clean element.
`import.meta.env.VITE_…` is `undefined`	Use the `VITE_` prefix and restart the dev server 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.