npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@widgetic/file-browser

v0.5.49

Published

> **Internal building block.** This package is part of Widgetic's own apps and is not a supported integration surface. Partners: use [`@widgetic/ui-sdk`](https://www.npmjs.com/package/@widgetic/ui-sdk) instead.

Readme

@widgetic/file-browser Module

Internal building block. This package is part of Widgetic's own apps and is not a supported integration surface. Partners: use @widgetic/ui-sdk instead.

A modern reusable web-based file browser module built with SvelteKit and Tailwind CSS. The module provides an intuitive interface for managing files and folders with features like search, file preview, recent files (at the bottom), and batch operations (upload, move).

Quick Start

  1. Install dependencies: npm install
  2. Start development server: npm run dev
  3. Build for production: npm run build

Documentation

See CODE-OVERVIEW.md for detailed documentation including:

  • Project structure
  • Component architecture
  • State management
  • Feature documentation
  • Best practices

Setup

Before using this package, you need to set up pnpm correctly:

npm run ipnpm

This will:

  1. Create the necessary directories
  2. Install pnpm globally
  3. Configure pnpm with consistent settings
  4. Set the virtual store directory to a consistent location

Building and Linking

To build the package and make it available for linking:

# In the file-browser directory
npm run build
# this will run 'vite build && npm run package && npm run plink'

Linking into Another Project using pnpm link

# In your consuming project directory
pnpm link --global @widgetic/file-browser

Usage

<script>
  import { FileBrowser } from '@widgetic/file-browser';
  // Or import specific components
  import { SomeComponent } from '@widgetic/file-browser';
</script>

<FileBrowser />

Using your own media library

By default the File Browser shows the Widgetic account's uploads. The path above them reads Files / Uploads. An image or video preview opens as a 100px card and eases to the picture. The video controls are the width of that picture, with space on either side of it. Filter and sort stay on one line; the search field gives up width when the container is narrow. A file over 10 MB goes up in pieces unless allowResumableUploads is false.

A platform that already has a media library of its own (a CMS, an S3 bucket, a DAM) can hand the File Browser that library instead, as plain functions. The File Browser then lists, uploads, renames and deletes through those functions and never talks to Widgetic.

<script lang="ts">
  import { FileBrowser, type MediaLibraryProvider } from '@widgetic/file-browser';

  const mediaLibrary: MediaLibraryProvider = {
    id: 'acme-assets',
    label: 'Acme assets', // the title above the files. Default: "Uploads"

    // Required. One page of the library, newest files first.
    async list({ cursor, limit, signal }) {
      const response = await fetch(`/api/assets?cursor=${cursor ?? ''}&limit=${limit}`, { signal });
      if (!response.ok) throw Object.assign(new Error('Could not load your files'), { status: response.status });
      const page = await response.json();
      return {
        items: page.assets.map((asset) => ({
          id: asset.id,
          name: asset.fileName,
          url: asset.publicUrl,
          mimeType: asset.contentType,
          size: asset.bytes,
        })),
        nextCursor: page.next ?? null, // null (or leaving it out) means this was the last page
      };
    },

    // Optional. Leave a function out and its button is not shown.
    async upload({ file, onProgress, signal }) { /* store the file, call onProgress(0..100), return it as a MediaLibraryFile */ },
    async rename({ id, name, signal }) { /* rename it; return the file as it is now, or nothing */ },
    async delete({ id, signal }) { /* remove it */ },
  };
</script>

<FileBrowser
  {mediaLibrary}
  on:select={(event) => console.log('picked', event.detail.files)}
  on:error={(event) => console.warn('media library problem', event.detail)}
/>

