feat: implement backup management features and export functionality

Author: biggora

apps/nextjs/src/app/[locale]/manage/tools/backups/_components/backups-table.tsx

@@ -11,7 +11,7 @@ import { clientApi } from "@homarr/api/client";
 import { humanFileSize, useTimeAgo } from "@homarr/common";
 import { useConfirmModal } from "@homarr/modals";
 import { showErrorNotification, showSuccessNotification } from "@homarr/notifications";
-import { useI18n, useScopedI18n } from "@homarr/translation/client";
+import { useScopedI18n } from "@homarr/translation/client";
 import { Link, UserAvatar } from "@homarr/ui";
 import { useTranslatedMantineReactTable } from "@homarr/ui/hooks";
 
@@ -22,7 +22,6 @@ interface BackupsTableProps {
 }
 
 export const BackupsTable = ({ initialBackups }: BackupsTableProps) => {
-  const t = useI18n();
   const tBackup = useScopedI18n("backup");
 
   const utils = clientApi.useUtils();
@@ -72,19 +71,8 @@ export const BackupsTable = ({ initialBackups }: BackupsTableProps) => {
   }, []);
 
   const handleRefresh = useCallback(async () => {
-    try {
-      await utils.backup.list.invalidate();
-      showSuccessNotification({
-        title: t("common.success"),
-        message: "List refreshed",
-      });
-    } catch {
-      showErrorNotification({
-        title: t("common.error"),
-        message: "Failed to refresh",
-      });
-    }
-  }, [utils, t]);
+    await utils.backup.list.refetch();
+  }, [utils]);
 
   const columns: MRT_ColumnDef<BackupData>[] = [
     {

packages/backup/src/export/full-exporter.ts

@@ -7,6 +7,7 @@ import { createLogger } from "@homarr/core/infrastructure/logs";
 import type { Database } from "@homarr/db";
 import { apps, backups, medias, searchEngines, serverSettings } from "@homarr/db/schema";
 
+import packageJson from "../../../../package.json";
 import { backupEnv } from "../env";
 import { BACKUP_FORMAT_VERSION } from "../formats/json-format";
 import { createZipArchiveAsync } from "../formats/zip-format";
@@ -52,7 +53,7 @@ export class FullExporter {
     // Create metadata
     const metadata: BackupMetadata = {
       version: BACKUP_FORMAT_VERSION,
-      homarrVersion: process.env.VERSION ?? "unknown",
+      homarrVersion: packageJson.version,
       exportedAt: timestamp.toISOString(),
       exportedBy: options.userId ?? null,
       checksum,

packages/backup/src/formats/__tests__/json-format.spec.ts

@@ -9,6 +9,9 @@ import {
   parseJson,
 } from "../json-format";
 
+// Get the current Homarr version from formatEntityExport
+const getHomarrVersion = (): string => formatEntityExport("board", {}).homarrVersion;
+
 describe("BACKUP_FORMAT_VERSION", () => {
   it("should be a semantic version string", () => {
     expect(BACKUP_FORMAT_VERSION).toMatch(/^\d+\.\d+\.\d+$/);
@@ -27,6 +30,13 @@ describe("formatEntityExport", () => {
     expect(new Date(result.exportedAt).getTime()).toBeLessThanOrEqual(Date.now());
   });
 
+  it("should include homarrVersion from package.json", () => {
+    const data = { name: "test-board", items: [] };
+    const result = formatEntityExport("board", data);
+
+    expect(result.homarrVersion).toBe(getHomarrVersion());
+  });
+
   it("should set correct type for integration exports", () => {
     const data = { name: "test-integration", url: "http://example.com" };
     const result = formatEntityExport("integration", data);
@@ -47,6 +57,22 @@ describe("parseEntityExport", () => {
 
     const result = parseEntityExport<{ name: string }>(content);
 
+    // When homarrVersion is missing (legacy format), it's set to current package version
+    expect(result).toEqual({ ...exportData, homarrVersion: getHomarrVersion() });
+  });
+
+  it("should preserve homarrVersion when present", () => {
+    const exportData = {
+      version: "1.0.0",
+      homarrVersion: "1.2.3",
+      type: "board",
+      data: { name: "test" },
+      exportedAt: new Date().toISOString(),
+    };
+    const content = JSON.stringify(exportData);
+
+    const result = parseEntityExport<{ name: string }>(content);
+
     expect(result).toEqual(exportData);
   });
 

packages/backup/src/formats/json-format.ts

@@ -1,3 +1,4 @@
+import packageJson from "../../../../package.json";
 import type { EntityExport } from "../types";
 
 /**
@@ -11,6 +12,7 @@ export const BACKUP_FORMAT_VERSION = "1.0.0";
 export const formatEntityExport = <T>(type: "board" | "integration", data: T): EntityExport<T> => {
   return {
     version: BACKUP_FORMAT_VERSION,
+    homarrVersion: packageJson.version,
     exportedAt: new Date().toISOString(),
     type,
     data,
@@ -34,6 +36,11 @@ export const parseEntityExport = <T>(content: string): EntityExport<T> => {
     throw new Error("Invalid export format: missing required fields");
   }
 
+  // For backward compatibility, if homarrVersion is missing, use current version
+  if (!("homarrVersion" in parsed)) {
+    (parsed as EntityExport<T>).homarrVersion = packageJson.version;
+  }
+
   return parsed as EntityExport<T>;
 };
 

packages/backup/src/formats/zip-format.ts

@@ -2,6 +2,35 @@ import JSZip from "jszip";
 
 import type { BackupMetadata, FullBackupData, MediaFile } from "../types";
 
+/**
+ * Wrapper for data files with Homarr version
+ */
+interface VersionedData<T> {
+  homarrVersion: string;
+  data: T;
+}
+
+/**
+ * Helper to wrap data with version
+ */
+const wrapData = <T>(homarrVersion: string, itemData: T): VersionedData<T> => ({
+  homarrVersion,
+  data: itemData,
+});
+
+/**
+ * Helper to unwrap data, supporting both versioned and legacy formats
+ */
+const unwrapData = <T>(content: string): T => {
+  const parsed = JSON.parse(content) as Record<string, unknown> | VersionedData<unknown>;
+  // Check if data is in versioned format (has homarrVersion and data fields)
+  if (typeof parsed === "object" && "homarrVersion" in parsed && "data" in parsed) {
+    return (parsed as VersionedData<T>).data;
+  }
+  // Legacy format: return as-is
+  return parsed as T;
+};
+
 /**
  * Creates a ZIP archive buffer from backup data and media files
  */
@@ -15,16 +44,16 @@ export const createZipArchiveAsync = async (
   // Add metadata
   zip.file("metadata.json", JSON.stringify(metadata, null, 2));
 
-  // Add data files
-  zip.file("boards.json", JSON.stringify(data.boards, null, 2));
-  zip.file("integrations.json", JSON.stringify(data.integrations, null, 2));
-  zip.file("users.json", JSON.stringify(data.users, null, 2));
-  zip.file("groups.json", JSON.stringify(data.groups, null, 2));
-  zip.file("apps.json", JSON.stringify(data.apps, null, 2));
-  zip.file("searchEngines.json", JSON.stringify(data.searchEngines, null, 2));
+  // Add data files with version wrapper
+  zip.file("boards.json", JSON.stringify(wrapData(metadata.homarrVersion, data.boards), null, 2));
+  zip.file("integrations.json", JSON.stringify(wrapData(metadata.homarrVersion, data.integrations), null, 2));
+  zip.file("users.json", JSON.stringify(wrapData(metadata.homarrVersion, data.users), null, 2));
+  zip.file("groups.json", JSON.stringify(wrapData(metadata.homarrVersion, data.groups), null, 2));
+  zip.file("apps.json", JSON.stringify(wrapData(metadata.homarrVersion, data.apps), null, 2));
+  zip.file("searchEngines.json", JSON.stringify(wrapData(metadata.homarrVersion, data.searchEngines), null, 2));
 
   if (data.settings) {
-    zip.file("settings.json", JSON.stringify(data.settings, null, 2));
+    zip.file("settings.json", JSON.stringify(wrapData(metadata.homarrVersion, data.settings), null, 2));
   }
 
   // Add media files to media folder
@@ -68,16 +97,16 @@ export const extractZipArchiveAsync = async (
   const searchEnginesFile = zip.file("searchEngines.json");
 
   const data: FullBackupData = {
-    boards: boardsFile ? (JSON.parse(await boardsFile.async("string")) as FullBackupData["boards"]) : [],
+    boards: boardsFile ? unwrapData<FullBackupData["boards"]>(await boardsFile.async("string")) : [],
     integrations: integrationsFile
-      ? (JSON.parse(await integrationsFile.async("string")) as FullBackupData["integrations"])
+      ? unwrapData<FullBackupData["integrations"]>(await integrationsFile.async("string"))
       : [],
-    users: usersFile ? (JSON.parse(await usersFile.async("string")) as FullBackupData["users"]) : [],
-    groups: groupsFile ? (JSON.parse(await groupsFile.async("string")) as FullBackupData["groups"]) : [],
-    apps: appsFile ? (JSON.parse(await appsFile.async("string")) as FullBackupData["apps"]) : [],
-    settings: settingsFile ? (JSON.parse(await settingsFile.async("string")) as FullBackupData["settings"]) : null,
+    users: usersFile ? unwrapData<FullBackupData["users"]>(await usersFile.async("string")) : [],
+    groups: groupsFile ? unwrapData<FullBackupData["groups"]>(await groupsFile.async("string")) : [],
+    apps: appsFile ? unwrapData<FullBackupData["apps"]>(await appsFile.async("string")) : [],
+    settings: settingsFile ? unwrapData<FullBackupData["settings"]>(await settingsFile.async("string")) : null,
     searchEngines: searchEnginesFile
-      ? (JSON.parse(await searchEnginesFile.async("string")) as FullBackupData["searchEngines"])
+      ? unwrapData<FullBackupData["searchEngines"]>(await searchEnginesFile.async("string"))
       : [],
   };
 

packages/backup/src/types.ts

@@ -149,12 +149,17 @@ export interface BoardExportOptions {
   includeIntegrations?: boolean;
 }
 
+/**
+ * Wrapper for single entity export (board, integration)
+ */
 /**
  * Wrapper for single entity export (board, integration)
  */
 export interface EntityExport<T> {
   /** Version of the export format */
   version: string;
+  /** Version of Homarr that created the export */
+  homarrVersion: string;
   /** ISO timestamp of when export was created */
   exportedAt: string;
   /** Type of entity exported */