Browse docs
Storage
Implement storage when your source needs custom access. It resolves file URLs and lists directories; the adapter interprets their data.
Choosing a driver
| Location | Driver | Configuration |
|---|---|---|
| Public HTTP files | http | A URL prefix in basePath. |
| Public HuggingFace dataset | hf | Repository id, with optional revision and path. |
| Private application data | An application-provided driver | Identifiers needed by your access layer. |
Keep credentials in the application access layer. A schema supplies location identifiers; its driver obtains authorized URLs and listings.
The http driver (public)
resolveUrl joins relative paths to basePath and accepts absolute URLs.
list reads an index.json in the requested directory.
For directory discovery, the manifest can be a list of filenames:
It can also contain objects with name, path, type (file or dir) and
optional size. These may be wrapped in an { "entries": [...] } object.
basePath defaults to an empty string.
HuggingFace storage
The hf driver uses public resolve URLs and the paginated Hub tree API.
It does not need index.json.
| Key | Default | Meaning |
|---|---|---|
id | required | Repository identifier, such as organization/dataset. |
basePath | '' | Directory prefix inside the repository. |
revision | 'main' | Revision used for resolve and tree requests. |
repoType | 'datasets' | HuggingFace repository type used in the URL. |
Private data — injected by the host
Wrap your authorized listing and download-URL operations in a Storage factory:
Return URLs that browser media elements can use, such as signed URLs or authorized same-origin endpoints. The application handles their expiry.
The schema names the registered driver:
Register once, or per preview
Register the factory at application startup:
Or provide it when mounting a preview:
Both paths use the module's shared registry. An extensions entry is added only
if its name is absent; it is not scoped to that preview and persists for later
previews. registerStorage explicitly replaces an existing entry.
registerAdapter and registerView likewise support named registration, while
extensions.adapters and extensions.views skip names already registered.
Use distinct names when configurations need different implementations.
Writing your own driver
The public interface is:
Return paths accepted by resolveUrl. Opaque identifiers can serve as paths
while name supplies the extension. Listing is not recursive; check your
adapter's pagination behavior before relying on a paginated backend.
What storage does not do
Storage handles locations; the adapter handles format
and field kind. A file entry's type is not its data kind.