Files Module Recipe

The Files module is a ready-made /files experience on top of the Files API. Instead of hand-building upload zones, folder navigation, previews, and bulk actions, you scaffold the whole thing with one command and own the code.

It gives you two screens:

• FileManager — the /files library: drag-and-drop upload, import-from-URL, folder navigation with breadcrumbs, grid/list views, search, multi-select, and bulk delete.
• FileDetail — the /files/[id] page: a Preview tab (image, video, audio, and PDF rendered inline) and a Details tab with an editable metadata form (title, description, tags, location, download filename), plus single delete.

The pieces

Install

buildpad add files-routes

buildpad add api-routes

The routes

Two files give you the whole module. They live under the (authenticated) route group, so they render inside the App Shell:

app/[lang]/(authenticated)/files/
├── page.tsx            # /files       — the FileManager library view
└── [id]/page.tsx       # /files/[id]  — the FileDetail preview + metadata view

"use client";
 
import React from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { FileManager } from '@/components/ui/file-manager';
 
export default function FilesPage() {
  const router = useLocaleRouter();
 
  return <FileManager onFileClick={(file) => router.push(`/files/${file.id}`)} />;
}

"use client";
 
import React, { use } from 'react';
import { useLocaleRouter } from '@/lib/i18n/navigation';
import { FileDetail } from '@/components/ui/file-manager';
 
export default function FileDetailPage({
  params,
}: {
  params: Promise<{ id: string }>;
}) {
  const { id } = use(params);
  const router = useLocaleRouter();
 
  return (
    <FileDetail
      id={id}
      onBack={() => router.push('/files')}
      onDeleted={() => router.push('/files')}
    />
  );
}

The data layer

Both screens are thin — all the work lives in two hooks you can reuse anywhere.

useFiles returns uploadFiles, fetchFiles, getFile, updateFile, deleteFile, deleteFiles, and importFromUrl. updateFile accepts the full editable metadata set:

const { updateFile } = useFiles();
 
await updateFile(fileId, {
  title: 'Cover image',
  description: 'Homepage hero',
  tags: ['marketing', 'hero'],
  location: 'HQ',
  filename_download: 'hero.png',
});

useFolders returns fetchFolders, createFolder, updateFolder, and deleteFolder. Scope a listing to a parent (pass null for root):

const { fetchFolders, createFolder } = useFolders();
 
const rootFolders = await fetchFolders({ parent: null });
const folder = await createFolder({ name: 'Campaigns', parent: null });

Preview behaviour

The Preview tab renders inline based on MIME type:

RBAC behaviour

• The gates come from usePermissions().canPerform(collection, action) on daas_files (override with filesCollection). Administrators pass every gate. The upload zone and New Folder need create; a folder’s Rename, a file’s Edit, Replace file and the metadata form need update; Delete (a file, a folder, the bulk bar) needs delete. Download and the preview are read functionality and are never gated.
• Until the permissions are known, no write control is drawn: no upload zone (so nothing to drop a file on), no New Folder, no folder menu, no Edit or Delete in a row menu, no bulk bar, no Delete or Replace on the detail page, and a disabled metadata form. The controls appear when the answer is in, so a user without a right does not see its button first. Reading does not wait: the library, the file and its preview load at once. A later refresh of the permissions (a renewed token, another scope) keeps the controls as they were until its answer is in.
• The gates only hide controls. The API enforces the same collection, so a hidden button is not the protection.

Prerequisites

• The module must live under your authenticated layout so DaaSProvider is above it — buildpad init generates this as app/[lang]/(authenticated)/ with a DaaSProviderWrapper. The hooks call your /api/files/*, /api/folders/*, and /api/assets/* proxy routes.
• No extra styling is needed: the components consume the design tokens through the Mantine theme. See the Styleguide for the token reference.

See the components live

Every state of the Files module is in the Files Storybook — FileManager, FileDetail, FilePreview, and the supporting pieces. Run it locally with pnpm --filter @buildpad/ui-files storybook (port 6009). The Live DaaS stories of FileManager and FileDetail connect to a real DaaS instance through the storybook-host proxy.