UI Integration

Apps can embed custom user interfaces directly into Lombok’s web interface, providing users with dashboards, administrative tools, custom file viewers, or any functionality that makes sense for your app. Your UI appears as a native part of Lombok, with seamless authentication and full access to storage APIs through the Lombok SDK.

The primary integration point is the sidebar menu. When users click your app’s menu item, Lombok loads your custom UI in the main content area. Your app receives authentication context automatically, so you can immediately start reading files, listing folders, or managing users without manual login flows.

This guide covers sidebar integration, building your app’s UI, using the Lombok SDK, and best practices for creating interfaces that feel native to the platform.

Sidebar Integration

Sidebar integration adds your app to Lombok’s main navigation menu, making it easily accessible to users. When enabled, your app appears as a menu item alongside built-in features like Files, Storage, and Settings.

How It Works

When a user clicks your app’s sidebar menu item:

1. Lombok loads your app’s HTML entrypoint in the main content area
2. Your app receives authentication context (current user, access tokens) automatically
3. Your frontend code can immediately call Lombok APIs through the SDK
4. The user sees your UI as if it were a built-in Lombok feature

From the user’s perspective, your app is just another part of Lombok. From your perspective, you’re building a standard web application with access to storage, users, and files through well-defined APIs.

Configuring Sidebar Integration

Enable sidebar integration in your config.json file using the ui object:

config.json (partial)

{
  "ui": {
    "sidebar": true,
    "sidebarLabel": "My App",
    "sidebarIcon": "icon.svg",
    "sidebarOrder": 100
  }
}

Configuration Options

sidebar

Type: boolean Description: Enable or disable the sidebar menu item. Set to true to add your app to the sidebar. Default: false

sidebarLabel

Type: string Description: Display name shown in the sidebar menu. Keep it short (1-2 words) for best fit. This is what users see when navigating to your app. Example: "File Processor", "Backups", "Media Library"

sidebarIcon

Type: string (optional) Description: Path to your app’s icon file, relative to your package root. The icon appears next to your app’s label in the sidebar. Recommended format: SVG or PNG at 24x24 pixels minimum. SVG is preferred for scaling and theming. Example: "icon.svg", "assets/sidebar-icon.png"

sidebarOrder

Type: number (optional) Description: Position in the sidebar menu. Lower numbers appear higher in the menu. Built-in Lombok features use orders 1-50, so use 100+ for custom apps to appear below built-in items. Default: 100 Example: 150 (appears after most apps), 75 (appears near built-in features)

Building Your App UI

Your app’s UI is a standard web application. You provide an HTML entrypoint, and Lombok loads it when users access your app. From there, you have full control over what users see and how they interact with your app.

Project Structure

A typical app UI consists of an HTML file, JavaScript/TypeScript code, and stylesheets:

my-app/
  config.json        # App configuration (see Configuration Guide)
  index.html         # Your app's main UI entrypoint
  app.js             # Your frontend code (or app.ts compiled to JS)
  styles.css         # Your app's styles
  icon.svg           # Sidebar icon

Your index.html is loaded in Lombok’s main content area when users click your sidebar menu item. From there, you can load additional scripts, stylesheets, or assets as needed.

Technologies

Use any modern web framework or vanilla JavaScript/TypeScript:

• React — Component-based UI with hooks for Lombok API calls
• Vue — Reactive data binding for storage and file management
• Svelte — Compiled components with minimal overhead
• Vanilla TypeScript — No framework, direct DOM manipulation and Lombok SDK calls

Choose the stack that matches your team’s expertise and your app’s complexity. Simple apps may need only vanilla JavaScript; complex dashboards benefit from frameworks.

Authentication

Authentication is handled automatically. When Lombok loads your app, it provides authentication context in the global lombok object. You don’t need to implement login flows, manage tokens, or handle session expiration — Lombok does this for you.

Your app’s frontend code can immediately start calling Lombok APIs:

// Available as soon as your app loads
const user = await lombok.getCurrentUser()
console.log(`Current user: ${user.username}`)

Lombok SDK

The Lombok SDK is available in your app’s browser context, providing JavaScript APIs for interacting with storage, files, folders, and users. All methods return Promises and handle authentication automatically.

SDK Methods

The SDK provides the following methods (examples shown conceptually — refer to the Lombok source code for complete API documentation):

User Management:

// Get the current authenticated user
const user = await lombok.getCurrentUser()
// Returns: { id, username, email, ... }

Folder Management:

// List all folders accessible to the current user
const folders = await lombok.listFolders()
// Returns: [{ id, name, path, ... }, ...]