What the File Browser does with a library

  • One flat list. A media library has no folders, so there is no New folder, Move, breadcrumb or Recent files.
  • Pages. It calls list with limit: 100 and the previous page's nextCursor until there is no next page. It reads at most 1,000 files (and at most 50 pages) and then shows "Only the newest files are shown." Search and the type filter only look at the files that were loaded.
  • Only the actions the library can do. Upload needs upload, Rename needs rename, Delete needs delete. Download is always offered. capabilities can switch actions off (capabilities: { delete: false }), never on.
  • Nothing is kept on the visitor's device. No local cache, no saved file tree, and the picked files are not remembered between visits (a shared browser must not show the next visitor the previous one's picks). Pass persistSelection to keep them anyway.
  • Library mode ignores data, useDemoContent, enableLocalCache and the Widgetic upload settings.
  • The library's own failures are shown as they are. The message of the error you throw reaches the visitor (cut at 300 characters): a screen with "Try again" when the first page cannot be read, a notice when a later page fails, a message in the upload panel, a toast for rename and delete. Toasts are drawn by the design system's <ToasterModal />: pass renderToaster and the File Browser draws one itself, in the language of locale and messages (toast.regionLabel and toast.closeLabel are what a screen reader hears). An app that renders its own <ToasterModal /> (the Widgetic site's layout does) leaves renderToaster off, or its toasts would be drawn twice. With neither, a refused rename or delete shows the visitor nothing and the error event is the only sign.
  • Calls are given 30 seconds (list, rename, delete). An upload has no time limit, the visitor can cancel it. signal is aborted when the visitor cancels, or the File Browser is closed: stop your request then.

A file (MediaLibraryFile)

| Field | | | | --- | --- | --- | | id | required | Stable and unique in the library. Handed back unchanged on select, rename and delete. | | name | required | Shown to the visitor, with its extension (logo.png). | | url | required | Where the visitor's browser fetches the file. | | mimeType | optional | Tells images, audio, video and documents apart when the extension cannot (see below). | | size | optional | Bytes. | | modified | optional | ISO 8601 string, Date, or milliseconds since 1970. | | thumbnail | optional | A small preview picture. Without it an image is drawn from url and any other file gets its type icon. | | hash | optional | Handed back as is. Never interpreted. |

Which tab a file lands under (Images, Video, Audio, Documents, Fonts, SVG) is decided in this order: the extension in its url, the extension in its name, then its mimeType. A file nothing says anything about is a document. So /media/8f3a2c with name: 'logo.png', or a blob: address with mimeType: 'image/png', is an image. Give a name with its extension, or a mimeType, whenever your addresses carry no extension: otherwise those files only show up under "All" and "Documents".

Everything a library returns is treated as untrusted. A file without an id, name or usable url, or with a duplicate id, is skipped (with a console warning) instead of breaking the list. Ids longer than 512 characters are refused, names longer than 255 are cut, and a page uses at most its first 1,000 files. Addresses must be http:, https:, a path on the page's own site, or blob:; a thumbnail may also be a small data: picture. javascript: and every other kind of address is refused. Names are always shown as text, never as HTML.

A file on another website needs a CORS header (Access-Control-Allow-Origin) for the previews that read it with a script: text, PDF and font previews. Pictures, audio and video are shown without it.

Errors

Throw anything from a library function: an Error (its message is shown), or an object with a status (HTTP). The File Browser maps it to a code:

| Code | When | | --- | --- | | UNAUTHORIZED | status 401 | | FORBIDDEN | status 403 | | NOT_FOUND | status 404 | | NETWORK | fetch could not reach the server (a TypeError) | | INVALID_RESPONSE | list did not answer with { items: [...] }, or keeps returning the same files | | NOT_SUPPORTED | the library has no function for this (for example no upload) | | FAILED | anything else |

An AbortError is a cancellation, not a failure: nothing is shown and no error event is sent.

Events

  • select — { files }: the files the visitor picked, as the File Browser holds them (id, name, url, ...).
  • error — { message, code, action, file? } for a problem with the library. action is setup (the mediaLibrary option is not a media library), load, upload, rename or delete; file is the file name for an upload. Listen to it to log problems or to refresh your own token (UNAUTHORIZED).

The Widgetic library as a provider

createWidgeticMediaLibrary({ apiBasePath, getAccessToken }) is the Widgetic upload library (GET /v1/uploads, POST /v1/uploads) as a provider. getAccessToken('initial' | 'expired', refusedToken?) is called before every request, and again with 'expired' (and the token the API refused) when it answers 401, after which the request is tried once more. It has no Rename or Delete: the API cannot do them yet.

Languages

The File Browser shows English until it is told otherwise. Two props change that, a third says which way it is read, and all of them can change while the File Browser is open:

<FileBrowser
  locale="de"
  messages={{
    'action.cancel': 'Abbrechen',
    'action.delete': 'Löschen',
    'toolbar.deleteMany': '{count, plural, one {# Datei löschen} other {# Dateien löschen}}',
  }}
/>
  • locale is a BCP 47 language tag (de, pt-BR, ar-EG). It decides the plural rules and how numbers, dates, "2 days ago" and file sizes are written (all through Intl). It translates nothing. Blank or left out is English. A tag the browser does not know is said once in the console and numbers and dates stay English.
  • messages replaces words. Every word the File Browser shows is a message with a key; give the keys you want to change and every key you leave out stays English, so a language can be added one screen at a time. A key that does not exist is ignored and the console says which key you probably meant.
  • dir is 'ltr' or 'rtl'. It is not a word and it is not taken from locale: it says which way the screen is read, and dir="rtl" turns the File Browser around for a language that is written right to left. Left out, the File Browser is read the way the screen around it is (inside the composition editor it turns around with it), and left to right when nothing around it says. See "Right to left" below.

FILE_BROWSER_MESSAGES is the list: an object of every key and its English text (the keys are grouped by where the words appear), and it is the list to hand to a translator:

import { FILE_BROWSER_MESSAGES } from '@widgetic/file-browser';

console.log(Object.keys(FILE_BROWSER_MESSAGES).length); // every word of the File Browser
console.log(FILE_BROWSER_MESSAGES['toolbar.deleteMany']); // '{count, plural, one {Delete # file} other {Delete # files}}'

| Keys start with | The words of | | --- | --- | | action., list.separator | buttons that appear in several places (Cancel, Delete, Rename, Select, Add to Editor) | | search., filter., filterName., filterOption., sort., breadcrumbs. | the bar above the files and the path | | empty. | what the list says when there is nothing to show | | library., libraryError. | the page's own media library: its name, and what the File Browser says when it gave no reason | | size., date. | file sizes ("1.5 MB") and "2 days ago" | | fileKind., fileTypes. | the kinds of file inside a sentence ("Upload image files") | | upload. | the upload panel, its progress and its problems | | dialog. | Rename, New folder and Delete: titles, hints and the sentences about a name that is not allowed | | toast. | the messages that pop up after an action | | folder., item., recent., menu., newFolder. | folders and items in the list, and their menus | | selectedFiles., toolbar. | the bar over a selection and the list of selected files | | searchModal., moveDialog. | the search window and the Move window | | preview., metadata., fontPreview. | the previews and the details of a file |

Writing a message

A message is text. Two kinds of {...} have a meaning:

| Write | It shows | | --- | --- | | {name} | a value the File Browser puts in. A number is written the way the locale writes numbers (1,234 or 1.234). | | {count, plural, one {# file} other {# files}} | the branch that fits the number in the page's language. other is required; =0 {none} matches exactly 0; # is the number. A language with more forms says so: Polish uses one, few, many and other. |

\{, \}, \# and \\ write that character itself. An apostrophe is only an apostrophe: Delete '{name}'? works. Each English message names the values it is given ('filter.by': 'Filter by {type}'): a translation may leave one out, and it may use a value in any order, but it cannot ask for a value the message is never given (it would show as written, {kind}).

// Polish: "1 plik", "2 pliki", "5 plików", "1,5 pliku"
'toolbar.deleteMany': '{count, plural, one {Usuń # plik} few {Usuń # pliki} many {Usuń # plików} other {Usuń # pliku}}'

Finding a mistake before a visitor does

checkFileBrowserMessages(messages) checks a messages object without showing anything, and describeMessageProblem turns each problem into a sentence. It finds a key that does not exist (with the nearest real one), a value that is not text, a template that does not parse, and a message that asks for a value it is never given. An empty list means every message will be used. Put it in a test of your page:

import { checkFileBrowserMessages, describeMessageProblem } from '@widgetic/file-browser';
import german from './file-browser.de.json';

expect(checkFileBrowserMessages(german).map(describeMessageProblem)).toEqual([]);

While the File Browser runs, a message that cannot be used is never thrown: the English text of that key is shown and the console says [FileBrowser] ... once.

Right to left

Arabic, Hebrew, Persian, Urdu and the other languages that are written from right to left start a line on the right. dir="rtl" makes the File Browser read that way, and resolveTextDirection(locale) from @widgetic/design-system/i18n answers "which way is this language written" ('rtl' or 'ltr', never an error, 'ltr' for a blank or unreadable tag):

<script>
  import { FileBrowser } from '@widgetic/file-browser';
  import { resolveTextDirection } from '@widgetic/design-system/i18n';

  export let locale = 'ar';
</script>

<FileBrowser {locale} dir={resolveTextDirection(locale)} />
  • dir is a prop of its own. The File Browser is also a part of other screens (the file picker of the composition editor, and so the widget creator), and the screen around it decides, not the words: the File Browser in a picker inside an Arabic editor is read right to left whatever its own locale, and one inside an English editor left to right. Left out, it follows that screen (a component above it that calls provideTextDirection(store) from @widgetic/design-system/components/textDirection); a dir that is given wins over it. The page around it does not decide either: a File Browser on a page that is written right to left stays left to right until it is given dir="rtl" or sits in a screen that is.
  • What turns around. The list starts on the right and the row that does not fit goes on under it. The search box, the sort and filter controls, the selection bar, the path bar, the upload panel and the windows (Rename, New folder, Delete, Move, search, the selected files and the preview) are laid out from the right, and the close button of a window is in the corner where a line starts. Menus open toward the end of the line, and the pop-up of an action comes up in the bottom corner where a line starts. Arrows that mean back and forward are mirrored; in the preview the arrow key that points toward the end of the line goes on to the next file.
  • Trying it. The demo page of this package (npm run dev) turns around with ?dir=rtl in its address.
  • Names of files and folders are read by their own first letter (dir="auto"), so a Latin name such as 2024 report.pdf is not put in the wrong order in a row of Arabic ones. On a left to right screen nothing is added.
  • A name inside a sentence ("Failed to delete 2024 report.pdf") sits between two invisible marks, the Unicode isolates U+2068 and U+2069, whenever locale is a language written right to left, so the words around it cannot turn it around (a name that starts with a digit or has a hyphen would be). A screen reader does not say them; a test that compares the text of a pop-up has to leave them out. The translator does this for every package that uses it, whatever dir says.
  • What stays left to right on purpose: the time line of the video player, because time runs from left to right in every language.
  • Not looked at in a browser yet: the folder tree, the Move window, the search window and the list of recent files use the same placement as the rest and are covered by the source check below, but no browser test opens them in Arabic.
  • Keeping it so. tests/rtl/sourcePlacement.test.ts reads the whole source with auditPhysicalPlacement from @widgetic/design-system/rtl/audit and fails on a class or a style that puts something on a physical side (left, right, ml-, pr-, text-left, border-l, rounded-tl ...). Write the logical one (start, end, ms-, pe-, text-start, border-s, rounded-ss) or say why with the note rtl-ok on the same line or the line above.

What stays as it is

  • Words that belong to someone else. The File Browser shows what your media library says as it says it: the message of an error you throw from list, upload, rename or delete is not translated (the libraryError. messages are only used when the library gave no reason), and neither are your file names, your library's label, or the names of folders a visitor made. The same goes for a sentence Widgetic's API sends back.
  • error events. event.detail.message stays English: it is for your logs, not for the visitor.
  • Right to left. The words and the numbers follow locale and the layout follows dir; the two are set apart on purpose (see "Right to left" above), so a page that gives a right to left locale and no dir has the words in Arabic and a layout that reads left to right.
  • The design system. The File Browser needs @widgetic/design-system 0.5.16 or newer. Its words are made by the design system's @widgetic/design-system/i18n (the same translator the editor and the other packages use), and the words of the Rename and New folder windows, the close button of every window, the path bar and the PDF viewer come from the design system too. With an older one the File Browser does not load: update the design system.

The @widgetic/ui-sdk module of the File Browser takes the same locale and messages, and adds setLanguage(); see its README, "Speaking your visitors' language".

Available Components

The package exports all components from:

  • Core components
  • Modal components
  • Item components
  • Preview components
  • UI components

It also exports types.

Development

To develop the package:

Install dependencies

npm install

Its bins (check-runtime-deps, used by npm run check:deps / test:deps) come from the installed @widgetic/dev-tools dependency.

Sibling packages

This app compiles sibling @widgetic/* source in dev through the dev-alias setup @widgetic/dev-tools owns. The alias tables, the $lib remap, and everything else the mapping needs come from the installed @widgetic/dev-tools dependency. An ordinary npm install is the whole setup — there is no linking step.

The why and the silent-degrade failure mode live in the dev-tools README.

Publishing

GitLab CI on main publishes this package. Bump version in package.json and push main. The job is an npm Trusted Publisher (NPM_ID_TOKEN) and skips a version that is already on npm. A laptop publish is the fallback when CI minutes are gone. The token stays in ~/.npmrc and is never committed.

Publishing starts here: npm run package builds the dist/ directory that is the only content the published tarball ships. Linked consumers keep resolving this checkout’s files until the release lands, so a change is not real for anyone else until it publishes. After publishing, each consumer package bumps its dependency to the new version and refreshes its lockfile with npm install, so npm ci resolves the release from the registry. A consumer that skips the lockfile refresh keeps resolving the old version, so the version bump and the lockfile refresh land as one commit.

Start the server

npm run dev

To watch for changes and rebuild the package while linked in another project:

npm run package:watch

Troubleshooting

If you encounter issues with pnpm linking:

andy@Andy-MBPro-14-2021 file-browser % npm run plink

> @widgetic/[email protected] plink
> pnpm link --global

 ERR_PNPM_UNEXPECTED_VIRTUAL_STORE  Unexpected virtual store location

The dependencies at "/Users/andy/Library/pnpm/global/5/node_modules" are currently symlinked from the virtual store directory at "/Users/andy/Library/pnpm/global/5/node_modules/.pnpm".

pnpm now wants to use the virtual store at "/Users/andy/Library/pnpm/global/5/.pnpm" to link dependencies from the store.

If you want to use the new virtual store location, reinstall your dependencies with "pnpm install".

You may change the virtual store location by changing the value of the virtual-store-dir config.

Solution:

  1. Make sure you've run the ipnpm script

  2. Try unlinking and relinking:

    # Remove from global store
    cd /Users/$USER/Library/pnpm/global/5
    # Edit package.json to remove the link
    pnpm install
       
    # Then relink
    cd /path/to/file-browser
    pnpm link --global
  3. remove the global store: rm -rf /Users/andy/Library/pnpm/global/5 && mkdir -p /Users/andy/Library/pnpm/global/5 && cd /Users/andy/Library/pnpm/global/5 && echo '{"dependencies":{"pnpm":"^9.15.4"}}' > package.json && npm install -g pnpm && pnpm install",

License

This package is licensed under the Widgetic Integration License (see the LICENSE file in the package): you may use it to integrate Widgetic into your own application, and for nothing else. It is not open source. For any other use, write to [email protected].