@brftech/filex

Drop-in <filex-explorer> Web Component for the filex file manager. Wraps the Vue 3 <FileExplorer> SFC from @brftech/filex-core and ships with the Vue runtime bundled in - load it from any CDN, embed in any framework, no peers required.

Install

npm

npm i @brftech/filex

// Side-effect import registers the element.
import '@brftech/filex';

CDN (no build step)

<script type="module" src="https://cdn.jsdelivr.net/npm/@brftech/filex/dist/filex.js"></script>

⚠ @brftech/filex 0.55 needs a filex 0.55 server. Which files open for editing (edit_kinds), the input limits (limits) and the version line (release, commit, built) come from the server's /api/files/capabilities; the package keeps no list of its own to fall back on, so against an older server nothing is offered Edit and nothing opens as an office document. Update the server with the package (API.md).

⚠ An app that prints (ui.print, filex 0.55) prints from filex's own print page, which the explorer frames in your page. Only filex, its desktop app and the server's FILEX_FRAME_ANCESTORS may frame that page, so on another site list your page's origin there - otherwise the app is told printing is unavailable (CONFIGURATION.md → Security headers and framing).

Styles

No CSS import, no <link>. The bundle carries the explorer's stylesheet inside the JavaScript and appends it to <head> once, the first time an element mounts - so the two lines above are all a page needs, whether they come from a CDN or a bundler. It is @brftech/filex-core's sheet byte for byte, which is what keeps this distribution and the Vue one looking the same.

A style.css is published as well, for a host that would rather serve the sheet itself:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@brftech/filex/dist/style.css">

The look is the --fe-* custom properties; set them on any scope above the element (:root, a wrapper div) and the explorer follows. The element deliberately has no shadow root for exactly this reason - the host page's tokens, dark mode and fonts reach inside. The consequence is that a host cannot fill a slot in it either, so the product mark in the top bar comes from config.brand ({ name, markUrl }).

Use

Plain HTML

<filex-explorer
  api-base="https://files.example.com"
  locale="tr"
  theme="auto"
></filex-explorer>

<script type="module">
  const el = document.querySelector('filex-explorer');
  // ⚠ Configure BEFORE the element is registered. A static `import` would be
  // hoisted above these lines, mount the explorer with no credentials and
  // spend its first listing on a request that can only fail.
  el.config = {
    apiBase: 'https://files.example.com',
    auth: { kind: 'bearer', token: '<jwt>' },
    rootPath: 'main://projects/acme',
  };
  // ⚠ The payload is e.detail[0] - see Events below.
  el.addEventListener('error', (e) => console.error(e.detail[0].message));
  el.addEventListener('share-created', (e) => navigator.clipboard.writeText(e.detail[0].url));
  await import('@brftech/filex');   // registers <filex-explorer>
</script>

Inside a non-Vue framework

The element is just a normal DOM custom element - Angular, Svelte, plain JS, no problem.

<filex-connections> - reaching the server without a browser

The package registers a second element. filex can be spoken to as S3, SFTP, FTPS, NFSv3 and WebDAV, and mounted with filex mount; this is where a user mints the credential each protocol takes and reads instructions built from that deployment rather than a template with angle brackets in it. It is the same component the filex admin panel and the filex desktop app render - there is no second set of instructions anywhere.

Since v0.43.0 this element is the "how to connect" surface only. The initial-tab attribute and the changed event are gone with the Storages tab: it does not create, edit or delete a storage. Storages are managed in the filex admin panel.

<filex-connections></filex-connections>

<script type="module">
  import '@brftech/filex';
  const el = document.querySelector('filex-connections');
  el.setAttribute('closable', '');     // show a close button, emits `close`
  el.config = {
    apiBase: 'https://files.example.com',
    auth: { kind: 'bearer', token: '<jwt>' },
    locale: 'tr',
  };
  el.addEventListener('error', (e) => console.error(e.detail));
</script>

⚠⚠ Configure it through the config property, not attributes - el.config = { ...el.config, locale: 'tr' }. buildConfig merges {...attributes, ...config} and the config object wins, so an attribute is only ever a fallback for a key the config does not carry. That exact mistake shipped in v0.19.0: the shell went Turkish while the file list stayed English, and the element reported locale === 'tr' the whole time.

See docs/PROTOCOLS.md.

Attributes

Simple attributes are auto-parsed into the underlying config prop:

For anything richer (auth, custom endpoints, share base, …) set the config JS property after element creation. Properties merge on top of attributes.

config.callerKind - "user" (a person) or "app" (an integration: a host app's proxy, a bot). "app" leaves out the surfaces that belong to one identity: API keys, Recent, Starred, Shared with me. Upload, the storages, Trash and "Connections" stay, so an embed is still an embed. Omit it and the element asks the server (GET /api/files/capabilities → caller_kind), which is authoritative because only the server knows a token's kind; set it when your page already knows, to spare the moment before that answer lands. ⚠ Proxying every visitor with one shared API token IS the "app" case - see docs/MCP.md.

Events

Native CustomEvents - listen with addEventListener. ⚠ The SFC payload is event.detail[0], not event.detail: Vue dispatches a custom element's emit as new CustomEvent(name, { detail: args }), where args is the emit's argument list. event.detail.url is therefore undefined, and for selection-change - whose payload is itself an array - event.detail.length is always 1.

Build

pnpm build      # vue-tsc + vite lib build → dist/filex.js + dist/style.css

⚠⚠ sideEffects in package.json has to keep matching every file the build emits (./dist/*.js, ./dist/*.cjs), not a list of names. The entry is only a re-export: customElements.define and the stylesheet injection live in the hashed chunk beside it, and a list that does not cover the chunk lets a bundler drop it - the element is then never registered, the sheet never injected, and a React or Vite host renders an empty page with no error anywhere. web/tests/deploy/packageLook.test.ts is the guard.

License

MIT