// Get details for a specific folder
const folder = await lombok.getFolder(folderId)
// Returns: { id, name, path, files, ... }

File Operations:

// Read a file's contents
const content = await lombok.readFile(fileId)
// Returns: file content (blob, text, or JSON depending on file type)

// Write a file (create or update)
await lombok.writeFile(folderId, filename, content)
// Returns: { id, name, path, ... }

// Delete a file
await lombok.deleteFile(fileId)

Storage Information:

// Get storage usage and quotas
const storage = await lombok.getStorageInfo()
// Returns: { used, total, percentage, ... }

Usage Example

Here’s a simple example showing how to list folders and display them in your UI:

Using the Lombok SDK

// Initialize your app UI
async function initApp() {
  try {
    // Get current user
    const user = await lombok.getCurrentUser()
    document.getElementById('username').textContent = user.username

    // List folders
    const folders = await lombok.listFolders()
    const folderList = document.getElementById('folder-list')

    folders.forEach((folder) => {
      const li = document.createElement('li')
      li.textContent = `${folder.name} (${folder.files.length} files)`
      folderList.appendChild(li)
    })
  } catch (error) {
    console.error('Failed to initialize app:', error)
    // Show error message to user
  }
}

// Run when your app loads
initApp()

The SDK handles authentication tokens, request formatting, and error responses. Your code focuses on what your app does, not how it talks to Lombok.

Folder Sidebars

Coming Soon

Folder sidebars will allow apps to add custom panels when viewing specific folders. This feature is on the roadmap. See the Roadmap for status.

Folder sidebars are a planned feature that will let apps embed UI components into Lombok’s folder view. When a user opens a folder, your app could display custom metadata, previews, actions, or tools specific to that folder’s contents.

Potential use cases:

• Show photo metadata when viewing image folders
• Display media transcoding status in a video library folder
• Provide folder-specific backup controls
• Add custom actions (e.g., “Generate slideshow from these images”)

This feature is not yet available, but when implemented, it will use a configuration structure similar to sidebar integration. Check the roadmap or Discord for updates.

Best Practices

Match Lombok’s Visual Style

Lombok provides CSS variables for colors, typography, and spacing. Use these variables to make your app’s UI feel consistent with the rest of Lombok’s interface:

/* Use Lombok's CSS variables */
.my-button {
  background-color: var(--sl-color-accent);
  color: var(--sl-color-text);
  font-family: var(--sl-font);
  padding: var(--sl-spacing-1);
}

Check Lombok’s developer documentation or inspect the interface to discover available variables. When your app matches Lombok’s visual style, users perceive it as a native feature rather than a third-party add-on.

Handle Loading and Error States

Always show loading indicators when fetching data, and provide clear error messages when operations fail:

// Good: Show loading state
const folderList = document.getElementById('folder-list')
folderList.innerHTML = '<p>Loading folders...</p>'

try {
  const folders = await lombok.listFolders()
  // Render folders...
} catch (error) {
  folderList.innerHTML = '<p>Failed to load folders. Please try again.</p>'
  console.error(error)
}

Users expect feedback when clicking buttons or loading data. Don’t leave them staring at a blank screen or wondering if their action worked.

Test at Different Viewport Sizes

Your app may be viewed on desktop, tablet, or mobile devices. Test your UI at multiple viewport sizes and ensure key functionality remains usable:

• Use responsive CSS (flexbox, grid, media queries)
• Avoid fixed widths that break on small screens
• Ensure buttons and touch targets are large enough for mobile
• Consider mobile-first design if most users access Lombok on phones

Lombok’s interface is responsive, so your app should be too.

Keep Sidebar Icons Simple

Sidebar icons appear at small sizes (24x24 pixels), so keep them simple and recognizable:

• Use simple shapes and solid colors
• Avoid fine details that disappear when scaled down
• Test your icon at actual size in the sidebar
• Use SVG format for sharp rendering at any scale

A good sidebar icon is instantly recognizable even when you’re not looking directly at it. Think logos, not illustrations.

Next Steps

Now that you understand UI integration, explore other app platform capabilities:

• Workers — Add backend logic triggered by events or schedules in the Worker Scripts Guide
• Events & Tasks — Create asynchronous operations that users can monitor and approve in the Events & Tasks Documentation
• Configuration — Review all config.json options in the App Configuration Guide

Your app’s UI is just one integration point. Combine UI with workers and tasks to build complete, powerful applications on top of Lombok’s storage infrastructure.