fix: inject Tailwind CSS into client entry point (#1537)

Added a Vite plugin to automatically inject the Tailwind CSS import into
the `unraid-components.client.js` entry file, enhancing the integration
of Tailwind CSS within the application. This change improves the setup
for styling components consistently across the project.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added automated validation to ensure Tailwind CSS styles are correctly
included in the custom elements build output.

* **Chores**
* Updated the build process to include a CSS validation step after
manifest generation.
* Enhanced development build configuration to enable CSS source maps and
optimize Tailwind CSS injection into web components.
  * Extended CSS theme with new responsive breakpoint variables.
* Improved CSS class specificity in user profile, server state, and
update modal components for consistent styling.
* Removed redundant style blocks and global CSS imports from multiple
components to streamline styling and reduce duplication.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

.claude/settings.local.json

@@ -14,7 +14,31 @@
       "Bash(mv:*)",
       "Bash(ls:*)",
       "mcp__ide__getDiagnostics",
-      "Bash(pnpm --filter \"*connect*\" test connect-status-writer.service.spec)"
+      "Bash(pnpm --filter \"*connect*\" test connect-status-writer.service.spec)",
+      "Bash(pnpm storybook:*)",
+      "Bash(pnpm add:*)",
+      "Bash(pnpm install:*)",
+      "Bash(pkill:*)",
+      "Bash(true)",
+      "Bash(timeout 15 pnpm storybook)",
+      "WebFetch(domain:tailwindcss.com)",
+      "Bash(pnpm list:*)",
+      "Bash(pnpm remove:*)",
+      "WebFetch(domain:github.com)",
+      "mcp__browsermcp__browser_navigate",
+      "Bash(clear)",
+      "Bash(git log:*)",
+      "Bash(pnpm --filter ./unraid-ui build)",
+      "Bash(pnpm --filter @unraid/ui build)",
+      "Bash(pnpm --filter @unraid/web build)",
+      "Bash(python3:*)",
+      "Bash(pnpm tailwind:build:*)",
+      "WebFetch(domain:erangrin.github.io)",
+      "Bash(pnpm clean:*)",
+      "Bash(pnpm validate:css:*)",
+      "Bash(node:*)",
+      "Bash(rm:*)",
+      "Bash(pnpm run:*)"
     ]
   },
   "enableAllProjectMcpServers": false

CLAUDE.md

@@ -135,3 +135,8 @@ Enables GraphQL playground at `http://tower.local/graphql`
 - Place all mock declarations at the top level
 - Use factory functions for module mocks to avoid hoisting issues
 - Clear mocks between tests to ensure isolation
+
+## Development Memories
+
+- We are using tailwind v4 we do not need a tailwind config anymore 
+- always search the internet for tailwind v4 documentation when making tailwind related style changes

api/dev/configs/api.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.9.5",
+  "version": "4.10.0",
   "extraOrigins": [
     "https://google.com",
     "https://test.com"

api/dev/configs/connect.json

@@ -1,16 +1,12 @@
 {
-  "wanaccess": false,
-  "wanport": 0,
+  "wanaccess": true,
+  "wanport": 8443,
   "upnpEnabled": false,
-  "apikey": "",
-  "localApiKey": "",
-  "email": "",
-  "username": "",
-  "avatar": "",
-  "regWizTime": "",
-  "accesstoken": "",
-  "idtoken": "",
-  "refreshtoken": "",
-  "dynamicRemoteAccessType": "DISABLED",
-  "ssoSubIds": []
+  "apikey": "_______________________BIG_API_KEY_HERE_________________________",
+  "localApiKey": "_______________________LOCAL_API_KEY_HERE_________________________",
+  "email": "test@example.com",
+  "username": "zspearmint",
+  "avatar": "https://via.placeholder.com/200",
+  "regWizTime": "1611175408732_0951-1653-3509-FBA155FA23C0",
+  "dynamicRemoteAccessType": "DISABLED"
 }

api/generated-schema.graphql

@@ -247,6 +247,347 @@ A field whose value conforms to the standard URL format as specified in RFC3986:
 """
 scalar URL
 
+type DiskPartition {
+  """The name of the partition"""
+  name: String!
+
+  """The filesystem type of the partition"""
+  fsType: DiskFsType!
+
+  """The size of the partition in bytes"""
+  size: Float!
+}
+
+"""The type of filesystem on the disk partition"""
+enum DiskFsType {
+  XFS
+  BTRFS
+  VFAT
+  ZFS
+  EXT4
+  NTFS
+}
+
+type Disk implements Node {
+  id: PrefixedID!
+
+  """The device path of the disk (e.g. /dev/sdb)"""
+  device: String!
+
+  """The type of disk (e.g. SSD, HDD)"""
+  type: String!
+
+  """The model name of the disk"""
+  name: String!
+
+  """The manufacturer of the disk"""
+  vendor: String!
+
+  """The total size of the disk in bytes"""
+  size: Float!
+
+  """The number of bytes per sector"""
+  bytesPerSector: Float!
+
+  """The total number of cylinders on the disk"""
+  totalCylinders: Float!
+
+  """The total number of heads on the disk"""
+  totalHeads: Float!
+
+  """The total number of sectors on the disk"""
+  totalSectors: Float!
+
+  """The total number of tracks on the disk"""
+  totalTracks: Float!
+
+  """The number of tracks per cylinder"""
+  tracksPerCylinder: Float!
+
+  """The number of sectors per track"""
+  sectorsPerTrack: Float!
+
+  """The firmware revision of the disk"""
+  firmwareRevision: String!
+
+  """The serial number of the disk"""
+  serialNum: String!
+
+  """The interface type of the disk"""
+  interfaceType: DiskInterfaceType!
+
+  """The SMART status of the disk"""
+  smartStatus: DiskSmartStatus!
+
+  """The current temperature of the disk in Celsius"""
+  temperature: Float
+
+  """The partitions on the disk"""
+  partitions: [DiskPartition!]!
+}
+
+"""The type of interface the disk uses to connect to the system"""
+enum DiskInterfaceType {
+  SAS
+  SATA
+  USB
+  PCIE
+  UNKNOWN
+}
+
+"""
+The SMART (Self-Monitoring, Analysis and Reporting Technology) status of the disk
+"""
+enum DiskSmartStatus {
+  OK
+  UNKNOWN
+}
+
+type KeyFile {
+  location: String
+  contents: String
+}
+
+type Registration implements Node {
+  id: PrefixedID!
+  type: registrationType
+  keyFile: KeyFile
+  state: RegistrationState
+  expiration: String
+  updateExpiration: String
+}
+
+enum registrationType {
+  BASIC
+  PLUS
+  PRO
+  STARTER
+  UNLEASHED
+  LIFETIME
+  INVALID
+  TRIAL
+}
+
+enum RegistrationState {
+  TRIAL
+  BASIC
+  PLUS
+  PRO
+  STARTER
+  UNLEASHED
+  LIFETIME
+  EEXPIRED
+  EGUID
+  EGUID1
+  ETRIAL
+  ENOKEYFILE
+  ENOKEYFILE1
+  ENOKEYFILE2
+  ENOFLASH
+  ENOFLASH1
+  ENOFLASH2
+  ENOFLASH3
+  ENOFLASH4
+  ENOFLASH5
+  ENOFLASH6
+  ENOFLASH7
+  EBLACKLISTED
+  EBLACKLISTED1
+  EBLACKLISTED2
+  ENOCONN
+}
+
+type Vars implements Node {
+  id: PrefixedID!
+
+  """Unraid version"""
+  version: String
+  maxArraysz: Int
+  maxCachesz: Int
+
+  """Machine hostname"""
+  name: String
+  timeZone: String
+  comment: String
+  security: String
+  workgroup: String
+  domain: String
+  domainShort: String
+  hideDotFiles: Boolean
+  localMaster: Boolean
+  enableFruit: String
+
+  """Should a NTP server be used for time sync?"""
+  useNtp: Boolean
+
+  """NTP Server 1"""
+  ntpServer1: String
+
+  """NTP Server 2"""
+  ntpServer2: String
+
+  """NTP Server 3"""
+  ntpServer3: String
+
+  """NTP Server 4"""
+  ntpServer4: String
+  domainLogin: String
+  sysModel: String
+  sysArraySlots: Int
+  sysCacheSlots: Int
+  sysFlashSlots: Int
+  useSsl: Boolean
+
+  """Port for the webui via HTTP"""
+  port: Int
+
+  """Port for the webui via HTTPS"""
+  portssl: Int
+  localTld: String
+  bindMgt: Boolean
+
+  """Should telnet be enabled?"""
+  useTelnet: Boolean
+  porttelnet: Int
+  useSsh: Boolean
+  portssh: Int
+  startPage: String
+  startArray: Boolean
+  spindownDelay: String
+  queueDepth: String
+  spinupGroups: Boolean
+  defaultFormat: String
+  defaultFsType: String
+  shutdownTimeout: Int
+  luksKeyfile: String
+  pollAttributes: String
+  pollAttributesDefault: String
+  pollAttributesStatus: String
+  nrRequests: Int
+  nrRequestsDefault: Int
+  nrRequestsStatus: String
+  mdNumStripes: Int
+  mdNumStripesDefault: Int
+  mdNumStripesStatus: String
+  mdSyncWindow: Int
+  mdSyncWindowDefault: Int
+  mdSyncWindowStatus: String
+  mdSyncThresh: Int
+  mdSyncThreshDefault: Int
+  mdSyncThreshStatus: String
+  mdWriteMethod: Int
+  mdWriteMethodDefault: String
+  mdWriteMethodStatus: String
+  shareDisk: String
+  shareUser: String
+  shareUserInclude: String
+  shareUserExclude: String
+  shareSmbEnabled: Boolean
+  shareNfsEnabled: Boolean
+  shareAfpEnabled: Boolean
+  shareInitialOwner: String
+  shareInitialGroup: String
+  shareCacheEnabled: Boolean
+  shareCacheFloor: String
+  shareMoverSchedule: String
+  shareMoverLogging: Boolean
+  fuseRemember: String
+  fuseRememberDefault: String
+  fuseRememberStatus: String
+  fuseDirectio: String
+  fuseDirectioDefault: String
+  fuseDirectioStatus: String
+  shareAvahiEnabled: Boolean
+  shareAvahiSmbName: String
+  shareAvahiSmbModel: String
+  shareAvahiAfpName: String
+  shareAvahiAfpModel: String
+  safeMode: Boolean
+  startMode: String
+  configValid: Boolean
+  configError: ConfigErrorState
+  joinStatus: String
+  deviceCount: Int
+  flashGuid: String
+  flashProduct: String
+  flashVendor: String
+  regCheck: String
+  regFile: String
+  regGuid: String
+  regTy: registrationType
+  regState: RegistrationState
+
+  """Registration owner"""
+  regTo: String
+  regTm: String
+  regTm2: String
+  regGen: String
+  sbName: String
+  sbVersion: String
+  sbUpdated: String
+  sbEvents: Int
+  sbState: String
+  sbClean: Boolean
+  sbSynced: Int
+  sbSyncErrs: Int
+  sbSynced2: Int
+  sbSyncExit: String
+  sbNumDisks: Int
+  mdColor: String
+  mdNumDisks: Int
+  mdNumDisabled: Int
+  mdNumInvalid: Int
+  mdNumMissing: Int
+  mdNumNew: Int
+  mdNumErased: Int
+  mdResync: Int
+  mdResyncCorr: String
+  mdResyncPos: String
+  mdResyncDb: String
+  mdResyncDt: String
+  mdResyncAction: String
+  mdResyncSize: Int
+  mdState: String
+  mdVersion: String
+  cacheNumDevices: Int
+  cacheSbNumDisks: Int
+  fsState: String
+
+  """Human friendly string of array events happening"""
+  fsProgress: String
+
+  """
+  Percentage from 0 - 100 while upgrading a disk or swapping parity drives
+  """
+  fsCopyPrcnt: Int
+  fsNumMounted: Int
+  fsNumUnmountable: Int
+  fsUnmountableMask: String
+
+  """Total amount of user shares"""
+  shareCount: Int
+
+  """Total amount shares with SMB enabled"""
+  shareSmbCount: Int
+
+  """Total amount shares with NFS enabled"""
+  shareNfsCount: Int
+
+  """Total amount shares with AFP enabled"""
+  shareAfpCount: Int
+  shareMoverActive: Boolean
+  csrfToken: String
+}
+
+"""Possible error states for configuration"""
+enum ConfigErrorState {
+  UNKNOWN_ERROR
+  INELIGIBLE
+  INVALID
+  NO_KEY_SERVER
+  WITHDRAWN
+}
+
 type Permission {
   resource: Resource!
   actions: [String!]!
@@ -620,102 +961,6 @@ enum ThemeName {
   white
 }
 
-type DiskPartition {
-  """The name of the partition"""
-  name: String!
-
-  """The filesystem type of the partition"""
-  fsType: DiskFsType!
-
-  """The size of the partition in bytes"""
-  size: Float!
-}
-
-"""The type of filesystem on the disk partition"""
-enum DiskFsType {
-  XFS
-  BTRFS
-  VFAT
-  ZFS
-  EXT4
-  NTFS
-}
-
-type Disk implements Node {
-  id: PrefixedID!
-
-  """The device path of the disk (e.g. /dev/sdb)"""
-  device: String!
-
-  """The type of disk (e.g. SSD, HDD)"""
-  type: String!
-
-  """The model name of the disk"""
-  name: String!
-
-  """The manufacturer of the disk"""
-  vendor: String!
-
-  """The total size of the disk in bytes"""
-  size: Float!
-
-  """The number of bytes per sector"""
-  bytesPerSector: Float!
-
-  """The total number of cylinders on the disk"""
-  totalCylinders: Float!
-
-  """The total number of heads on the disk"""
-  totalHeads: Float!
-
-  """The total number of sectors on the disk"""
-  totalSectors: Float!
-
-  """The total number of tracks on the disk"""
-  totalTracks: Float!
-
-  """The number of tracks per cylinder"""
-  tracksPerCylinder: Float!
-
-  """The number of sectors per track"""
-  sectorsPerTrack: Float!
-
-  """The firmware revision of the disk"""
-  firmwareRevision: String!
-
-  """The serial number of the disk"""
-  serialNum: String!
-
-  """The interface type of the disk"""
-  interfaceType: DiskInterfaceType!
-
-  """The SMART status of the disk"""
-  smartStatus: DiskSmartStatus!
-
-  """The current temperature of the disk in Celsius"""
-  temperature: Float
-
-  """The partitions on the disk"""
-  partitions: [DiskPartition!]!
-}
-
-"""The type of interface the disk uses to connect to the system"""
-enum DiskInterfaceType {
-  SAS
-  SATA
-  USB
-  PCIE
-  UNKNOWN
-}
-
-"""
-The SMART (Self-Monitoring, Analysis and Reporting Technology) status of the disk
-"""
-enum DiskSmartStatus {
-  OK
-  UNKNOWN
-}
-
 type InfoApps implements Node {
   id: PrefixedID!
 
@@ -1106,60 +1351,6 @@ type Owner {
   avatar: String!
 }
 
-type KeyFile {
-  location: String
-  contents: String
-}
-
-type Registration implements Node {
-  id: PrefixedID!
-  type: registrationType
-  keyFile: KeyFile
-  state: RegistrationState
-  expiration: String
-  updateExpiration: String
-}
-
-enum registrationType {
-  BASIC
-  PLUS
-  PRO
-  STARTER
-  UNLEASHED
-  LIFETIME
-  INVALID
-  TRIAL
-}
-
-enum RegistrationState {
-  TRIAL
-  BASIC
-  PLUS
-  PRO
-  STARTER
-  UNLEASHED
-  LIFETIME
-  EEXPIRED
-  EGUID
-  EGUID1
-  ETRIAL
-  ENOKEYFILE
-  ENOKEYFILE1
-  ENOKEYFILE2
-  ENOFLASH
-  ENOFLASH1
-  ENOFLASH2
-  ENOFLASH3
-  ENOFLASH4
-  ENOFLASH5
-  ENOFLASH6
-  ENOFLASH7
-  EBLACKLISTED
-  EBLACKLISTED1
-  EBLACKLISTED2
-  ENOCONN
-}
-
 type ProfileModel implements Node {
   id: PrefixedID!
   username: String!
@@ -1225,197 +1416,6 @@ type Settings implements Node {
   api: ApiConfig!
 }
 
-type Vars implements Node {
-  id: PrefixedID!
-
-  """Unraid version"""
-  version: String
-  maxArraysz: Int
-  maxCachesz: Int
-
-  """Machine hostname"""
-  name: String
-  timeZone: String
-  comment: String
-  security: String
-  workgroup: String
-  domain: String
-  domainShort: String
-  hideDotFiles: Boolean
-  localMaster: Boolean
-  enableFruit: String
-
-  """Should a NTP server be used for time sync?"""
-  useNtp: Boolean
-
-  """NTP Server 1"""
-  ntpServer1: String
-
-  """NTP Server 2"""
-  ntpServer2: String
-
-  """NTP Server 3"""
-  ntpServer3: String
-
-  """NTP Server 4"""
-  ntpServer4: String
-  domainLogin: String
-  sysModel: String
-  sysArraySlots: Int
-  sysCacheSlots: Int
-  sysFlashSlots: Int
-  useSsl: Boolean
-
-  """Port for the webui via HTTP"""
-  port: Int
-
-  """Port for the webui via HTTPS"""
-  portssl: Int
-  localTld: String
-  bindMgt: Boolean
-
-  """Should telnet be enabled?"""
-  useTelnet: Boolean
-  porttelnet: Int
-  useSsh: Boolean
-  portssh: Int
-  startPage: String
-  startArray: Boolean
-  spindownDelay: String
-  queueDepth: String
-  spinupGroups: Boolean
-  defaultFormat: String
-  defaultFsType: String
-  shutdownTimeout: Int
-  luksKeyfile: String
-  pollAttributes: String
-  pollAttributesDefault: String
-  pollAttributesStatus: String
-  nrRequests: Int
-  nrRequestsDefault: Int
-  nrRequestsStatus: String
-  mdNumStripes: Int
-  mdNumStripesDefault: Int
-  mdNumStripesStatus: String
-  mdSyncWindow: Int
-  mdSyncWindowDefault: Int
-  mdSyncWindowStatus: String
-  mdSyncThresh: Int
-  mdSyncThreshDefault: Int
-  mdSyncThreshStatus: String
-  mdWriteMethod: Int
-  mdWriteMethodDefault: String
-  mdWriteMethodStatus: String
-  shareDisk: String
-  shareUser: String
-  shareUserInclude: String
-  shareUserExclude: String
-  shareSmbEnabled: Boolean
-  shareNfsEnabled: Boolean
-  shareAfpEnabled: Boolean
-  shareInitialOwner: String
-  shareInitialGroup: String
-  shareCacheEnabled: Boolean
-  shareCacheFloor: String
-  shareMoverSchedule: String
-  shareMoverLogging: Boolean
-  fuseRemember: String
-  fuseRememberDefault: String
-  fuseRememberStatus: String
-  fuseDirectio: String
-  fuseDirectioDefault: String
-  fuseDirectioStatus: String
-  shareAvahiEnabled: Boolean
-  shareAvahiSmbName: String
-  shareAvahiSmbModel: String
-  shareAvahiAfpName: String
-  shareAvahiAfpModel: String
-  safeMode: Boolean
-  startMode: String
-  configValid: Boolean
-  configError: ConfigErrorState
-  joinStatus: String
-  deviceCount: Int
-  flashGuid: String
-  flashProduct: String
-  flashVendor: String
-  regCheck: String
-  regFile: String
-  regGuid: String
-  regTy: registrationType
-  regState: RegistrationState
-
-  """Registration owner"""
-  regTo: String
-  regTm: String
-  regTm2: String
-  regGen: String
-  sbName: String
-  sbVersion: String
-  sbUpdated: String
-  sbEvents: Int
-  sbState: String
-  sbClean: Boolean
-  sbSynced: Int
-  sbSyncErrs: Int
-  sbSynced2: Int
-  sbSyncExit: String
-  sbNumDisks: Int
-  mdColor: String
-  mdNumDisks: Int
-  mdNumDisabled: Int
-  mdNumInvalid: Int
-  mdNumMissing: Int
-  mdNumNew: Int
-  mdNumErased: Int
-  mdResync: Int
-  mdResyncCorr: String
-  mdResyncPos: String
-  mdResyncDb: String
-  mdResyncDt: String
-  mdResyncAction: String
-  mdResyncSize: Int
-  mdState: String
-  mdVersion: String
-  cacheNumDevices: Int
-  cacheSbNumDisks: Int
-  fsState: String
-
-  """Human friendly string of array events happening"""
-  fsProgress: String
-
-  """
-  Percentage from 0 - 100 while upgrading a disk or swapping parity drives
-  """
-  fsCopyPrcnt: Int
-  fsNumMounted: Int
-  fsNumUnmountable: Int
-  fsUnmountableMask: String
-
-  """Total amount of user shares"""
-  shareCount: Int
-
-  """Total amount shares with SMB enabled"""
-  shareSmbCount: Int
-
-  """Total amount shares with NFS enabled"""
-  shareNfsCount: Int
-
-  """Total amount shares with AFP enabled"""
-  shareAfpCount: Int
-  shareMoverActive: Boolean
-  csrfToken: String
-}
-
-"""Possible error states for configuration"""
-enum ConfigErrorState {
-  UNKNOWN_ERROR
-  INELIGIBLE
-  INVALID
-  NO_KEY_SERVER
-  WITHDRAWN
-}
-
 type VmDomain implements Node {
   """The unique identifier for the vm (uuid)"""
   id: PrefixedID!

api/src/__test__/config/api-config.test.ts

@@ -1,137 +0,0 @@
-import { ConfigService } from '@nestjs/config';
-
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { ApiConfigPersistence } from '@app/unraid-api/config/api-config.module.js';
-import { ConfigPersistenceHelper } from '@app/unraid-api/config/persistence.helper.js';
-
-describe('ApiConfigPersistence', () => {
-    let service: ApiConfigPersistence;
-    let configService: ConfigService;
-    let persistenceHelper: ConfigPersistenceHelper;
-
-    beforeEach(() => {
-        configService = {
-            get: vi.fn(),
-            set: vi.fn(),
-        } as any;
-
-        persistenceHelper = {} as ConfigPersistenceHelper;
-        service = new ApiConfigPersistence(configService, persistenceHelper);
-    });
-
-    describe('convertLegacyConfig', () => {
-        it('should migrate sandbox from string "yes" to boolean true', () => {
-            const legacyConfig = {
-                local: { sandbox: 'yes' },
-                api: { extraOrigins: '' },
-                remote: { ssoSubIds: '' },
-            };
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.sandbox).toBe(true);
-        });
-
-        it('should migrate sandbox from string "no" to boolean false', () => {
-            const legacyConfig = {
-                local: { sandbox: 'no' },
-                api: { extraOrigins: '' },
-                remote: { ssoSubIds: '' },
-            };
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.sandbox).toBe(false);
-        });
-
-        it('should migrate extraOrigins from comma-separated string to array', () => {
-            const legacyConfig = {
-                local: { sandbox: 'no' },
-                api: { extraOrigins: 'https://example.com,https://test.com' },
-                remote: { ssoSubIds: '' },
-            };
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.extraOrigins).toEqual(['https://example.com', 'https://test.com']);
-        });
-
-        it('should filter out non-HTTP origins from extraOrigins', () => {
-            const legacyConfig = {
-                local: { sandbox: 'no' },
-                api: {
-                    extraOrigins: 'https://example.com,invalid-origin,http://test.com,ftp://bad.com',
-                },
-                remote: { ssoSubIds: '' },
-            };
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.extraOrigins).toEqual(['https://example.com', 'http://test.com']);
-        });
-
-        it('should handle empty extraOrigins string', () => {
-            const legacyConfig = {
-                local: { sandbox: 'no' },
-                api: { extraOrigins: '' },
-                remote: { ssoSubIds: '' },
-            };
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.extraOrigins).toEqual([]);
-        });
-
-        it('should migrate ssoSubIds from comma-separated string to array', () => {
-            const legacyConfig = {
-                local: { sandbox: 'no' },
-                api: { extraOrigins: '' },
-                remote: { ssoSubIds: 'user1,user2,user3' },
-            };
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.ssoSubIds).toEqual(['user1', 'user2', 'user3']);
-        });
-
-        it('should handle empty ssoSubIds string', () => {
-            const legacyConfig = {
-                local: { sandbox: 'no' },
-                api: { extraOrigins: '' },
-                remote: { ssoSubIds: '' },
-            };
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.ssoSubIds).toEqual([]);
-        });
-
-        it('should handle undefined config sections', () => {
-            const legacyConfig = {};
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.sandbox).toBe(false);
-            expect(result.extraOrigins).toEqual([]);
-            expect(result.ssoSubIds).toEqual([]);
-        });
-
-        it('should handle complete migration with all fields', () => {
-            const legacyConfig = {
-                local: { sandbox: 'yes' },
-                api: { extraOrigins: 'https://app1.example.com,https://app2.example.com' },
-                remote: { ssoSubIds: 'sub1,sub2,sub3' },
-            };
-
-            const result = service.convertLegacyConfig(legacyConfig);
-
-            expect(result.sandbox).toBe(true);
-            expect(result.extraOrigins).toEqual([
-                'https://app1.example.com',
-                'https://app2.example.com',
-            ]);
-            expect(result.ssoSubIds).toEqual(['sub1', 'sub2', 'sub3']);
-        });
-    });
-});

api/src/store/listeners/config-listener.ts

@@ -1,4 +1,4 @@
-import { writeFileSync } from 'fs';
+import { writeFile } from 'fs/promises';
 
 import type { ConfigType } from '@app/core/utils/files/config-file-normalizer.js';
 import { logger } from '@app/core/log.js';
@@ -17,6 +17,6 @@ export const enableConfigFileListener = (mode: ConfigType) => () =>
             const writeableConfig = getWriteableConfig(config, mode);
             const serializedConfig = safelySerializeObjectToIni(writeableConfig);
             logger.debug('Writing updated config to %s', pathToWrite);
-            writeFileSync(pathToWrite, serializedConfig);
+            await writeFile(pathToWrite, serializedConfig);
         },
     });

api/src/store/modules/config.ts

@@ -1,6 +1,5 @@
 import { F_OK } from 'constants';
-import { writeFileSync } from 'fs';
-import { access } from 'fs/promises';
+import { access, writeFile } from 'fs/promises';
 
 import type { PayloadAction } from '@reduxjs/toolkit';
 import { createAsyncThunk, createSlice, isAnyOf } from '@reduxjs/toolkit';
@@ -140,7 +139,7 @@ export const loadConfigFile = createAsyncThunk<
         const newConfig = getWriteableConfig(initialState, 'flash');
         newConfig.remote.wanaccess = 'no';
         const serializedConfig = safelySerializeObjectToIni(newConfig);
-        writeFileSync(getState().paths['myservers-config'], serializedConfig);
+        await writeFile(getState().paths['myservers-config'], serializedConfig);
         return rejectWithValue({
             type: CONFIG_LOAD_ERROR.CONFIG_CORRUPTED,
             error: error instanceof Error ? error : new Error('Unknown Error'),

api/src/unraid-api/cli/pm2.service.ts

@@ -1,11 +1,11 @@
 import { Injectable } from '@nestjs/common';
-import { existsSync } from 'node:fs';
 import { mkdir, rm } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import type { Options, Result, ResultPromise } from 'execa';
 import { execa, ExecaError } from 'execa';
 
+import { fileExists } from '@app/core/utils/files/file-exists.js';
 import { LOGS_DIR, PM2_HOME, PM2_PATH } from '@app/environment.js';
 import { LogService } from '@app/unraid-api/cli/log.service.js';
 
@@ -90,7 +90,7 @@ export class PM2Service {
     }
 
     async deletePm2Home() {
-        if (existsSync(PM2_HOME) && existsSync(join(PM2_HOME, 'pm2.log'))) {
+        if ((await fileExists(PM2_HOME)) && (await fileExists(join(PM2_HOME, 'pm2.log')))) {
             await rm(PM2_HOME, { recursive: true, force: true });
             this.logger.trace('PM2 home directory cleared.');
         } else {

api/src/unraid-api/config/api-config.module.ts

@@ -1,14 +1,12 @@
 import { Injectable, Logger, Module } from '@nestjs/common';
 import { ConfigService, registerAs } from '@nestjs/config';
+import path from 'path';
 
 import type { ApiConfig } from '@unraid/shared/services/api-config.js';
+import { ConfigFilePersister } from '@unraid/shared/services/config-file.js';
 import { csvStringToArray } from '@unraid/shared/util/data.js';
-import { fileExists } from '@unraid/shared/util/file.js';
-import { bufferTime } from 'rxjs/operators';
 
-import { API_VERSION } from '@app/environment.js';
-import { ApiStateConfig } from '@app/unraid-api/config/factory/api-state.model.js';
-import { ConfigPersistenceHelper } from '@app/unraid-api/config/persistence.helper.js';
+import { API_VERSION, PATHS_CONFIG_MODULES } from '@app/environment.js';
 
 export { type ApiConfig };
 
@@ -22,123 +20,72 @@ const createDefaultConfig = (): ApiConfig => ({
     plugins: [],
 });
 
-export const persistApiConfig = async (config: ApiConfig) => {
-    const apiConfig = new ApiStateConfig<ApiConfig>(
-        {
-            name: 'api',
-            defaultConfig: config,
-            parse: (data) => data as ApiConfig,
-        },
-        new ConfigPersistenceHelper()
-    );
-    return await apiConfig.persist(config);
-};
-
+/**
+ * Simple file-based config loading for plugin discovery (outside of nestjs DI container).
+ * This avoids complex DI container instantiation during module loading.
+ */
 export const loadApiConfig = async () => {
+    const defaultConfig = createDefaultConfig();
+    const apiHandler = new ApiConfigPersistence(new ConfigService()).getFileHandler();
+
+    let diskConfig: Partial<ApiConfig> = {};
     try {
-        const defaultConfig = createDefaultConfig();
-        const apiConfig = new ApiStateConfig<ApiConfig>(
-            {
-                name: 'api',
-                defaultConfig,
-                parse: (data) => data as ApiConfig,
-            },
-            new ConfigPersistenceHelper()
-        );
-
-        let diskConfig: ApiConfig | undefined;
-        try {
-            diskConfig = await apiConfig.parseConfig();
-        } catch (error) {
-            logger.error('Failed to load API config from disk, using defaults:', error);
-            diskConfig = undefined;
-
-            // Try to overwrite the invalid config with defaults to fix the issue
-            try {
-                const configToWrite = {
-                    ...defaultConfig,
-                    version: API_VERSION,
-                };
-
-                const writeSuccess = await apiConfig.persist(configToWrite);
-                if (writeSuccess) {
-                    logger.log('Successfully overwrote invalid config file with defaults.');
-                } else {
-                    logger.error(
-                        'Failed to overwrite invalid config file. Continuing with defaults in memory only.'
-                    );
-                }
-            } catch (persistError) {
-                logger.error('Error during config file repair:', persistError);
-            }
-        }
-
-        return {
-            ...defaultConfig,
-            ...diskConfig,
-            version: API_VERSION,
-        };
-    } catch (outerError) {
-        // This should never happen, but ensures the config factory never throws
-        logger.error('Critical error in loadApiConfig, using minimal defaults:', outerError);
-        return createDefaultConfig();
+        diskConfig = await apiHandler.loadConfig();
+    } catch (error) {
+        logger.warn('Failed to load API config from disk:', error);
     }
+
+    return {
+        ...defaultConfig,
+        ...diskConfig,
+        // diskConfig's version may be older, but we still want to use the correct version
+        version: API_VERSION,
+    };
 };
 
 /**
  * Loads the API config from disk. If not found, returns the default config, but does not persist it.
+ * This is used in the root config module to register the api config.
  */
 export const apiConfig = registerAs<ApiConfig>('api', loadApiConfig);
 
 @Injectable()
-export class ApiConfigPersistence {
-    private configModel: ApiStateConfig<ApiConfig>;
-    private logger = new Logger(ApiConfigPersistence.name);
-    get filePath() {
-        return this.configModel.filePath;
-    }
-    get config() {
-        return this.configService.getOrThrow('api');
+export class ApiConfigPersistence extends ConfigFilePersister<ApiConfig> {
+    constructor(configService: ConfigService) {
+        super(configService);
     }
 
-    constructor(
-        private readonly configService: ConfigService,
-        private readonly persistenceHelper: ConfigPersistenceHelper
-    ) {
-        this.configModel = new ApiStateConfig<ApiConfig>(
-            {
-                name: 'api',
-                defaultConfig: createDefaultConfig(),
-                parse: (data) => data as ApiConfig,
-            },
-            this.persistenceHelper
-        );
+    fileName(): string {
+        return 'api.json';
     }
 
-    async onModuleInit() {
-        try {
-            if (!(await fileExists(this.filePath))) {
-                this.migrateFromMyServersConfig();
-            }
-            await this.persistenceHelper.persistIfChanged(this.filePath, this.config);
-            this.configService.changes$.pipe(bufferTime(25)).subscribe({
-                next: async (changes) => {
-                    if (changes.some((change) => change.path.startsWith('api'))) {
-                        this.logger.verbose(`API Config changed ${JSON.stringify(changes)}`);
-                        try {
-                            await this.persistenceHelper.persistIfChanged(this.filePath, this.config);
-                        } catch (persistError) {
-                            this.logger.error('Error persisting config changes:', persistError);
-                        }
-                    }
-                },
-                error: (err) => {
-                    this.logger.error('Error receiving config changes:', err);
-                },
-            });
-        } catch (error) {
-            this.logger.error('Error during API config module initialization:', error);
-        }
+    configKey(): string {
+        return 'api';
+    }
+
+    /**
+     * @override
+     * Since the api config is read outside of the nestjs DI container,
+     * we need to provide an explicit path instead of relying on the
+     * default prefix from the configService.
+     *
+     * @returns The path to the api config file
+     */
+    configPath(): string {
+        return path.join(PATHS_CONFIG_MODULES, this.fileName());
+    }
+
+    defaultConfig(): ApiConfig {
+        return createDefaultConfig();
+    }
+
+    async migrateConfig(): Promise<ApiConfig> {
+        const legacyConfig = this.configService.get('store.config', {});
+        const migrated = this.convertLegacyConfig(legacyConfig);
+        return {
+            ...this.defaultConfig(),
+            ...migrated,
+        };
     }
 
     convertLegacyConfig(
@@ -156,18 +103,11 @@ export class ApiConfigPersistence {
             ssoSubIds: csvStringToArray(config?.remote?.ssoSubIds ?? ''),
         };
     }
-
-    migrateFromMyServersConfig() {
-        const legacyConfig = this.configService.get('store.config', {});
-        const { sandbox, extraOrigins, ssoSubIds } = this.convertLegacyConfig(legacyConfig);
-        this.configService.set('api.sandbox', sandbox);
-        this.configService.set('api.extraOrigins', extraOrigins);
-        this.configService.set('api.ssoSubIds', ssoSubIds);
-    }
 }
 
 // apiConfig should be registered in root config in app.module.ts, not here.
 @Module({
-    providers: [ApiConfigPersistence, ConfigPersistenceHelper],
+    providers: [ApiConfigPersistence],
+    exports: [ApiConfigPersistence],
 })
 export class ApiConfigModule {}

api/src/unraid-api/config/api-config.test.ts

@@ -4,14 +4,12 @@ import { beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { fileExists } from '@app/core/utils/files/file-exists.js';
 import { ApiConfigPersistence, loadApiConfig } from '@app/unraid-api/config/api-config.module.js';
-import { ConfigPersistenceHelper } from '@app/unraid-api/config/persistence.helper.js';
 
-// Mock the core file-exists utility used by ApiStateConfig
+// Mock file utilities
 vi.mock('@app/core/utils/files/file-exists.js', () => ({
     fileExists: vi.fn(),
 }));
 
-// Mock the shared file-exists utility used by ConfigPersistenceHelper
 vi.mock('@unraid/shared/util/file.js', () => ({
     fileExists: vi.fn(),
 }));
@@ -25,16 +23,56 @@ vi.mock('fs/promises', () => ({
 describe('ApiConfigPersistence', () => {
     let service: ApiConfigPersistence;
     let configService: ConfigService;
-    let persistenceHelper: ConfigPersistenceHelper;
 
     beforeEach(() => {
         configService = {
             get: vi.fn(),
             set: vi.fn(),
+            getOrThrow: vi.fn().mockReturnValue('test-config-path'),
         } as any;
 
-        persistenceHelper = {} as ConfigPersistenceHelper;
-        service = new ApiConfigPersistence(configService, persistenceHelper);
+        service = new ApiConfigPersistence(configService);
+    });
+
+    describe('required ConfigFilePersister methods', () => {
+        it('should return correct file name', () => {
+            expect(service.fileName()).toBe('api.json');
+        });
+
+        it('should return correct config key', () => {
+            expect(service.configKey()).toBe('api');
+        });
+
+        it('should return default config', () => {
+            const defaultConfig = service.defaultConfig();
+            expect(defaultConfig).toEqual({
+                version: expect.any(String),
+                extraOrigins: [],
+                sandbox: false,
+                ssoSubIds: [],
+                plugins: [],
+            });
+        });
+
+        it('should migrate config from legacy format', async () => {
+            const mockLegacyConfig = {
+                local: { sandbox: 'yes' },
+                api: { extraOrigins: 'https://example.com,https://test.com' },
+                remote: { ssoSubIds: 'sub1,sub2' },
+            };
+
+            vi.mocked(configService.get).mockReturnValue(mockLegacyConfig);
+
+            const result = await service.migrateConfig();
+
+            expect(result).toEqual({
+                version: expect.any(String),
+                extraOrigins: ['https://example.com', 'https://test.com'],
+                sandbox: true,
+                ssoSubIds: ['sub1', 'sub2'],
+                plugins: [],
+            });
+        });
     });
 
     describe('convertLegacyConfig', () => {
@@ -154,23 +192,11 @@ describe('ApiConfigPersistence', () => {
 });
 
 describe('loadApiConfig', () => {
-    let readFile: any;
-    let writeFile: any;
-
     beforeEach(async () => {
         vi.clearAllMocks();
-        // Reset modules to ensure fresh imports
-        vi.resetModules();
-
-        // Get mocked functions
-        const fsMocks = await import('fs/promises');
-        readFile = fsMocks.readFile;
-        writeFile = fsMocks.writeFile;
     });
 
-    it('should return default config when file does not exist', async () => {
-        vi.mocked(fileExists).mockResolvedValue(false);
-
+    it('should return default config with current API_VERSION', async () => {
         const result = await loadApiConfig();
 
         expect(result).toEqual({
@@ -182,39 +208,9 @@ describe('loadApiConfig', () => {
         });
     });
 
-    it('should merge disk config with defaults when file exists', async () => {
-        const diskConfig = {
-            extraOrigins: ['https://example.com'],
-            sandbox: true,
-            ssoSubIds: ['sub1', 'sub2'],
-        };
-
-        vi.mocked(fileExists).mockResolvedValue(true);
-        vi.mocked(readFile).mockResolvedValue(JSON.stringify(diskConfig));
-
+    it('should handle errors gracefully and return defaults', async () => {
         const result = await loadApiConfig();
 
-        expect(result).toEqual({
-            version: expect.any(String),
-            extraOrigins: ['https://example.com'],
-            sandbox: true,
-            ssoSubIds: ['sub1', 'sub2'],
-            plugins: [],
-        });
-    });
-
-    it('should use default config and overwrite file when JSON parsing fails', async () => {
-        const { fileExists: sharedFileExists } = await import('@unraid/shared/util/file.js');
-
-        vi.mocked(fileExists).mockResolvedValue(true);
-        vi.mocked(readFile).mockResolvedValue('{ invalid json }');
-        vi.mocked(sharedFileExists).mockResolvedValue(false); // For persist operation
-        vi.mocked(writeFile).mockResolvedValue(undefined);
-
-        const result = await loadApiConfig();
-
-        // Error logging is handled by NestJS Logger, just verify the config is returned
-        expect(writeFile).toHaveBeenCalled();
         expect(result).toEqual({
             version: expect.any(String),
             extraOrigins: [],
@@ -223,56 +219,4 @@ describe('loadApiConfig', () => {
             plugins: [],
         });
     });
-
-    it('should handle write failure gracefully when JSON parsing fails', async () => {
-        const { fileExists: sharedFileExists } = await import('@unraid/shared/util/file.js');
-
-        vi.mocked(fileExists).mockResolvedValue(true);
-        vi.mocked(readFile).mockResolvedValue('{ invalid json }');
-        vi.mocked(sharedFileExists).mockResolvedValue(false); // For persist operation
-        vi.mocked(writeFile).mockRejectedValue(new Error('Permission denied'));
-
-        const result = await loadApiConfig();
-
-        // Error logging is handled by NestJS Logger, just verify the config is returned
-        expect(writeFile).toHaveBeenCalled();
-        expect(result).toEqual({
-            version: expect.any(String),
-            extraOrigins: [],
-            sandbox: false,
-            ssoSubIds: [],
-            plugins: [],
-        });
-    });
-
-    it('should use default config when file is empty', async () => {
-        vi.mocked(fileExists).mockResolvedValue(true);
-        vi.mocked(readFile).mockResolvedValue('');
-
-        const result = await loadApiConfig();
-
-        // No error logging expected for empty files
-        expect(result).toEqual({
-            version: expect.any(String),
-            extraOrigins: [],
-            sandbox: false,
-            ssoSubIds: [],
-            plugins: [],
-        });
-    });
-
-    it('should always override version with current API_VERSION', async () => {
-        const diskConfig = {
-            version: 'old-version',
-            extraOrigins: ['https://example.com'],
-        };
-
-        vi.mocked(fileExists).mockResolvedValue(true);
-        vi.mocked(readFile).mockResolvedValue(JSON.stringify(diskConfig));
-
-        const result = await loadApiConfig();
-
-        expect(result.version).not.toBe('old-version');
-        expect(result.version).toBeTruthy();
-    });
 });

api/src/unraid-api/config/factory/api-state.model.test.ts

@@ -1,364 +0,0 @@
-import { Logger } from '@nestjs/common';
-import { readFile } from 'node:fs/promises';
-import { join } from 'path';
-
-import type { Mock } from 'vitest';
-import { beforeEach, describe, expect, it, vi } from 'vitest';
-
-import { fileExists } from '@app/core/utils/files/file-exists.js';
-import { ApiStateConfig } from '@app/unraid-api/config/factory/api-state.model.js';
-import { ConfigPersistenceHelper } from '@app/unraid-api/config/persistence.helper.js';
-
-vi.mock('node:fs/promises');
-vi.mock('@app/core/utils/files/file-exists.js');
-vi.mock('@app/environment.js', () => ({
-    PATHS_CONFIG_MODULES: '/test/config/path',
-}));
-
-describe('ApiStateConfig', () => {
-    let mockPersistenceHelper: ConfigPersistenceHelper;
-    let mockLogger: Logger;
-
-    interface TestConfig {
-        name: string;
-        value: number;
-        enabled: boolean;
-    }
-
-    const defaultConfig: TestConfig = {
-        name: 'test',
-        value: 42,
-        enabled: true,
-    };
-
-    const parseFunction = (data: unknown): TestConfig => {
-        if (!data || typeof data !== 'object') {
-            throw new Error('Invalid config format');
-        }
-        return data as TestConfig;
-    };
-
-    beforeEach(() => {
-        vi.clearAllMocks();
-
-        mockPersistenceHelper = {
-            persistIfChanged: vi.fn().mockResolvedValue(true),
-        } as any;
-
-        mockLogger = {
-            log: vi.fn(),
-            warn: vi.fn(),
-            error: vi.fn(),
-            debug: vi.fn(),
-        } as any;
-
-        vi.spyOn(Logger.prototype, 'log').mockImplementation(mockLogger.log);
-        vi.spyOn(Logger.prototype, 'warn').mockImplementation(mockLogger.warn);
-        vi.spyOn(Logger.prototype, 'error').mockImplementation(mockLogger.error);
-        vi.spyOn(Logger.prototype, 'debug').mockImplementation(mockLogger.debug);
-    });
-
-    describe('constructor', () => {
-        it('should initialize with cloned default config', () => {
-            const config = new ApiStateConfig(
-                {
-                    name: 'test-config',
-                    defaultConfig,
-                    parse: parseFunction,
-                },
-                mockPersistenceHelper
-            );
-
-            expect(config.config).toEqual(defaultConfig);
-            expect(config.config).not.toBe(defaultConfig);
-        });
-    });
-
-    describe('token', () => {
-        it('should generate correct token', () => {
-            const config = new ApiStateConfig(
-                {
-                    name: 'my-config',
-                    defaultConfig,
-                    parse: parseFunction,
-                },
-                mockPersistenceHelper
-            );
-
-            expect(config.token).toBe('ApiConfig.my-config');
-        });
-    });
-
-    describe('file paths', () => {
-        it('should generate correct file name', () => {
-            const config = new ApiStateConfig(
-                {
-                    name: 'test-config',
-                    defaultConfig,
-                    parse: parseFunction,
-                },
-                mockPersistenceHelper
-            );
-
-            expect(config.fileName).toBe('test-config.json');
-        });
-
-        it('should generate correct file path', () => {
-            const config = new ApiStateConfig(
-                {
-                    name: 'test-config',
-                    defaultConfig,
-                    parse: parseFunction,
-                },
-                mockPersistenceHelper
-            );
-
-            expect(config.filePath).toBe(join('/test/config/path', 'test-config.json'));
-        });
-    });
-
-    describe('parseConfig', () => {
-        let config: ApiStateConfig<TestConfig>;
-
-        beforeEach(() => {
-            config = new ApiStateConfig(
-                {
-                    name: 'test-config',
-                    defaultConfig,
-                    parse: parseFunction,
-                },
-                mockPersistenceHelper
-            );
-        });
-
-        it('should return undefined when file does not exist', async () => {
-            (fileExists as Mock).mockResolvedValue(false);
-
-            const result = await config.parseConfig();
-
-            expect(result).toBeUndefined();
-            expect(readFile).not.toHaveBeenCalled();
-        });
-
-        it('should parse valid JSON config', async () => {
-            const validConfig = { name: 'custom', value: 100, enabled: false };
-            (fileExists as Mock).mockResolvedValue(true);
-            (readFile as Mock).mockResolvedValue(JSON.stringify(validConfig));
-
-            const result = await config.parseConfig();
-
-            expect(result).toEqual(validConfig);
-            expect(readFile).toHaveBeenCalledWith(config.filePath, 'utf8');
-        });
-
-        it('should return undefined for empty file', async () => {
-            (fileExists as Mock).mockResolvedValue(true);
-            (readFile as Mock).mockResolvedValue('');
-
-            const result = await config.parseConfig();
-
-            expect(result).toBeUndefined();
-            expect(mockLogger.warn).toHaveBeenCalledWith(expect.stringContaining('is empty'));
-        });
-
-        it('should return undefined for whitespace-only file', async () => {
-            (fileExists as Mock).mockResolvedValue(true);
-            (readFile as Mock).mockResolvedValue('   \n\t  ');
-
-            const result = await config.parseConfig();
-
-            expect(result).toBeUndefined();
-            expect(mockLogger.warn).toHaveBeenCalledWith(expect.stringContaining('is empty'));
-        });
-
-        it('should throw error for invalid JSON', async () => {
-            (fileExists as Mock).mockResolvedValue(true);
-            (readFile as Mock).mockResolvedValue('{ invalid json }');
-
-            await expect(config.parseConfig()).rejects.toThrow();
-            expect(mockLogger.error).toHaveBeenCalledWith(
-                expect.stringContaining('Failed to parse JSON')
-            );
-            expect(mockLogger.debug).toHaveBeenCalledWith(expect.stringContaining('{ invalid json }'));
-        });
-
-        it('should throw error for incomplete JSON', async () => {
-            (fileExists as Mock).mockResolvedValue(true);
-            (readFile as Mock).mockResolvedValue('{ "name": "test"');
-
-            await expect(config.parseConfig()).rejects.toThrow();
-            expect(mockLogger.error).toHaveBeenCalledWith(
-                expect.stringContaining('Failed to parse JSON')
-            );
-        });
-
-        it('should use custom file path when provided', async () => {
-            const customPath = '/custom/path/config.json';
-            (fileExists as Mock).mockResolvedValue(true);
-            (readFile as Mock).mockResolvedValue(JSON.stringify(defaultConfig));
-
-            await config.parseConfig({ filePath: customPath });
-
-            expect(fileExists).toHaveBeenCalledWith(customPath);
-            expect(readFile).toHaveBeenCalledWith(customPath, 'utf8');
-        });
-    });
-
-    describe('persist', () => {
-        let config: ApiStateConfig<TestConfig>;
-
-        beforeEach(() => {
-            config = new ApiStateConfig(
-                {
-                    name: 'test-config',
-                    defaultConfig,
-                    parse: parseFunction,
-                },
-                mockPersistenceHelper
-            );
-        });
-
-        it('should persist current config when no argument provided', async () => {
-            const result = await config.persist();
-
-            expect(result).toBe(true);
-            expect(mockPersistenceHelper.persistIfChanged).toHaveBeenCalledWith(
-                config.filePath,
-                defaultConfig
-            );
-        });
-
-        it('should persist provided config', async () => {
-            const customConfig = { name: 'custom', value: 999, enabled: false };
-
-            const result = await config.persist(customConfig);
-
-            expect(result).toBe(true);
-            expect(mockPersistenceHelper.persistIfChanged).toHaveBeenCalledWith(
-                config.filePath,
-                customConfig
-            );
-        });
-
-        it('should return false and log error on persistence failure', async () => {
-            (mockPersistenceHelper.persistIfChanged as Mock).mockResolvedValue(false);
-
-            const result = await config.persist();
-
-            expect(result).toBe(false);
-            expect(mockLogger.error).toHaveBeenCalledWith(
-                expect.stringContaining('Could not write config')
-            );
-        });
-    });
-
-    describe('load', () => {
-        let config: ApiStateConfig<TestConfig>;
-
-        beforeEach(() => {
-            config = new ApiStateConfig(
-                {
-                    name: 'test-config',
-                    defaultConfig,
-                    parse: parseFunction,
-                },
-                mockPersistenceHelper
-            );
-        });
-
-        it('should load config from file when it exists', async () => {
-            const savedConfig = { name: 'saved', value: 200, enabled: true };
-            (fileExists as Mock).mockResolvedValue(true);
-            (readFile as Mock).mockResolvedValue(JSON.stringify(savedConfig));
-
-            await config.load();
-
-            expect(config.config).toEqual(savedConfig);
-        });
-
-        it('should create default config when file does not exist', async () => {
-            (fileExists as Mock).mockResolvedValue(false);
-
-            await config.load();
-
-            expect(config.config).toEqual(defaultConfig);
-            expect(mockLogger.log).toHaveBeenCalledWith(
-                expect.stringContaining('Config file does not exist')
-            );
-            expect(mockPersistenceHelper.persistIfChanged).toHaveBeenCalledWith(
-                config.filePath,
-                defaultConfig
-            );
-        });
-
-        it('should not modify config when file is invalid', async () => {
-            (fileExists as Mock).mockResolvedValue(true);
-            (readFile as Mock).mockResolvedValue('invalid json');
-
-            await config.load();
-
-            expect(config.config).toEqual(defaultConfig);
-            expect(mockLogger.warn).toHaveBeenCalledWith(
-                expect.any(Error),
-                expect.stringContaining('is invalid')
-            );
-        });
-
-        it('should not throw even when persist fails', async () => {
-            (fileExists as Mock).mockResolvedValue(false);
-            (mockPersistenceHelper.persistIfChanged as Mock).mockResolvedValue(false);
-
-            await expect(config.load()).resolves.not.toThrow();
-
-            expect(config.config).toEqual(defaultConfig);
-        });
-    });
-
-    describe('update', () => {
-        let config: ApiStateConfig<TestConfig>;
-
-        beforeEach(() => {
-            config = new ApiStateConfig(
-                {
-                    name: 'test-config',
-                    defaultConfig,
-                    parse: parseFunction,
-                },
-                mockPersistenceHelper
-            );
-        });
-
-        it('should update config with partial values', () => {
-            config.update({ value: 123 });
-
-            expect(config.config).toEqual({
-                name: 'test',
-                value: 123,
-                enabled: true,
-            });
-        });
-
-        it('should return self for chaining', () => {
-            const result = config.update({ enabled: false });
-
-            expect(result).toBe(config);
-        });
-
-        it('should validate updated config through parse function', () => {
-            const badParseFunction = vi.fn().mockImplementation(() => {
-                throw new Error('Validation failed');
-            });
-
-            const strictConfig = new ApiStateConfig(
-                {
-                    name: 'strict-config',
-                    defaultConfig,
-                    parse: badParseFunction,
-                },
-                mockPersistenceHelper
-            );
-
-            expect(() => strictConfig.update({ value: -1 })).toThrow('Validation failed');
-        });
-    });
-});

api/src/unraid-api/config/factory/api-state.model.ts

@@ -1,122 +0,0 @@
-import { Logger } from '@nestjs/common';
-import { readFile } from 'node:fs/promises';
-import { join } from 'path';
-
-import { fileExists } from '@app/core/utils/files/file-exists.js';
-import { PATHS_CONFIG_MODULES } from '@app/environment.js';
-import { makeConfigToken } from '@app/unraid-api/config/factory/config.injection.js';
-import { ConfigPersistenceHelper } from '@app/unraid-api/config/persistence.helper.js';
-
-export interface ApiStateConfigOptions<T> {
-    /**
-     * The name of the config.
-     *
-     * - Must be unique.
-     * - Should be the key representing this config in the `ConfigFeatures` interface.
-     * - Used for logging and dependency injection.
-     */
-    name: string;
-    defaultConfig: T;
-    parse: (data: unknown) => T;
-}
-
-export class ApiStateConfig<T> {
-    #config: T;
-    private logger: Logger;
-
-    constructor(
-        readonly options: ApiStateConfigOptions<T>,
-        readonly persistenceHelper: ConfigPersistenceHelper
-    ) {
-        // avoid sharing a reference with the given default config. This allows us to re-use it.
-        this.#config = structuredClone(options.defaultConfig);
-        this.logger = new Logger(this.token);
-    }
-
-    /** Unique token for this config. Used for Dependency Injection & logging. */
-    get token() {
-        return makeConfigToken(this.options.name);
-    }
-
-    get fileName() {
-        return `${this.options.name}.json`;
-    }
-
-    get filePath() {
-        return join(PATHS_CONFIG_MODULES, this.fileName);
-    }
-
-    get config() {
-        return this.#config;
-    }
-
-    /**
-     * Persists the config to the file system. Will never throw.
-     * @param config - The config to persist.
-     * @returns True if the config was written successfully, false otherwise.
-     */
-    async persist(config = this.#config) {
-        const success = await this.persistenceHelper.persistIfChanged(this.filePath, config);
-        if (!success) {
-            this.logger.error(`Could not write config to ${this.filePath}.`);
-        }
-        return success;
-    }
-
-    /**
-     * Reads the config from a path (defaults to the default file path of the config).
-     * @param opts - The options for the read operation.
-     * @param opts.filePath - The path to the config file.
-     * @returns The parsed config or undefined if the file does not exist.
-     * @throws If the file exists but is invalid.
-     */
-    async parseConfig(opts: { filePath?: string } = {}): Promise<T | undefined> {
-        const { filePath = this.filePath } = opts;
-        if (!(await fileExists(filePath))) return undefined;
-
-        const fileContent = await readFile(filePath, 'utf8');
-
-        if (!fileContent || fileContent.trim() === '') {
-            this.logger.warn(`Config file '${filePath}' is empty.`);
-            return undefined;
-        }
-
-        try {
-            const rawConfig = JSON.parse(fileContent);
-            return this.options.parse(rawConfig);
-        } catch (error) {
-            this.logger.error(
-                `Failed to parse JSON from '${filePath}': ${error instanceof Error ? error.message : String(error)}`
-            );
-            this.logger.debug(`File content: ${fileContent.substring(0, 100)}...`);
-            throw error;
-        }
-    }
-
-    /**
-     * Loads config from the file system. If the file does not exist, it will be created with the default config.
-     * If the config is invalid or corrupt, no action will be taken. The error will be logged.
-     *
-     * Will never throw.
-     */
-    async load() {
-        try {
-            const config = await this.parseConfig();
-            if (config) {
-                this.#config = config;
-            } else {
-                this.logger.log(`Config file does not exist. Writing default config.`);
-                this.#config = this.options.defaultConfig;
-                await this.persist();
-            }
-        } catch (error) {
-            this.logger.warn(error, `Config file '${this.filePath}' is invalid. Not modifying config.`);
-        }
-    }
-
-    update(config: Partial<T>) {
-        const proposedConfig = this.options.parse({ ...this.#config, ...config });
-        this.#config = proposedConfig;
-        return this;
-    }
-}

api/src/unraid-api/config/factory/api-state.register.ts

@@ -1,54 +0,0 @@
-import type { DynamicModule, Provider } from '@nestjs/common';
-import { SchedulerRegistry } from '@nestjs/schedule';
-
-import type { ApiStateConfigOptions } from '@app/unraid-api/config/factory/api-state.model.js';
-import type { ApiStateConfigPersistenceOptions } from '@app/unraid-api/config/factory/api-state.service.js';
-import { ApiStateConfig } from '@app/unraid-api/config/factory/api-state.model.js';
-import { ScheduledConfigPersistence } from '@app/unraid-api/config/factory/api-state.service.js';
-import { makeConfigToken } from '@app/unraid-api/config/factory/config.injection.js';
-import { ConfigPersistenceHelper } from '@app/unraid-api/config/persistence.helper.js';
-
-type ApiStateRegisterOptions<ConfigType> = ApiStateConfigOptions<ConfigType> & {
-    persistence?: ApiStateConfigPersistenceOptions;
-};
-
-export class ApiStateConfigModule {
-    static async register<ConfigType>(
-        options: ApiStateRegisterOptions<ConfigType>
-    ): Promise<DynamicModule> {
-        const { persistence, ...configOptions } = options;
-        const configToken = makeConfigToken(options.name);
-        const persistenceToken = makeConfigToken(options.name, ScheduledConfigPersistence.name);
-        const ConfigProvider = {
-            provide: configToken,
-            useFactory: async (helper: ConfigPersistenceHelper) => {
-                const config = new ApiStateConfig(configOptions, helper);
-                await config.load();
-                return config;
-            },
-            inject: [ConfigPersistenceHelper],
-        };
-
-        const providers: Provider[] = [ConfigProvider, ConfigPersistenceHelper];
-        const exports = [configToken];
-        if (persistence) {
-            providers.push({
-                provide: persistenceToken,
-                useFactory: (
-                    schedulerRegistry: SchedulerRegistry,
-                    config: ApiStateConfig<ConfigType>
-                ) => {
-                    return new ScheduledConfigPersistence(schedulerRegistry, config, persistence);
-                },
-                inject: [SchedulerRegistry, configToken],
-            });
-            exports.push(persistenceToken);
-        }
-
-        return {
-            module: ApiStateConfigModule,
-            providers,
-            exports,
-        };
-    }
-}

api/src/unraid-api/config/factory/api-state.service.ts

@@ -1,82 +0,0 @@
-import type { OnModuleDestroy, OnModuleInit } from '@nestjs/common';
-import { Logger } from '@nestjs/common';
-import { SchedulerRegistry } from '@nestjs/schedule';
-
-import type { ApiStateConfig } from '@app/unraid-api/config/factory/api-state.model.js';
-import { makeConfigToken } from '@app/unraid-api/config/factory/config.injection.js';
-
-export interface ApiStateConfigPersistenceOptions {
-    /** How often to persist the config to the file system, in milliseconds. Defaults to 10 seconds. */
-    intervalMs?: number;
-    /** How many consecutive failed persistence attempts to tolerate before stopping. Defaults to 5. */
-    maxConsecutiveFailures?: number;
-    /** By default, the config will be persisted to the file system when the module is initialized and destroyed.
-     * Set this to true to disable this behavior.
-     */
-    disableLifecycleHooks?: boolean;
-}
-
-export class ScheduledConfigPersistence<T> implements OnModuleInit, OnModuleDestroy {
-    private consecutiveFailures = 0;
-    private logger: Logger;
-
-    constructor(
-        private readonly schedulerRegistry: SchedulerRegistry,
-        private readonly config: ApiStateConfig<T>,
-        private readonly options: ApiStateConfigPersistenceOptions
-    ) {
-        this.logger = new Logger(this.token);
-    }
-
-    get token() {
-        return makeConfigToken(this.configName, ScheduledConfigPersistence.name);
-    }
-
-    get configName() {
-        return this.config.options.name;
-    }
-
-    onModuleInit() {
-        if (this.options.disableLifecycleHooks) return;
-        this.setup();
-    }
-
-    async onModuleDestroy() {
-        if (this.options.disableLifecycleHooks) return;
-        this.stop();
-        await this.config.persist();
-    }
-
-    stop() {
-        if (this.schedulerRegistry.getInterval(this.token)) {
-            this.schedulerRegistry.deleteInterval(this.token);
-        }
-    }
-
-    setup() {
-        const interval = this.schedulerRegistry.getInterval(this.token);
-        if (interval) {
-            this.logger.warn(`Persistence interval for '${this.token}' already exists. Aborting setup.`);
-            return;
-        }
-        const ONE_MINUTE = 60_000;
-        const { intervalMs = ONE_MINUTE, maxConsecutiveFailures = 3 } = this.options;
-
-        const callback = async () => {
-            const success = await this.config.persist();
-            if (success) {
-                this.consecutiveFailures = 0;
-                return;
-            }
-            this.consecutiveFailures++;
-            if (this.consecutiveFailures > maxConsecutiveFailures) {
-                this.logger.warn(
-                    `Failed to persist '${this.configName}' too many times in a row (${this.consecutiveFailures} attempts). Disabling persistence.`
-                );
-                this.schedulerRegistry.deleteInterval(this.token);
-            }
-        };
-
-        this.schedulerRegistry.addInterval(this.token, setInterval(callback, intervalMs));
-    }
-}

api/src/unraid-api/config/factory/config.injection.ts

@@ -1,22 +0,0 @@
-import { Inject } from '@nestjs/common';
-
-import type { ConfigFeatures } from '@app/unraid-api/config/factory/config.interface.js';
-
-/**
- * Creates a string token representation of the arguements. Pure function.
- *
- * @param configName - The name of the config.
- * @returns A colon-separated string
- */
-export function makeConfigToken(configName: string, ...details: string[]) {
-    return ['ApiConfig', configName, ...details].join('.');
-}
-
-/**
- * Custom decorator to inject a config by name.
- * @param feature - The name of the config to inject.
- * @returns Dependency injector for the config.
- */
-export function InjectConfig<K extends keyof ConfigFeatures>(feature: K) {
-    return Inject(makeConfigToken(feature));
-}

api/src/unraid-api/config/factory/config.interface.ts

@@ -1,15 +0,0 @@
-/**
- * Container record of config names to their types. Used for type completion on registered configs.
- * Config authors should redeclare/merge this interface with their config names as the keys
- * and implementation models as the types.
- */
-export interface ConfigFeatures {}
-
-export interface ConfigMetadata<T = unknown> {
-    /** Unique token for this config. Used for Dependency Injection, logging, etc. */
-    token: string;
-    /** The path to the config file. */
-    filePath?: string;
-    /** Validates a config of type `T`. */
-    validate: (config: unknown) => Promise<T>;
-}

api/src/unraid-api/config/persistence.helper.ts

@@ -1,70 +0,0 @@
-import { Injectable } from '@nestjs/common';
-import { readFile, writeFile } from 'fs/promises';
-
-import { fileExists } from '@unraid/shared/util/file.js';
-import { isEqual } from 'lodash-es';
-
-@Injectable()
-export class ConfigPersistenceHelper {
-    /**
-     * Persist the config to disk if the given data is different from the data on-disk.
-     * This helps preserve the boot flash drive's life by avoiding unnecessary writes.
-     *
-     * @param filePath - The path to the config file.
-     * @param data - The data to persist.
-     * @returns `true` if the config was persisted, `false` if no changes were needed or if persistence failed.
-     *
-     * This method is designed to never throw errors. If the existing file is corrupted or unreadable,
-     * it will attempt to overwrite it with the new data. If write operations fail, it returns false
-     * but does not crash the application.
-     */
-    async persistIfChanged(filePath: string, data: unknown): Promise<boolean> {
-        if (!(await fileExists(filePath))) {
-            try {
-                const jsonString = JSON.stringify(data ?? {}, null, 2);
-                await writeFile(filePath, jsonString);
-                return true;
-            } catch (error) {
-                // JSON serialization or write failed, but don't crash - just return false
-                return false;
-            }
-        }
-
-        let currentData: unknown;
-        try {
-            const fileContent = await readFile(filePath, 'utf8');
-            currentData = JSON.parse(fileContent);
-        } catch (error) {
-            // If existing file is corrupted, treat it as if it doesn't exist
-            // and write the new data
-            try {
-                const jsonString = JSON.stringify(data ?? {}, null, 2);
-                await writeFile(filePath, jsonString);
-                return true;
-            } catch (writeError) {
-                // JSON serialization or write failed, but don't crash - just return false
-                return false;
-            }
-        }
-
-        let stagedData: unknown;
-        try {
-            stagedData = JSON.parse(JSON.stringify(data));
-        } catch (error) {
-            // If data can't be serialized to JSON, we can't persist it
-            return false;
-        }
-
-        if (isEqual(currentData, stagedData)) {
-            return false;
-        }
-
-        try {
-            await writeFile(filePath, JSON.stringify(stagedData, null, 2));
-            return true;
-        } catch (error) {
-            // Write failed, but don't crash - just return false
-            return false;
-        }
-    }
-}

api/src/unraid-api/cron/log-rotate.service.ts

@@ -1,6 +1,6 @@
 import { Injectable, Logger } from '@nestjs/common';
 import { Cron } from '@nestjs/schedule';
-import { existsSync } from 'fs';
+import { stat } from 'fs/promises';
 
 import { execa } from 'execa';
 
@@ -8,25 +8,26 @@ import { execa } from 'execa';
 export class LogRotateService {
     private readonly logger = new Logger(LogRotateService.name);
 
-    logRotatePath: string = '/usr/sbin/logrotate';
-    configPath: string = '/etc/logrotate.conf';
-    @Cron('0 * * * *')
+    private readonly logFilePath = '/var/log/graphql-api.log';
+    private readonly maxSizeBytes = 5 * 1024 * 1024; // 5MB
+
+    @Cron('*/20 * * * *') // Every 20 minutes
     async handleCron() {
         try {
-            if (!existsSync(this.logRotatePath)) {
-                throw new Error(`Logrotate binary not found at ${this.logRotatePath}`);
+            const stats = await stat(this.logFilePath);
+            if (stats.size > this.maxSizeBytes) {
+                this.logger.debug(`Log file size (${stats.size} bytes) exceeds limit, truncating`);
+                await execa('truncate', ['-s', '0', this.logFilePath]);
+                this.logger.debug('Log file truncated successfully');
+            } else {
+                this.logger.debug(`Log file size (${stats.size} bytes) within limit`);
             }
-            if (!existsSync(this.configPath)) {
-                throw new Error(`Logrotate config not found at ${this.configPath}`);
-            }
-            this.logger.debug('Running logrotate');
-            const result = await execa(this.logRotatePath, [this.configPath]);
-            if (result.failed) {
-                throw new Error(`Logrotate execution failed: ${result.stderr}`);
-            }
-            this.logger.debug('Logrotate completed successfully');
         } catch (error) {
-            this.logger.debug('Failed to run logrotate with error' + error);
+            if (error instanceof Error && 'code' in error && error.code === 'ENOENT') {
+                this.logger.debug('Log file does not exist, skipping truncation');
+            } else {
+                this.logger.debug('Failed to check/truncate log file: ' + error);
+            }
         }
     }
 }

api/src/unraid-api/graph/resolvers/display/display.service.ts

@@ -1,10 +1,10 @@
 import { Injectable } from '@nestjs/common';
-import { existsSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 
 import { type DynamixConfig } from '@app/core/types/ini.js';
 import { toBoolean } from '@app/core/utils/casting.js';
+import { fileExists } from '@app/core/utils/files/file-exists.js';
 import { loadState } from '@app/core/utils/misc/load-state.js';
 import { getters } from '@app/store/index.js';
 import { ThemeName } from '@app/unraid-api/graph/resolvers/customization/theme.model.js';
@@ -80,7 +80,7 @@ export class DisplayService {
 
         // If the config file doesn't exist then it's a new OS install
         // Default to "default"
-        if (!existsSync(configFilePath)) {
+        if (!(await fileExists(configFilePath))) {
             return states.default;
         }
 

api/src/unraid-api/graph/resolvers/notifications/loadNotificationsFile.test.ts

@@ -0,0 +1,228 @@
+// Unit Test File for NotificationsService: loadNotificationFile
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { NotificationIni } from '@app/core/types/states/notification.js';
+import {
+    Notification,
+    NotificationImportance,
+    NotificationType,
+} from '@app/unraid-api/graph/resolvers/notifications/notifications.model.js';
+import { NotificationsService } from '@app/unraid-api/graph/resolvers/notifications/notifications.service.js';
+
+// Only mock getters.dynamix and Logger
+vi.mock('@app/store/index.js', () => ({
+    getters: {
+        dynamix: vi.fn().mockReturnValue({
+            notify: { path: '/test/notifications' },
+            display: {
+                date: 'Y-m-d',
+                time: 'H:i:s',
+            },
+        }),
+    },
+}));
+
+vi.mock('@nestjs/common', async (importOriginal) => {
+    const original = await importOriginal<typeof import('@nestjs/common')>();
+    return {
+        ...original,
+        Logger: vi.fn(() => ({
+            log: vi.fn(),
+            warn: vi.fn(),
+            error: vi.fn(),
+            debug: vi.fn(),
+            verbose: vi.fn(),
+        })),
+    };
+});
+
+describe('NotificationsService - loadNotificationFile (minimal mocks)', () => {
+    let service: NotificationsService;
+
+    beforeEach(() => {
+        service = new NotificationsService();
+    });
+
+    it('should load and validate a valid notification file', async () => {
+        const mockNotificationIni: NotificationIni = {
+            timestamp: '1609459200',
+            event: 'Test Event',
+            subject: 'Test Subject',
+            description: 'Test Description',
+            importance: 'alert',
+            link: 'http://example.com',
+        };
+
+        vi.spyOn(await import('@app/core/utils/misc/parse-config.js'), 'parseConfig').mockReturnValue(
+            mockNotificationIni
+        );
+
+        const result = await (service as any).loadNotificationFile(
+            '/test/path/test.notify',
+            NotificationType.UNREAD
+        );
+        expect(result).toEqual(
+            expect.objectContaining({
+                id: 'test.notify',
+                type: NotificationType.UNREAD,
+                title: 'Test Event',
+                subject: 'Test Subject',
+                description: 'Test Description',
+                importance: NotificationImportance.ALERT,
+                link: 'http://example.com',
+                timestamp: '2021-01-01T00:00:00.000Z',
+            })
+        );
+    });
+
+    it('should return masked warning notification on validation error (missing required fields)', async () => {
+        const invalidNotificationIni: Omit<NotificationIni, 'event'> = {
+            timestamp: '1609459200',
+            // event: 'Missing Event', // missing required field
+            subject: 'Test Subject',
+            description: 'Test Description',
+            importance: 'alert',
+        };
+
+        vi.spyOn(await import('@app/core/utils/misc/parse-config.js'), 'parseConfig').mockReturnValue(
+            invalidNotificationIni
+        );
+
+        const result = await (service as any).loadNotificationFile(
+            '/test/path/invalid.notify',
+            NotificationType.UNREAD
+        );
+        expect(result.id).toBe('invalid.notify');
+        expect(result.importance).toBe(NotificationImportance.WARNING);
+        expect(result.description).toContain('invalid and cannot be displayed');
+    });
+
+    it('should handle invalid enum values', async () => {
+        const invalidNotificationIni: NotificationIni = {
+            timestamp: '1609459200',
+            event: 'Test Event',
+            subject: 'Test Subject',
+            description: 'Test Description',
+            importance: 'not-a-valid-enum' as any,
+        };
+
+        vi.spyOn(await import('@app/core/utils/misc/parse-config.js'), 'parseConfig').mockReturnValue(
+            invalidNotificationIni
+        );
+
+        const result = await (service as any).loadNotificationFile(
+            '/test/path/invalid-enum.notify',
+            NotificationType.UNREAD
+        );
+        expect(result.id).toBe('invalid-enum.notify');
+        // Implementation falls back to INFO for unknown importance
+        expect(result.importance).toBe(NotificationImportance.INFO);
+        // Should not be a masked warning notification, just fallback to INFO
+        expect(result.description).toBe('Test Description');
+    });
+
+    it('should handle missing description field (should return masked warning notification)', async () => {
+        const mockNotificationIni: Omit<NotificationIni, 'description'> = {
+            timestamp: '1609459200',
+            event: 'Test Event',
+            subject: 'Test Subject',
+            importance: 'normal',
+        };
+
+        vi.spyOn(await import('@app/core/utils/misc/parse-config.js'), 'parseConfig').mockReturnValue(
+            mockNotificationIni
+        );
+
+        const result = await (service as any).loadNotificationFile(
+            '/test/path/test.notify',
+            NotificationType.UNREAD
+        );
+        // Should be a masked warning notification
+        expect(result.description).toContain('invalid and cannot be displayed');
+        expect(result.importance).toBe(NotificationImportance.WARNING);
+    });
+
+    it('should preserve passthrough data from notification file (only known fields)', async () => {
+        const mockNotificationIni: NotificationIni & { customField: string } = {
+            timestamp: '1609459200',
+            event: 'Test Event',
+            subject: 'Test Subject',
+            description: 'Test Description',
+            importance: 'normal',
+            link: 'http://example.com',
+            customField: 'custom value',
+        };
+
+        vi.spyOn(await import('@app/core/utils/misc/parse-config.js'), 'parseConfig').mockReturnValue(
+            mockNotificationIni
+        );
+
+        const result = await (service as any).loadNotificationFile(
+            '/test/path/test.notify',
+            NotificationType.UNREAD
+        );
+        expect(result).toEqual(
+            expect.objectContaining({
+                link: 'http://example.com',
+                // customField should NOT be present
+                description: 'Test Description',
+                id: 'test.notify',
+                type: NotificationType.UNREAD,
+                title: 'Test Event',
+                subject: 'Test Subject',
+                importance: NotificationImportance.INFO,
+                timestamp: '2021-01-01T00:00:00.000Z',
+            })
+        );
+        expect((result as any).customField).toBeUndefined();
+    });
+
+    it('should handle missing timestamp field gracefully', async () => {
+        const mockNotificationIni: Omit<NotificationIni, 'timestamp'> = {
+            // timestamp is missing
+            event: 'Test Event',
+            subject: 'Test Subject',
+            description: 'Test Description',
+            importance: 'alert',
+        };
+
+        vi.spyOn(await import('@app/core/utils/misc/parse-config.js'), 'parseConfig').mockReturnValue(
+            mockNotificationIni
+        );
+
+        const result = await (service as any).loadNotificationFile(
+            '/test/path/missing-timestamp.notify',
+            NotificationType.UNREAD
+        );
+        expect(result.id).toBe('missing-timestamp.notify');
+        expect(result.importance).toBe(NotificationImportance.ALERT);
+        expect(result.description).toBe('Test Description');
+        expect(result.timestamp).toBeUndefined(); // Missing timestamp results in undefined
+        expect(result.formattedTimestamp).toBe(undefined); // Also undefined since timestamp is missing
+    });
+
+    it('should handle malformed timestamp field gracefully', async () => {
+        const mockNotificationIni: NotificationIni = {
+            timestamp: 'not-a-timestamp',
+            event: 'Test Event',
+            subject: 'Test Subject',
+            description: 'Test Description',
+            importance: 'alert',
+        };
+
+        vi.spyOn(await import('@app/core/utils/misc/parse-config.js'), 'parseConfig').mockReturnValue(
+            mockNotificationIni
+        );
+
+        const result = await (service as any).loadNotificationFile(
+            '/test/path/malformed-timestamp.notify',
+            NotificationType.UNREAD
+        );
+        expect(result.id).toBe('malformed-timestamp.notify');
+        expect(result.importance).toBe(NotificationImportance.ALERT);
+        expect(result.description).toBe('Test Description');
+        expect(result.timestamp).toBeUndefined(); // Malformed timestamp results in undefined
+        expect(result.formattedTimestamp).toBe('not-a-timestamp'); // Returns original string when parsing fails
+    });
+});

api/src/unraid-api/graph/resolvers/notifications/notifications.service.spec.ts

@@ -1,3 +1,11 @@
+// Integration Test File for NotificationsService
+// ------------------------------------------------
+// This file contains integration-style tests for the NotificationsService.
+// It uses the full NestJS TestingModule, mocks only the minimum required dependencies,
+// and interacts with the real filesystem (in /tmp/test/notifications).
+// These tests cover end-to-end service behavior, including notification creation,
+// archiving, unarchiving, deletion, and legacy CLI compatibility.
+
 import type { TestingModule } from '@nestjs/testing';
 import { Test } from '@nestjs/testing';
 import { existsSync } from 'fs';

api/src/unraid-api/graph/resolvers/notifications/notifications.service.ts

@@ -1,10 +1,10 @@
 import { Injectable, Logger } from '@nestjs/common';
-import { statSync } from 'fs';
-import { readdir, rename, unlink, writeFile } from 'fs/promises';
+import { readdir, rename, stat, unlink, writeFile } from 'fs/promises';
 import { basename, join } from 'path';
 
 import type { Stats } from 'fs';
 import { FSWatcher, watch } from 'chokidar';
+import { ValidationError } from 'class-validator';
 import { execa } from 'execa';
 import { emptyDir } from 'fs-extra';
 import { encode as encodeIni } from 'ini';
@@ -581,12 +581,15 @@ export class NotificationsService {
         sortFn: SortFn<Stats> = (fileA, fileB) => fileB.birthtimeMs - fileA.birthtimeMs // latest first
     ): Promise<string[]> {
         const contents = narrowContent(await readdir(folderPath));
-        return contents
-            .map((content) => {
+        const contentStats = await Promise.all(
+            contents.map(async (content) => {
                 // pre-map each file's stats to avoid excess calls during sorting
                 const path = join(folderPath, content);
-                return { path, stats: statSync(path) };
+                const stats = await stat(path);
+                return { path, stats };
             })
+        );
+        return contentStats
             .sort((fileA, fileB) => sortFn(fileA.stats, fileB.stats))
             .map(({ path }) => path);
     }
@@ -635,10 +638,14 @@ export class NotificationsService {
      * Loads a notification file from disk, parses it to a Notification object, and
      * validates the object against the NotificationSchema.
      *
+     * If the file contains invalid data (doesn't conform to the Notification schema),
+     * instead of throwing, returns a masked warning notification with details masked,
+     * and logs a warning. This allows the system to gracefully handle corrupt or malformed notifications.
+     *
      * @param path The path to the notification file on disk.
      * @param type The type of the notification that is being loaded.
-     * @returns A parsed Notification object, or throws an error if the object is invalid.
-     * @throws An error if the object is invalid (doesn't conform to the graphql NotificationSchema).
+     * @returns A parsed Notification object, or a masked warning notification if invalid.
+     * @throws File system errors (file not found, permission issues) or unexpected validation errors.
      */
     private async loadNotificationFile(path: string, type: NotificationType): Promise<Notification> {
         const notificationFile = parseConfig<NotificationIni>({
@@ -656,8 +663,28 @@ export class NotificationsService {
         // The contents of the file, and therefore the notification, may not always be a valid notification.
         // so we parse it through the schema to make sure it is
 
-        const validatedNotification = await validateObject(Notification, notification);
-        return validatedNotification;
+        try {
+            const validatedNotification = await validateObject(Notification, notification);
+            return validatedNotification;
+        } catch (error) {
+            if (!(error instanceof ValidationError)) {
+                throw error;
+            }
+            const errorsToLog = error.children?.length ? error.children : error;
+            this.logger.warn(errorsToLog, `notification file at ${path} is invalid. Will mask.`);
+            const nameMask = this.getIdFromPath(path);
+            const dateMask = new Date();
+            return {
+                id: nameMask,
+                type,
+                title: nameMask,
+                subject: nameMask,
+                description: `This notification is invalid and cannot be displayed! For details, see the logs and the notification file at ${path}`,
+                importance: NotificationImportance.WARNING,
+                timestamp: dateMask.toISOString(),
+                formattedTimestamp: this.formatDatetime(dateMask),
+            };
+        }
     }
 
     private getIdFromPath(path: string) {
@@ -729,19 +756,22 @@ export class NotificationsService {
     }
 
     private formatTimestamp(timestamp: string) {
-        const { display: settings } = getters.dynamix();
         const date = this.parseNotificationDateToIsoDate(timestamp);
+        if (!date) {
+            this.logger.warn(`[formatTimestamp] Could not parse date from timestamp: ${date}`);
+            return timestamp;
+        }
+        return this.formatDatetime(date);
+    }
 
+    private formatDatetime(date: Date) {
+        const { display: settings } = getters.dynamix();
         if (!settings) {
             this.logger.warn(
                 '[formatTimestamp] Dynamix display settings not found. Cannot apply user settings.'
             );
-            return timestamp;
-        } else if (!date) {
-            this.logger.warn(`[formatTimestamp] Could not parse date from timestamp: ${date}`);
-            return timestamp;
+            return date.toISOString();
         }
-        // this.logger.debug(`[formatTimestamp] ${settings.date} :: ${settings.time} :: ${date}`);
         return formatDatetime(date, {
             dateFormat: settings.date,
             timeFormat: settings.time,

api/src/unraid-api/graph/resolvers/rclone/rclone-api.service.ts

@@ -1,7 +1,6 @@
 import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
 import crypto from 'crypto';
 import { ChildProcess } from 'node:child_process';
-import { existsSync } from 'node:fs';
 import { mkdir, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 
@@ -10,6 +9,7 @@ import got, { HTTPError } from 'got';
 import pRetry from 'p-retry';
 
 import { sanitizeParams } from '@app/core/log.js';
+import { fileExists } from '@app/core/utils/files/file-exists.js';
 import {
     CreateRCloneRemoteDto,
     DeleteRCloneRemoteDto,
@@ -104,7 +104,7 @@ export class RCloneApiService implements OnModuleInit, OnModuleDestroy {
     private async startRcloneSocket(socketPath: string, logFilePath: string): Promise<boolean> {
         try {
             // Make log file exists
-            if (!existsSync(logFilePath)) {
+            if (!(await fileExists(logFilePath))) {
                 this.logger.debug(`Creating log file: ${logFilePath}`);
                 await mkdir(dirname(logFilePath), { recursive: true });
                 await writeFile(logFilePath, '', 'utf-8');
@@ -187,7 +187,7 @@ export class RCloneApiService implements OnModuleInit, OnModuleDestroy {
         }
 
         // Clean up the socket file if it exists
-        if (this.rcloneSocketPath && existsSync(this.rcloneSocketPath)) {
+        if (this.rcloneSocketPath && (await fileExists(this.rcloneSocketPath))) {
             this.logger.log(`Removing RClone socket file: ${this.rcloneSocketPath}`);
             try {
                 await rm(this.rcloneSocketPath, { force: true });
@@ -201,7 +201,7 @@ export class RCloneApiService implements OnModuleInit, OnModuleDestroy {
      * Checks if the RClone socket exists
      */
     private async checkRcloneSocketExists(socketPath: string): Promise<boolean> {
-        const socketExists = existsSync(socketPath);
+        const socketExists = await fileExists(socketPath);
         if (!socketExists) {
             this.logger.warn(`RClone socket does not exist at: ${socketPath}`);
             return false;

api/src/unraid-api/plugin/plugin-management.service.ts

@@ -4,13 +4,14 @@ import { ConfigService } from '@nestjs/config';
 import { ApiConfig } from '@unraid/shared/services/api-config.js';
 
 import { DependencyService } from '@app/unraid-api/app/dependency.service.js';
-import { persistApiConfig } from '@app/unraid-api/config/api-config.module.js';
+import { ApiConfigPersistence } from '@app/unraid-api/config/api-config.module.js';
 
 @Injectable()
 export class PluginManagementService {
     constructor(
         private readonly configService: ConfigService<{ api: ApiConfig }, true>,
-        private readonly dependencyService: DependencyService
+        private readonly dependencyService: DependencyService,
+        private readonly apiConfigPersistence: ApiConfigPersistence
     ) {}
 
     get plugins() {
@@ -111,6 +112,6 @@ export class PluginManagementService {
     }
 
     private async persistConfig() {
-        return await persistApiConfig(this.configService.get('api', { infer: true }));
+        return await this.apiConfigPersistence.persist();
     }
 }

api/src/unraid-api/plugin/plugin.module.ts

@@ -1,6 +1,7 @@
 import { DynamicModule, Logger, Module } from '@nestjs/common';
 
 import { DependencyService } from '@app/unraid-api/app/dependency.service.js';
+import { ApiConfigModule } from '@app/unraid-api/config/api-config.module.js';
 import { ResolversModule } from '@app/unraid-api/graph/resolvers/resolvers.module.js';
 import { GlobalDepsModule } from '@app/unraid-api/plugin/global-deps.module.js';
 import { PluginManagementService } from '@app/unraid-api/plugin/plugin-management.service.js';
@@ -22,7 +23,7 @@ export class PluginModule {
 
         return {
             module: PluginModule,
-            imports: [GlobalDepsModule, ResolversModule, ...apiModules],
+            imports: [GlobalDepsModule, ResolversModule, ApiConfigModule, ...apiModules],
             providers: [PluginService, PluginManagementService, DependencyService, PluginResolver],
             exports: [PluginService, PluginManagementService, DependencyService, GlobalDepsModule],
         };
@@ -44,7 +45,7 @@ export class PluginCliModule {
 
         return {
             module: PluginCliModule,
-            imports: [GlobalDepsModule, ...cliModules],
+            imports: [GlobalDepsModule, ApiConfigModule, ...cliModules],
             providers: [PluginManagementService, DependencyService],
             exports: [PluginManagementService, DependencyService, GlobalDepsModule],
         };

api/src/unraid-api/unraid-file-modifier/modifications/__test__/__fixtures__/downloaded/.login.php.last-download-time

@@ -1 +1 @@
-1752524464371
+1753135397044

api/src/unraid-api/unraid-file-modifier/modifications/__test__/__fixtures__/downloaded/DefaultPageLayout.php.last-download-time

@@ -1 +1 @@
-1752524464066
+1753135396799

api/src/unraid-api/unraid-file-modifier/modifications/__test__/__fixtures__/downloaded/Notifications.page.last-download-time

@@ -1 +1 @@
-1752524464213
+1753135396931

api/src/unraid-api/unraid-file-modifier/modifications/__test__/__fixtures__/downloaded/auth-request.php.last-download-time

@@ -1 +1 @@
-1752524464631
+1753135397144

api/src/unraid-api/unraid-file-modifier/modifications/__test__/__fixtures__/downloaded/logrotate.conf.last-download-time

@@ -1 +0,0 @@
-999999999999999999999999999999999999

api/src/unraid-api/unraid-file-modifier/modifications/__test__/__fixtures__/downloaded/rc.nginx.last-download-time

@@ -1 +1 @@
-1752524464761
+1753135397303

api/src/unraid-api/unraid-file-modifier/modifications/__test__/generic-modification.spec.ts

@@ -8,7 +8,6 @@ import { describe, expect, test, vi } from 'vitest';
 import { FileModification } from '@app/unraid-api/unraid-file-modifier/file-modification.js';
 import AuthRequestModification from '@app/unraid-api/unraid-file-modifier/modifications/auth-request.modification.js';
 import DefaultPageLayoutModification from '@app/unraid-api/unraid-file-modifier/modifications/default-page-layout.modification.js';
-import LogRotateModification from '@app/unraid-api/unraid-file-modifier/modifications/log-rotate.modification.js';
 import NotificationsPageModification from '@app/unraid-api/unraid-file-modifier/modifications/notifications-page.modification.js';
 import RcNginxModification from '@app/unraid-api/unraid-file-modifier/modifications/rc-nginx.modification.js';
 import SSOFileModification from '@app/unraid-api/unraid-file-modifier/modifications/sso.modification.js';
@@ -56,13 +55,7 @@ const patchTestCases: ModificationTestCase[] = [
 ];
 
 /** Modifications that simply add a new file & remove it on rollback. */
-const simpleTestCases: ModificationTestCase[] = [
-    {
-        ModificationClass: LogRotateModification,
-        fileUrl: 'logrotate.conf',
-        fileName: 'logrotate.conf',
-    },
-];
+const simpleTestCases: ModificationTestCase[] = [];
 
 const downloadOrRetrieveOriginalFile = async (filePath: string, fileUrl: string): Promise<string> => {
     let originalContent = '';

api/src/unraid-api/unraid-file-modifier/modifications/auth-request.modification.ts

@@ -1,7 +1,7 @@
-import { existsSync } from 'fs';
 import { readFile } from 'fs/promises';
 import { join } from 'node:path';
 
+import { fileExists } from '@app/core/utils/files/file-exists.js';
 import {
     FileModification,
     ShouldApplyWithReason,
@@ -45,7 +45,7 @@ export default class AuthRequestModification extends FileModification {
 
         const filesToAdd = [getters.paths().webgui.logo.assetPath, ...jsFiles];
 
-        if (!existsSync(this.filePath)) {
+        if (!(await fileExists(this.filePath))) {
             throw new Error(`File ${this.filePath} not found.`);
         }
 

api/src/unraid-api/unraid-file-modifier/modifications/log-rotate.modification.ts

@@ -1,70 +0,0 @@
-import { Logger } from '@nestjs/common';
-import { readFile, rm, writeFile } from 'node:fs/promises';
-
-import { fileExists } from '@app/core/utils/files/file-exists.js';
-import {
-    FileModification,
-    ShouldApplyWithReason,
-} from '@app/unraid-api/unraid-file-modifier/file-modification.js';
-
-export default class LogRotateModification extends FileModification {
-    id: string = 'log-rotate';
-    public readonly filePath: string = '/etc/logrotate.d/unraid-api' as const;
-    private readonly logRotateConfig: string = `
-/var/log/unraid-api/*.log {
-    rotate 1
-    missingok
-    size 1M
-    su root root
-    compress
-    delaycompress
-    copytruncate
-    create 0640 root root
-}
-/var/log/graphql-api.log {
-    rotate 1
-    missingok
-    size 1M
-    su root root
-    compress
-    delaycompress
-    copytruncate
-    create 0640 root root
-}
-`.trimStart();
-
-    constructor(logger: Logger) {
-        super(logger);
-    }
-
-    protected async generatePatch(overridePath?: string): Promise<string> {
-        const currentContent = (await fileExists(this.filePath))
-            ? await readFile(this.filePath, 'utf8')
-            : '';
-
-        return this.createPatchWithDiff(
-            overridePath ?? this.filePath,
-            currentContent,
-            this.logRotateConfig
-        );
-    }
-
-    async shouldApply(): Promise<ShouldApplyWithReason> {
-        const alreadyConfigured = await fileExists(this.filePath);
-        if (alreadyConfigured) {
-            return { shouldApply: false, reason: 'LogRotate configuration already exists' };
-        }
-        return { shouldApply: true, reason: 'No LogRotate config for the API configured yet' };
-    }
-
-    async apply(): Promise<string> {
-        await this.rollback();
-        await writeFile(this.filePath, this.logRotateConfig, { mode: 0o644 });
-        return this.logRotateConfig;
-    }
-
-    async rollback(): Promise<void> {
-        await rm(this.getPathToAppliedPatch(), { force: true });
-        await rm(this.filePath, { force: true });
-    }
-}

api/src/unraid-api/unraid-file-modifier/modifications/patches/log-rotate.patch

@@ -1,25 +0,0 @@
-Index: /etc/logrotate.d/unraid-api
-===================================================================
---- /etc/logrotate.d/unraid-api	original
-+++ /etc/logrotate.d/unraid-api	modified
-@@ -0,0 +1,20 @@
-+/var/log/unraid-api/*.log {
-+    rotate 1
-+    missingok
-+    size 1M
-+    su root root
-+    compress
-+    delaycompress
-+    copytruncate
-+    create 0640 root root
-+}
-+/var/log/graphql-api.log {
-+    rotate 1
-+    missingok
-+    size 1M
-+    su root root
-+    compress
-+    delaycompress
-+    copytruncate
-+    create 0640 root root
-+}

api/src/unraid-api/unraid-file-modifier/modifications/rc-nginx.modification.ts

@@ -1,6 +1,6 @@
-import { existsSync } from 'fs';
 import { readFile } from 'fs/promises';
 
+import { fileExists } from '@app/core/utils/files/file-exists.js';
 import {
     FileModification,
     ShouldApplyWithReason,
@@ -25,7 +25,7 @@ export default class RcNginxModification extends FileModification {
      * @returns The patch for the rc.nginx file
      */
     protected async generatePatch(overridePath?: string): Promise<string> {
-        if (!existsSync(this.filePath)) {
+        if (!(await fileExists(this.filePath))) {
             throw new Error(`File ${this.filePath} not found.`);
         }
         const fileContent = await readFile(this.filePath, 'utf8');

package.json

@@ -3,7 +3,6 @@
   "private": true,
   "version": "4.10.0",
   "scripts": {
-    "preinstall": "node web/scripts/check-node-version.js",
     "build": "pnpm -r build",
     "build:watch": " pnpm -r --parallel build:watch",
     "dev": "pnpm -r dev",
@@ -27,6 +26,7 @@
       "@nestjs/core",
       "@parcel/watcher",
       "@swc/core",
+      "@tailwindcss/oxide",
       "@unraid/libvirt",
       "core-js",
       "cpu-features",
@@ -34,10 +34,12 @@
       "esbuild",
       "nestjs-pino",
       "protobufjs",
+      "sharp",
       "simple-git-hooks",
       "ssh2",
       "unrs-resolver",
-      "vue-demi"
+      "vue-demi",
+      "workerd"
     ]
   },
   "dependencies": {

packages/unraid-api-plugin-connect/src/config/config.persistence.ts

@@ -1,82 +1,48 @@
-import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { Injectable } from '@nestjs/common';
 import { ConfigService } from '@nestjs/config';
 import { existsSync, readFileSync } from 'fs';
-import { writeFile } from 'fs/promises';
-import path from 'path';
 
+import { ConfigFilePersister } from '@unraid/shared/services/config-file.js';
 import { plainToInstance } from 'class-transformer';
 import { validateOrReject } from 'class-validator';
 import { parse as parseIni } from 'ini';
-import { isEqual } from 'lodash-es';
-import { bufferTime } from 'rxjs/operators';
 
 import type { MyServersConfig as LegacyConfig } from './my-servers.config.js';
-import { ConfigType, MyServersConfig } from './connect.config.js';
+import { emptyMyServersConfig, MyServersConfig } from './connect.config.js';
 
 @Injectable()
-export class ConnectConfigPersister implements OnModuleInit, OnModuleDestroy {
-    constructor(private readonly configService: ConfigService<ConfigType, true>) {}
-
-    private logger = new Logger(ConnectConfigPersister.name);
-    get configPath() {
-        // PATHS_CONFIG_MODULES is a required environment variable.
-        // It is the directory where custom config files are stored.
-        return path.join(this.configService.getOrThrow('PATHS_CONFIG_MODULES'), 'connect.json');
-    }
-
-    async onModuleDestroy() {
-        await this.persist();
-    }
-
-    async onModuleInit() {
-        this.logger.verbose(`Config path: ${this.configPath}`);
-        await this.loadOrMigrateConfig();
-        // Persist changes to the config.
-        this.configService.changes$.pipe(bufferTime(25)).subscribe({
-            next: async (changes) => {
-                const connectConfigChanged = changes.some(({ path }) =>
-                    path.startsWith('connect.config')
-                );
-                if (connectConfigChanged) {
-                    await this.persist();
-                }
-            },
-            error: (err) => {
-                this.logger.error('Error receiving config changes:', err);
-            },
-        });
+export class ConnectConfigPersister extends ConfigFilePersister<MyServersConfig> {
+    constructor(configService: ConfigService) {
+        super(configService);
     }
 
     /**
-     * Persist the config to disk if the given data is different from the data on-disk.
-     * This helps preserve the boot flash drive's life by avoiding unnecessary writes.
-     *
-     * @param config - The config object to persist.
-     * @returns `true` if the config was persisted, `false` otherwise.
+     * @override
+     * @returns The name of the config file.
      */
-    async persist(config = this.configService.get<MyServersConfig>('connect.config')) {
-        try {
-            if (isEqual(config, await this.loadConfig())) {
-                this.logger.verbose(`Config is unchanged, skipping persistence`);
-                return false;
-            }
-        } catch (error) {
-            this.logger.error(error, `Error loading config (will overwrite file)`);
-        }
-        const data = JSON.stringify(config, null, 2);
-        this.logger.verbose(`Persisting config to ${this.configPath}: ${data}`);
-        try {
-            await writeFile(this.configPath, data);
-            this.logger.verbose(`Config persisted to ${this.configPath}`);
-            return true;
-        } catch (error) {
-            this.logger.error(error, `Error persisting config to '${this.configPath}'`);
-            return false;
-        }
+    fileName(): string {
+        return 'connect.json';
+    }
+
+    /**
+     * @override
+     * @returns The key of the config in the config service.
+     */
+    configKey(): string {
+        return 'connect.config';
+    }
+
+    /**
+     * @override
+     * @returns The default config object.
+     */
+    defaultConfig(): MyServersConfig {
+        return emptyMyServersConfig();
     }
 
     /**
      * Validate the config object.
+     * @override
      * @param config - The config object to validate.
      * @returns The validated config instance.
      */
@@ -89,49 +55,21 @@ export class ConnectConfigPersister implements OnModuleInit, OnModuleDestroy {
                 enableImplicitConversion: true,
             });
         }
-        await validateOrReject(instance);
+        await validateOrReject(instance, { whitelist: true });
         return instance;
     }
 
     /**
-     * Load the config from the filesystem, or migrate the legacy config file to the new config format.
-     * When unable to load or migrate the config, messages are logged at WARN level, but no other action is taken.
-     * @returns true if the config was loaded successfully, false otherwise.
+     * @override
+     * @returns The migrated config object.
      */
-    private async loadOrMigrateConfig() {
-        try {
-            const config = await this.loadConfig();
-            this.configService.set('connect.config', config);
-            this.logger.verbose(`Config loaded from ${this.configPath}`);
-            return true;
-        } catch (error) {
-            this.logger.warn(error, 'Error loading config');
-        }
-
-        try {
-            await this.migrateLegacyConfig();
-            return this.persist();
-        } catch (error) {
-            this.logger.warn('Error migrating legacy config:', error);
-        }
-
-        this.logger.error(
-            'Failed to load or migrate config from filesystem. Config is not persisted. Using defaults in-memory.'
-        );
-        return false;
+    async migrateConfig(): Promise<MyServersConfig> {
+        return await this.migrateLegacyConfig();
     }
 
-    /**
-     * Load the JSON config from the filesystem
-     * @throws {Error} - If the config file does not exist.
-     * @throws {Error} - If the config file is not parse-able.
-     * @throws {Error} - If the config file is not valid.
-     */
-    private async loadConfig(configFilePath = this.configPath) {
-        if (!existsSync(configFilePath))
-            throw new Error(`Config file does not exist at '${configFilePath}'`);
-        return this.validate(JSON.parse(readFileSync(configFilePath, 'utf8')));
-    }
+    /**-----------------------------------------------------
+     *  Helpers for migrating myservers.cfg to connect.json
+     *------------------------------------------------------**/
 
     /**
      * Migrate the legacy config file to the new config format.
@@ -143,8 +81,7 @@ export class ConnectConfigPersister implements OnModuleInit, OnModuleDestroy {
     private async migrateLegacyConfig(filePath?: string) {
         const myServersCfgFile = await this.readLegacyConfig(filePath);
         const legacyConfig = this.parseLegacyConfig(myServersCfgFile);
-        const newConfig = await this.convertLegacyConfig(legacyConfig);
-        this.configService.set('connect.config', newConfig);
+        return await this.convertLegacyConfig(legacyConfig);
     }
 
     /**

packages/unraid-api-plugin-generator/src/templates/config.persistence.ts

@@ -1,81 +1,25 @@
-import { Logger, Injectable, OnModuleInit } from "@nestjs/common";
-import { ConfigService } from "@nestjs/config";
-import { existsSync, readFileSync } from "fs";
-import { writeFile } from "fs/promises";
-import path from "path";
-import { bufferTime } from "rxjs/operators";
+import { Injectable } from "@nestjs/common";
+import { ConfigFilePersister } from "@unraid/shared/services/config-file.js"; // npm install @unraid/shared
 import { PluginNameConfig } from "./config.entity.js";
+import { ConfigService } from "@nestjs/config";
 
 @Injectable()
-export class PluginNameConfigPersister implements OnModuleInit {
-  constructor(private readonly configService: ConfigService) {}
-
-  private logger = new Logger(PluginNameConfigPersister.name);
-
-  /** the file path to the config file for this plugin */
-  get configPath() {
-    return path.join(
-      this.configService.get("PATHS_CONFIG_MODULES")!,
-      "plugin-name.json" // Use kebab-case for the filename
-    );
+export class PluginNameConfigPersister extends ConfigFilePersister<PluginNameConfig> {
+  constructor(configService: ConfigService) {
+    super(configService);
   }
 
-  onModuleInit() {
-    this.logger.debug(`Config path: ${this.configPath}`);
-    // Load the config from the file if it exists, otherwise initialize it with defaults.
-    if (existsSync(this.configPath)) {
-      try {
-        const configFromFile = JSON.parse(
-          readFileSync(this.configPath, "utf8")
-        );
-        this.configService.set("plugin-name", configFromFile);
-        this.logger.verbose(`Config loaded from ${this.configPath}`);
-      } catch (error) {
-        this.logger.error(
-          `Error reading or parsing config file at ${this.configPath}. Using defaults.`,
-          error
-        );
-        // If loading fails, ensure default config is set and persisted
-        this.persist();
-      }
-    } else {
-      this.logger.log(
-        `Config file ${this.configPath} does not exist. Writing default config...`
-      );
-      // Persist the default configuration provided by configFeature
-      this.persist();
-    }
-
-    // Automatically persist changes to the config file after a short delay.
-    this.configService.changes$.pipe(bufferTime(25)).subscribe({
-      next: async (changes) => {
-        const pluginNameConfigChanged = changes.some(({ path }) =>
-          path.startsWith("plugin-name.")
-        );
-        if (pluginNameConfigChanged) {
-          this.logger.verbose("Plugin config changed");
-          await this.persist();
-        }
-      },
-      error: (err) => {
-        this.logger.error("Error receiving config changes:", err);
-      },
-    });
+  fileName(): string {
+    return "plugin-name.json"; // Use kebab-case for the filename
   }
 
-  async persist(
-    config = this.configService.get<PluginNameConfig>("plugin-name")
-  ) {
-    const data = JSON.stringify(config, null, 2);
-    this.logger.verbose(`Persisting config to ${this.configPath}: ${data}`);
-    try {
-      await writeFile(this.configPath, data);
-      this.logger.verbose(`Config change persisted to ${this.configPath}`);
-    } catch (error) {
-      this.logger.error(
-        `Error persisting config to '${this.configPath}':`,
-        error
-      );
-    }
+  configKey(): string {
+    return "plugin-name";
+  }
+
+  defaultConfig(): PluginNameConfig {
+    // Return the default configuration for your plugin
+    // This should match the structure defined in your config.entity.ts
+    return {} as PluginNameConfig;
   }
 }

packages/unraid-shared/package.json

@@ -47,11 +47,13 @@
         "@graphql-tools/utils": "10.8.6",
         "@jsonforms/core": "3.6.0",
         "@nestjs/common": "11.1.3",
+        "@nestjs/config": "4.0.2",
         "@nestjs/graphql": "13.1.0",
         "class-validator": "0.14.2",
         "graphql": "16.11.0",
         "graphql-scalars": "1.24.2",
         "lodash-es": "4.17.21",
-        "nest-authz": "2.17.0"
+        "nest-authz": "2.17.0",
+        "rxjs": "7.8.2"
     }
 }

packages/unraid-shared/src/services/__tests__/config-file.test.ts

@@ -0,0 +1,495 @@
+import { expect, test, describe, beforeEach, afterEach } from "bun:test";
+import { Subject } from "rxjs";
+import { readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ConfigFilePersister } from "../config-file.js";
+
+/**
+ * TEST SCOPE: ConfigFilePersister NestJS Integration
+ *
+ * BEHAVIORS TESTED:
+ * • NestJS lifecycle integration (OnModuleInit, OnModuleDestroy)
+ * • Reactive config change subscription with 25ms buffering
+ * • ConfigService integration for path resolution and config storage
+ * • Automatic config loading with migration priority over defaults
+ * • Config change detection and selective persistence (matching configKey only)
+ * • Graceful error handling for all failure scenarios
+ * • Flash drive optimization through change detection
+ * • Standalone file access via getFileHandler() delegation
+ * • Proper cleanup of subscriptions and final state persistence
+ *
+ * INTEGRATION SCENARIOS:
+ * ✓ Module initialization with existing/missing/invalid config files
+ * ✓ Reactive config change processing with proper filtering
+ * ✓ Module destruction with subscription cleanup and final persistence
+ * ✓ Error resilience (file system errors, validation failures, service errors)
+ * ✓ Migration vs defaults priority during initialization
+ * ✓ Full application lifecycle from startup to shutdown
+ *
+ * COVERAGE FOCUS:
+ * • NestJS framework integration correctness
+ * • Reactive configuration management
+ * • Production-like error scenarios
+ * • Memory leak prevention (subscription management)
+ * • Data persistence guarantees during shutdown
+ *
+ * NOT TESTED (covered in other files):
+ * • Low-level file operations (ConfigFileHandler)
+ * • Abstract class behavior (ConfigDefinition)
+ */
+
+interface TestConfig {
+  name: string;
+  version: number;
+  enabled: boolean;
+  settings: {
+    timeout: number;
+    retries: number;
+  };
+}
+
+class TestConfigFilePersister extends ConfigFilePersister<TestConfig> {
+  constructor(configService: any) {
+    super(configService);
+  }
+
+  fileName(): string {
+    return "test-config.json";
+  }
+
+  configKey(): string {
+    return "testConfig";
+  }
+
+  defaultConfig(): TestConfig {
+    return {
+      name: "test",
+      version: 1,
+      enabled: false,
+      settings: {
+        timeout: 5000,
+        retries: 3,
+      },
+    };
+  }
+
+  async validate(config: object): Promise<TestConfig> {
+    const testConfig = config as TestConfig;
+    if (testConfig.version < 1) {
+      throw new Error("Invalid version: must be >= 1");
+    }
+    if (testConfig.settings.timeout < 1000) {
+      throw new Error("Invalid timeout: must be >= 1000");
+    }
+    return testConfig;
+  }
+
+  async migrateConfig(): Promise<TestConfig> {
+    return {
+      name: "migrated",
+      version: 2,
+      enabled: true,
+      settings: {
+        timeout: 3000,
+        retries: 5,
+      },
+    };
+  }
+}
+
+describe("ConfigFilePersister Integration Tests", () => {
+  let configService: any;
+  let persister: TestConfigFilePersister;
+  let testDir: string;
+  let configPath: string;
+  let changesSubject: Subject<any>;
+  let configStore: Record<string, any>;
+
+  beforeEach(async () => {
+    // Setup test directory
+    testDir = join(tmpdir(), `config-test-${Date.now()}`);
+    await mkdir(testDir, { recursive: true });
+    configPath = join(testDir, "test-config.json");
+
+    // Setup config store
+    configStore = {};
+
+    // Setup rxjs subject for config changes
+    changesSubject = new Subject();
+
+    // Mock ConfigService
+    configService = {
+      get: (key: string) => configStore[key],
+      set: (key: string, value: any) => {
+        configStore[key] = value;
+      },
+      getOrThrow: (key: string) => {
+        if (key === "PATHS_CONFIG_MODULES") return testDir;
+        throw new Error(`Config key ${key} not found`);
+      },
+      changes$: changesSubject.asObservable(),
+    };
+
+    persister = new TestConfigFilePersister(configService);
+  });
+
+  afterEach(async () => {
+    // Proper cleanup
+    changesSubject.complete();
+    await persister.onModuleDestroy?.();
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  test("configPath returns correct path", () => {
+    expect(persister.configPath()).toBe(configPath);
+  });
+
+  test("loads existing config from file", async () => {
+    const existingConfig = {
+      name: "existing",
+      version: 2,
+      enabled: true,
+      settings: {
+        timeout: 3000,
+        retries: 5,
+      },
+    };
+    await writeFile(configPath, JSON.stringify(existingConfig, null, 2));
+
+    await persister.onModuleInit();
+
+    // Should load existing config
+    expect(configStore.testConfig).toEqual(existingConfig);
+  });
+
+  test("handles invalid config by attempting migration", async () => {
+    const invalidConfig = {
+      name: "invalid",
+      version: 0, // Invalid version
+      enabled: true,
+      settings: {
+        timeout: 500, // Invalid timeout
+        retries: 5,
+      },
+    };
+    await writeFile(configPath, JSON.stringify(invalidConfig, null, 2));
+
+    await persister.onModuleInit();
+
+    // Should call migrate and set migrated config
+    expect(configStore.testConfig).toEqual({
+      name: "migrated",
+      version: 2,
+      enabled: true,
+      settings: {
+        timeout: 3000,
+        retries: 5,
+      },
+    });
+  });
+
+  test("persists config to file", async () => {
+    const config = {
+      name: "persist-test",
+      version: 2,
+      enabled: true,
+      settings: {
+        timeout: 4000,
+        retries: 4,
+      },
+    };
+
+    const result = await persister.persist(config);
+
+    expect(result).toBe(true);
+    const fileContent = await readFile(configPath, "utf8");
+    const parsedConfig = JSON.parse(fileContent);
+    expect(parsedConfig).toEqual(config);
+  });
+
+  test("skips persistence when config is unchanged", async () => {
+    const config = {
+      name: "unchanged",
+      version: 1,
+      enabled: false,
+      settings: {
+        timeout: 5000,
+        retries: 3,
+      },
+    };
+
+    // Write initial config
+    await writeFile(configPath, JSON.stringify(config, null, 2));
+
+    const result = await persister.persist(config);
+
+    expect(result).toBe(false);
+  });
+
+  test("loads and validates config from file", async () => {
+    const config = {
+      name: "file-test",
+      version: 3,
+      enabled: true,
+      settings: {
+        timeout: 2000,
+        retries: 1,
+      },
+    };
+    await writeFile(configPath, JSON.stringify(config));
+
+    const result = await persister.getFileHandler().readConfigFile();
+
+    expect(result).toEqual(config);
+  });
+
+  test("throws error when file doesn't exist", async () => {
+    await expect(persister.getFileHandler().readConfigFile()).rejects.toThrow(
+      "Config file does not exist"
+    );
+  });
+
+  test("throws error when file contains invalid JSON", async () => {
+    await writeFile(configPath, "{ invalid json");
+
+    await expect(persister.getFileHandler().readConfigFile()).rejects.toThrow();
+  });
+
+  test("throws error when config is invalid", async () => {
+    const invalidConfig = {
+      name: "invalid",
+      version: -1,
+      enabled: true,
+      settings: {
+        timeout: 100,
+        retries: 1,
+      },
+    };
+    await writeFile(configPath, JSON.stringify(invalidConfig));
+
+    await expect(persister.getFileHandler().readConfigFile()).rejects.toThrow(
+      "Invalid version"
+    );
+  });
+
+  test("base class migration throws not implemented error", async () => {
+    const basePersister = new (class extends ConfigFilePersister<TestConfig> {
+      fileName() {
+        return "base-test.json";
+      }
+      configKey() {
+        return "baseTest";
+      }
+      defaultConfig() {
+        return persister.defaultConfig();
+      }
+    })(configService);
+
+    await expect(basePersister.migrateConfig()).rejects.toThrow(
+      "Not implemented"
+    );
+  });
+
+  test("unsubscribes from config changes and persists final state", async () => {
+    await persister.onModuleInit();
+
+    // Setup final config state
+    configStore["testConfig"] = {
+      name: "final",
+      version: 4,
+      enabled: false,
+      settings: {
+        timeout: 1000,
+        retries: 10,
+      },
+    };
+
+    await persister.onModuleDestroy();
+
+    // Should persist final state
+    const fileContent = await readFile(configPath, "utf8");
+    const parsedConfig = JSON.parse(fileContent);
+    expect(parsedConfig.name).toBe("final");
+  });
+
+  test("handles destroy when not initialized", async () => {
+    // Should not throw error
+    await expect(persister.onModuleDestroy()).resolves.toBeUndefined();
+  });
+
+  test("config change subscription is properly set up", async () => {
+    // Pre-create config file to avoid migration
+    const initialConfig = persister.defaultConfig();
+    await writeFile(configPath, JSON.stringify(initialConfig, null, 2));
+
+    await persister.onModuleInit();
+
+    // Verify that the config observer is active by checking internal state
+    // This tests that the subscription was created without relying on timing
+    expect((persister as any).configObserver).toBeDefined();
+    expect((persister as any).configObserver.closed).toBe(false);
+
+    // Test that non-matching changes are ignored (synchronous test)
+    configStore["testConfig"] = persister.defaultConfig();
+    const initialFileContent = await readFile(configPath, "utf8");
+
+    // Emit a non-matching config change
+    changesSubject.next([{ path: "otherConfig.setting" }]);
+
+    // Wait briefly to ensure no processing occurs
+    await new Promise((resolve) => setTimeout(resolve, 30));
+
+    // File should remain unchanged
+    const afterFileContent = await readFile(configPath, "utf8");
+    expect(afterFileContent).toBe(initialFileContent);
+  });
+
+  test("ignores non-matching config changes", async () => {
+    // Pre-create config file
+    const initialConfig = persister.defaultConfig();
+    await writeFile(configPath, JSON.stringify(initialConfig, null, 2));
+
+    await persister.onModuleInit();
+
+    // Set initial config and write to file
+    configStore["testConfig"] = persister.defaultConfig();
+
+    // Get initial modification time
+    const stats1 = await import("fs/promises").then((fs) =>
+      fs.stat(configPath)
+    );
+
+    // Wait a bit to ensure timestamp difference
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    // Emit change for different config key
+    changesSubject.next([{ path: "otherConfig.setting" }]);
+
+    // Wait for buffer time
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // File should remain unchanged (same modification time)
+    const stats2 = await import("fs/promises").then((fs) =>
+      fs.stat(configPath)
+    );
+    expect(stats2.mtime).toEqual(stats1.mtime);
+  });
+
+  test("handles config service errors gracefully", async () => {
+    // Mock config service to throw error on get
+    const errorConfigService = {
+      ...configService,
+      get: () => {
+        throw new Error("Config service error");
+      },
+    };
+
+    const errorPersister = new TestConfigFilePersister(errorConfigService);
+
+    // Should still initialize (migration will be called due to no file)
+    await errorPersister.onModuleInit();
+
+    // Should have migrated config since get failed
+    const expectedMigrated = await errorPersister.migrateConfig();
+    expect(configStore.testConfig).toEqual(expectedMigrated);
+  });
+
+  test("handles persistence errors gracefully", async () => {
+    await persister.onModuleInit();
+
+    // Create a persister that points to invalid directory
+    const invalidPersister = new TestConfigFilePersister({
+      ...configService,
+      getOrThrow: (key: string) => {
+        if (key === "PATHS_CONFIG_MODULES")
+          return "/invalid/path/that/does/not/exist";
+        throw new Error(`Config key ${key} not found`);
+      },
+    });
+
+    const config = { ...persister.defaultConfig(), name: "error-test" };
+
+    // Should not throw despite write error
+    const result = await invalidPersister.persist(config);
+    expect(result).toBe(false);
+  });
+
+  test("migration priority over defaults when file doesn't exist", async () => {
+    // No file exists, should trigger migration path
+    await persister.onModuleInit();
+
+    // ConfigFilePersister prioritizes migration over defaults when file doesn't exist
+    expect(configStore.testConfig).toEqual({
+      name: "migrated",
+      version: 2,
+      enabled: true,
+      settings: {
+        timeout: 3000,
+        retries: 5,
+      },
+    });
+
+    // Should persist migrated config to file
+    const fileContent = await readFile(configPath, "utf8");
+    const parsedConfig = JSON.parse(fileContent);
+    expect(parsedConfig).toEqual({
+      name: "migrated",
+      version: 2,
+      enabled: true,
+      settings: {
+        timeout: 3000,
+        retries: 5,
+      },
+    });
+  });
+
+  test("full lifecycle integration", async () => {
+    // Initialize - will use migration since no file exists
+    await persister.onModuleInit();
+
+    // Verify initial state (migrated, not defaults)
+    expect(configStore.testConfig).toEqual({
+      name: "migrated",
+      version: 2,
+      enabled: true,
+      settings: {
+        timeout: 3000,
+        retries: 5,
+      },
+    });
+
+    // Simulate config change
+    configStore["testConfig"] = {
+      name: "lifecycle-test",
+      version: 5,
+      enabled: true,
+      settings: {
+        timeout: 1500,
+        retries: 7,
+      },
+    };
+
+    // Trigger change notification
+    changesSubject.next([{ path: "testConfig.enabled" }]);
+
+    // Wait for persistence
+    await new Promise((resolve) => setTimeout(resolve, 50));
+
+    // Cleanup
+    await persister.onModuleDestroy();
+
+    // Verify final persisted state
+    const fileContent = await readFile(configPath, "utf8");
+    const parsedConfig = JSON.parse(fileContent);
+    expect(parsedConfig).toEqual({
+      name: "lifecycle-test",
+      version: 5,
+      enabled: true,
+      settings: {
+        timeout: 1500,
+        retries: 7,
+      },
+    });
+  });
+});

packages/unraid-shared/src/services/config-file.ts

@@ -0,0 +1,147 @@
+import {
+  Logger,
+  type OnModuleDestroy,
+  type OnModuleInit,
+} from "@nestjs/common";
+import type { ConfigService } from "@nestjs/config";
+import path from "node:path";
+
+import { bufferTime } from "rxjs/operators";
+import type { Subscription } from "rxjs";
+import { ConfigFileHandler } from "../util/config-file-handler.js";
+import { ConfigDefinition } from "../util/config-definition.js";
+
+/**
+ * Abstract base class for persisting configuration objects to JSON files.
+ *
+ * Provides NestJS integration with reactive config updates, standalone file operations,
+ * and lifecycle management with automatic persistence.
+ *
+ * @template T The configuration object type that extends object
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class MyConfigPersister extends ConfigFilePersister<MyConfig> {
+ *   constructor(configService: ConfigService) {
+ *     super(configService);
+ *   }
+ *
+ *   fileName() { return "my-config.json"; }
+ *   configKey() { return "myConfig"; }
+ *   defaultConfig(): MyConfig {
+ *     return { enabled: false, timeout: 5000 };
+ *   }
+ * }
+ * ```
+ */
+export abstract class ConfigFilePersister<T extends object>
+  extends ConfigDefinition<T>
+  implements OnModuleInit, OnModuleDestroy
+{
+  private configObserver?: Subscription;
+  private fileHandler: ConfigFileHandler<T>;
+
+  /**
+   * Creates a new ConfigFilePersister instance.
+   * 
+   * @param configService The NestJS ConfigService instance for reactive config management
+   */
+  constructor(protected readonly configService: ConfigService) {
+    super();
+    this.logger = new Logger(`ConfigFilePersister:${this.fileName()}`);
+    this.fileHandler = new ConfigFileHandler(this);
+  }
+
+  /**
+   * Returns the configuration key used in the ConfigService.
+   *
+   * This key is used to:
+   * - Store/retrieve config from the ConfigService
+   * - Filter config change events to only process relevant changes
+   * - Namespace configuration to avoid conflicts
+   *
+   * @returns The config key string (e.g., "userPreferences", "apiSettings")
+   * @example "myModuleConfig"
+   */
+  abstract configKey(): string;
+
+  /**
+   * Returns the absolute path to the configuration file.
+   * Combines `PATHS_CONFIG_MODULES` environment variable with the filename.
+   * 
+   * @throws Error if `PATHS_CONFIG_MODULES` environment variable is not set
+   */
+  configPath(): string {
+    return path.join(
+      this.configService.getOrThrow("PATHS_CONFIG_MODULES"),
+      this.fileName()
+    );
+  }
+
+  /**
+   * Returns a standalone ConfigFileHandler for direct file operations outside NestJS.
+   */
+  getFileHandler(): ConfigFileHandler<T> {
+    return this.fileHandler;
+  }
+
+  /**
+   * NestJS lifecycle hook for cleanup.
+   * Unsubscribes from config changes and persists final state.
+   */
+  async onModuleDestroy() {
+    this.configObserver?.unsubscribe();
+    await this.persist();
+  }
+
+  /**
+   * NestJS lifecycle hook for initialization.
+   * Loads config from disk and sets up reactive change subscription.
+   */
+  async onModuleInit() {
+    this.logger.verbose(`Config path: ${this.configPath()}`);
+    await this.loadOrMigrateConfig();
+
+    this.configObserver = this.configService.changes$
+      .pipe(bufferTime(25))
+      .subscribe({
+        next: async (changes) => {
+          const configChanged = changes.some(({ path }) =>
+            path?.startsWith(this.configKey())
+          );
+          if (configChanged) {
+            await this.persist();
+          }
+        },
+        error: (err) => {
+          this.logger.error("Error receiving config changes:", err);
+        },
+      });
+  }
+
+  /**
+   * Persists configuration to disk with change detection optimization.
+   * 
+   * @param config - The config object to persist (defaults to current config from service)
+   * @returns `true` if persisted to disk, `false` if skipped or failed
+   */
+  async persist(
+    config = this.configService.get(this.configKey())
+  ): Promise<boolean> {
+    if (!config) {
+      this.logger.warn(`Cannot persist undefined config`);
+      return false;
+    }
+    return await this.fileHandler.writeConfigFile(config);
+  }
+
+  /**
+   * Load or migrate configuration and set it in ConfigService.
+   */
+  private async loadOrMigrateConfig() {
+    const config = await this.fileHandler.loadConfig();
+    this.configService.set(this.configKey(), config);
+    return this.persist(config);
+  }
+}

packages/unraid-shared/src/util/__tests__/config-definition.test.ts

@@ -0,0 +1,192 @@
+import { expect, test, describe, beforeEach } from "bun:test";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ConfigDefinition } from "../config-definition.js";
+
+/**
+ * TEST SCOPE: ConfigDefinition Abstract Base Class
+ *
+ * BEHAVIORS TESTED:
+ * • Core abstract method implementations (fileName, configPath, defaultConfig)
+ * • Default validation behavior (passthrough without transformation)
+ * • Custom validation with data transformation and error throwing
+ * • Default migration behavior (throws "Not implemented" error)
+ * • Custom migration implementation with success and failure scenarios
+ * • Error propagation from validation and migration methods
+ *
+ * COVERAGE FOCUS:
+ * • Abstract class contract enforcement
+ * • Extension point behavior (validate, migrate methods)
+ * • Error handling patterns for implementors
+ * • Type safety and configuration structure validation
+ *
+ * NOT TESTED (covered in other files):
+ * • File I/O operations (ConfigFileHandler)
+ * • NestJS integration (ConfigFilePersister)
+ * • Reactive config changes
+ */
+
+interface TestConfig {
+  name: string;
+  version: number;
+  enabled: boolean;
+  timeout: number;
+}
+
+class TestConfigDefinition extends ConfigDefinition<TestConfig> {
+  constructor(private configDir: string, loggerName?: string) {
+    super(loggerName);
+  }
+
+  fileName(): string {
+    return "test-config.json";
+  }
+
+  configPath(): string {
+    return join(this.configDir, this.fileName());
+  }
+
+  defaultConfig(): TestConfig {
+    return {
+      name: "test",
+      version: 1,
+      enabled: false,
+      timeout: 5000,
+    };
+  }
+}
+
+class ValidatingConfigDefinition extends TestConfigDefinition {
+  async validate(config: object): Promise<TestConfig> {
+    const testConfig = config as TestConfig;
+
+    if (typeof testConfig.name !== "string" || testConfig.name.length === 0) {
+      throw new Error("Name must be a non-empty string");
+    }
+
+    if (typeof testConfig.version !== "number" || testConfig.version < 1) {
+      throw new Error("Version must be a number >= 1");
+    }
+
+    if (typeof testConfig.timeout !== "number" || testConfig.timeout < 1000) {
+      throw new Error("Timeout must be a number >= 1000");
+    }
+
+    // Test data transformation
+    return {
+      ...testConfig,
+      name: testConfig.name.trim(),
+      timeout: Math.max(testConfig.timeout, 1000),
+    };
+  }
+}
+
+class MigratingConfigDefinition extends TestConfigDefinition {
+  public migrationShouldFail = false;
+  public migrationCallCount = 0;
+
+  async migrateConfig(): Promise<TestConfig> {
+    this.migrationCallCount++;
+
+    if (this.migrationShouldFail) {
+      throw new Error("Migration failed");
+    }
+
+    return {
+      name: "migrated",
+      version: 2,
+      enabled: true,
+      timeout: 3000,
+    };
+  }
+}
+
+describe("ConfigDefinition", () => {
+  let testDir: string;
+  let configDefinition: TestConfigDefinition;
+
+  beforeEach(() => {
+    testDir = join(tmpdir(), `config-def-test-${Date.now()}`);
+    configDefinition = new TestConfigDefinition(testDir);
+  });
+
+  describe("Core Functionality", () => {
+    test("abstract methods are implemented correctly", () => {
+      expect(configDefinition.fileName()).toBe("test-config.json");
+      expect(configDefinition.configPath()).toBe(
+        join(testDir, "test-config.json")
+      );
+      expect(configDefinition.defaultConfig()).toEqual({
+        name: "test",
+        version: 1,
+        enabled: false,
+        timeout: 5000,
+      });
+    });
+
+    test("default validation is passthrough", async () => {
+      const config = { name: "test", version: 2, enabled: true, timeout: 3000 };
+      const result = await configDefinition.validate(config);
+      expect(result).toEqual(config);
+    });
+  });
+
+  describe("Validation Behavior", () => {
+    test("validation can transform and validate config", async () => {
+      const validatingDefinition = new ValidatingConfigDefinition(testDir);
+      const config = {
+        name: "  test-name  ", // Should be trimmed
+        version: 2,
+        enabled: true,
+        timeout: 1500,
+      };
+
+      const result = await validatingDefinition.validate(config);
+      expect(result.name).toBe("test-name"); // Trimmed
+      expect(result.timeout).toBe(1500);
+    });
+
+    test("validation errors are thrown for invalid configs", async () => {
+      const validatingDefinition = new ValidatingConfigDefinition(testDir);
+      const invalidConfig = {
+        name: "",
+        version: 0,
+        enabled: false,
+        timeout: 500,
+      };
+
+      await expect(
+        validatingDefinition.validate(invalidConfig)
+      ).rejects.toThrow();
+    });
+  });
+
+  describe("Migration Behavior", () => {
+    test("default migration throws not implemented error", async () => {
+      await expect(configDefinition.migrateConfig()).rejects.toThrow(
+        "Not implemented"
+      );
+    });
+
+    test("custom migration works when implemented", async () => {
+      const migratingDefinition = new MigratingConfigDefinition(testDir);
+      const result = await migratingDefinition.migrateConfig();
+
+      expect(result).toEqual({
+        name: "migrated",
+        version: 2,
+        enabled: true,
+        timeout: 3000,
+      });
+    });
+
+    test("migration failures are propagated as errors", async () => {
+      const migratingDefinition = new MigratingConfigDefinition(testDir);
+      migratingDefinition.migrationShouldFail = true;
+
+      await expect(migratingDefinition.migrateConfig()).rejects.toThrow(
+        "Migration failed"
+      );
+    });
+  });
+});

packages/unraid-shared/src/util/__tests__/config-file-handler.test.ts

@@ -0,0 +1,466 @@
+import { expect, test, describe, beforeEach, afterEach } from "bun:test";
+import { readFile, writeFile, mkdir, rm } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { ConfigFileHandler } from "../config-file-handler.js";
+import { ConfigDefinition } from "../config-definition.js";
+
+/**
+ * TEST SCOPE: ConfigFileHandler Standalone File Operations
+ *
+ * BEHAVIORS TESTED:
+ * • Configuration loading with error recovery cascade:
+ *   - File exists & valid → load directly
+ *   - File read fails → attempt migration → fallback to defaults
+ *   - File valid but merged config fails validation → attempt migration
+ *   - Migration succeeds but merged result fails validation → fallback to defaults
+ *   - Migration fails → fallback to defaults
+ * • File I/O operations (read, write) with validation
+ * • Flash drive optimization (skip writes when config unchanged)
+ * • Partial config updates with deep merging
+ * • Error resilience (invalid JSON, validation failures, file system errors)
+ * • End-to-end workflows (load → update → reload cycles)
+ *
+ * CRITICAL ERROR RECOVERY PATHS:
+ * ✓ read failed → migration failed → defaults written
+ * ✓ read failed → migration succeeded but combo validation failed → defaults written
+ * ✓ read succeeded but merged validation failed → migration → recovery
+ *
+ * COVERAGE FOCUS:
+ * • Data integrity during all error scenarios
+ * • Performance optimization (change detection)
+ * • Configuration persistence reliability
+ * • Validation error handling at all stages
+ *
+ * NOT TESTED (covered in other files):
+ * • NestJS integration and reactive changes (ConfigFilePersister)
+ * • Abstract class behavior (ConfigDefinition)
+ */
+
+interface TestConfig {
+  name: string;
+  version: number;
+  enabled: boolean;
+  timeout: number;
+  maxRetries?: number; // Optional field for testing merge validation
+}
+
+class TestConfigDefinition extends ConfigDefinition<TestConfig> {
+  public migrationCallCount = 0;
+  public migrationShouldFail = false;
+  public validationShouldFail = false;
+  public mergeValidationShouldFail = false; // New flag for the edge case
+
+  constructor(private configDir: string) {
+    super("TestConfigDefinition");
+  }
+
+  fileName(): string {
+    return "test-config.json";
+  }
+
+  configPath(): string {
+    return join(this.configDir, this.fileName());
+  }
+
+  defaultConfig(): TestConfig {
+    return {
+      name: "test",
+      version: 1,
+      enabled: false,
+      timeout: 5000,
+      maxRetries: 3, // Default includes maxRetries
+    };
+  }
+
+  async validate(config: object): Promise<TestConfig> {
+    if (this.validationShouldFail) {
+      throw new Error("Validation failed");
+    }
+
+    const testConfig = config as TestConfig;
+
+    // Basic validation
+    if (typeof testConfig.version !== "number" || testConfig.version < 1) {
+      throw new Error("Invalid version: must be >= 1");
+    }
+
+    if (typeof testConfig.timeout !== "number" || testConfig.timeout < 1000) {
+      throw new Error("Invalid timeout: must be >= 1000");
+    }
+
+    // Critical edge case: maxRetries validation that could fail after merge
+    if (testConfig.maxRetries !== undefined && testConfig.maxRetries < 0) {
+      throw new Error("Invalid maxRetries: must be >= 0");
+    }
+
+    // Simulate a validation that fails specifically for merged configs
+    if (this.mergeValidationShouldFail && testConfig.maxRetries === -1) {
+      throw new Error("Merged validation failed: maxRetries cannot be -1");
+    }
+
+    return testConfig;
+  }
+
+  async migrateConfig(): Promise<TestConfig> {
+    this.migrationCallCount++;
+
+    if (this.migrationShouldFail) {
+      throw new Error("Migration failed");
+    }
+
+    return {
+      name: "migrated",
+      version: 2,
+      enabled: true,
+      timeout: 3000,
+      maxRetries: 5,
+    };
+  }
+}
+
+describe("ConfigFileHandler", () => {
+  let testDir: string;
+  let configPath: string;
+  let configDefinition: TestConfigDefinition;
+  let fileHandler: ConfigFileHandler<TestConfig>;
+
+  beforeEach(async () => {
+    testDir = join(tmpdir(), `config-handler-test-${Date.now()}`);
+    await mkdir(testDir, { recursive: true });
+    configPath = join(testDir, "test-config.json");
+
+    configDefinition = new TestConfigDefinition(testDir);
+    fileHandler = new ConfigFileHandler(configDefinition);
+  });
+
+  afterEach(async () => {
+    await rm(testDir, { recursive: true, force: true });
+  });
+
+  describe("Critical loadConfig Scenarios", () => {
+    test("loads valid config from file successfully", async () => {
+      const validConfig = {
+        name: "existing",
+        version: 2,
+        enabled: true,
+        timeout: 3000,
+        maxRetries: 2,
+      };
+      await writeFile(configPath, JSON.stringify(validConfig));
+
+      const result = await fileHandler.loadConfig();
+      expect(result.name).toBe("existing");
+      expect(result.version).toBe(2);
+      expect(result.maxRetries).toBe(2);
+    });
+
+    test("falls back to migration when file doesn't exist", async () => {
+      const result = await fileHandler.loadConfig();
+
+      expect(configDefinition.migrationCallCount).toBe(1);
+      expect(result.name).toBe("migrated");
+      expect(result.version).toBe(2);
+
+      // Should persist migrated config
+      const persistedContent = await readFile(configPath, "utf8");
+      const persistedConfig = JSON.parse(persistedContent);
+      expect(persistedConfig.name).toBe("migrated");
+    });
+
+    test("falls back to defaults when migration fails", async () => {
+      configDefinition.migrationShouldFail = true;
+
+      const result = await fileHandler.loadConfig();
+
+      expect(result.name).toBe("test"); // From defaults
+      expect(result.version).toBe(1);
+    });
+
+    test("CRITICAL: file valid but merged config fails validation - triggers migration", async () => {
+      // File contains valid config but defaults have invalid maxRetries
+      const fileConfig = {
+        name: "file-valid",
+        version: 2,
+        enabled: true,
+        timeout: 2000,
+        // Note: no maxRetries in file
+      };
+      await writeFile(configPath, JSON.stringify(fileConfig));
+
+      // Override defaults to include invalid value that fails after merge
+      const originalDefaults = configDefinition.defaultConfig;
+      configDefinition.defaultConfig = () => ({
+        name: "test",
+        version: 1,
+        enabled: false,
+        timeout: 5000,
+        maxRetries: -1, // This will cause merged validation to fail!
+      });
+
+      configDefinition.mergeValidationShouldFail = true;
+
+      // This should NOT throw - should catch validation error and migrate
+      const result = await fileHandler.loadConfig();
+
+      // Should have triggered migration due to validation failure
+      expect(configDefinition.migrationCallCount).toBe(1);
+      expect(result.name).toBe("migrated");
+      expect(result.maxRetries).toBe(5); // From migration
+
+      // Restore original method
+      configDefinition.defaultConfig = originalDefaults;
+    });
+
+    test("handles invalid JSON by migrating", async () => {
+      await writeFile(configPath, "{ invalid json");
+
+      const result = await fileHandler.loadConfig();
+      expect(configDefinition.migrationCallCount).toBe(1);
+      expect(result.name).toBe("migrated");
+    });
+
+    test("CRITICAL: read failed → migration succeeded but merged validation fails → defaults used", async () => {
+      // No file exists (read will fail)
+      // Migration will succeed but return config that passes its own validation
+      // But when merged with defaults, the result fails validation
+
+      // Create a special definition for this edge case
+      class SpecialMigrationDefinition extends TestConfigDefinition {
+        async migrateConfig(): Promise<TestConfig> {
+          this.migrationCallCount++;
+          // Return a config that's valid on its own
+          return {
+            name: "migration-success",
+            version: 2,
+            enabled: true,
+            timeout: 2000,
+            // Missing maxRetries - will be merged from defaults
+          };
+        }
+
+        async validate(config: object): Promise<TestConfig> {
+          const testConfig = config as TestConfig;
+
+          // Basic validation
+          if (
+            typeof testConfig.version !== "number" ||
+            testConfig.version < 1
+          ) {
+            throw new Error("Invalid version: must be >= 1");
+          }
+
+          if (
+            typeof testConfig.timeout !== "number" ||
+            testConfig.timeout < 1000
+          ) {
+            throw new Error("Invalid timeout: must be >= 1000");
+          }
+
+          // This validation will fail after merge when maxRetries comes from defaults
+          if (
+            testConfig.maxRetries !== undefined &&
+            testConfig.name === "migration-success" &&
+            testConfig.maxRetries === 3
+          ) {
+            throw new Error(
+              "Special validation failure: migration + defaults combo invalid"
+            );
+          }
+
+          return testConfig;
+        }
+      }
+
+      const specialDefinition = new SpecialMigrationDefinition(testDir);
+      const specialHandler = new ConfigFileHandler(specialDefinition);
+
+      // Should NOT throw - should catch validation error and fall back to defaults
+      const result = await specialHandler.loadConfig();
+
+      // Should have attempted migration
+      expect(specialDefinition.migrationCallCount).toBe(1);
+
+      // But result should be from defaults due to validation failure
+      expect(result.name).toBe("test"); // From defaults
+      expect(result.version).toBe(1); // From defaults
+      expect(result.maxRetries).toBe(3); // From defaults
+    });
+  });
+
+  describe("File Operations", () => {
+    test("readConfigFile validates config from disk", async () => {
+      const config = {
+        name: "read-test",
+        version: 2,
+        enabled: true,
+        timeout: 2000,
+      };
+      await writeFile(configPath, JSON.stringify(config));
+
+      const result = await fileHandler.readConfigFile();
+      expect(result).toEqual(config);
+    });
+
+    test("readConfigFile throws for invalid config", async () => {
+      const invalidConfig = {
+        name: "invalid",
+        version: -1,
+        enabled: true,
+        timeout: 2000,
+      };
+      await writeFile(configPath, JSON.stringify(invalidConfig));
+
+      await expect(fileHandler.readConfigFile()).rejects.toThrow(
+        "Invalid version"
+      );
+    });
+
+    test("writeConfigFile persists config to disk", async () => {
+      const config = {
+        name: "write-test",
+        version: 3,
+        enabled: true,
+        timeout: 4000,
+      };
+
+      const success = await fileHandler.writeConfigFile(config);
+      expect(success).toBe(true);
+
+      const fileContent = await readFile(configPath, "utf8");
+      expect(JSON.parse(fileContent)).toEqual(config);
+    });
+
+    test("writeConfigFile skips write when config unchanged (flash drive optimization)", async () => {
+      const config = {
+        name: "unchanged",
+        version: 1,
+        enabled: false,
+        timeout: 5000,
+      };
+      await writeFile(configPath, JSON.stringify(config, null, 2));
+
+      const success = await fileHandler.writeConfigFile(config);
+      expect(success).toBe(false); // Skipped
+    });
+
+    test("writeConfigFile proceeds with write when existing file has invalid JSON", async () => {
+      // Pre-existing file with invalid JSON
+      await writeFile(configPath, "{ invalid json");
+
+      const config = {
+        name: "write-despite-invalid",
+        version: 2,
+        enabled: true,
+        timeout: 4000,
+      };
+
+      // Should proceed with write despite invalid existing file
+      const success = await fileHandler.writeConfigFile(config);
+      expect(success).toBe(true);
+
+      // Should have written valid config
+      const fileContent = await readFile(configPath, "utf8");
+      expect(JSON.parse(fileContent)).toEqual(config);
+    });
+
+    test("writeConfigFile handles validation errors", async () => {
+      configDefinition.validationShouldFail = true;
+      const config = {
+        name: "invalid",
+        version: 1,
+        enabled: false,
+        timeout: 5000,
+      };
+
+      const success = await fileHandler.writeConfigFile(config);
+      expect(success).toBe(false);
+    });
+  });
+
+  describe("updateConfig Operations", () => {
+    test("updates existing config with partial changes", async () => {
+      const existing = {
+        name: "existing",
+        version: 1,
+        enabled: false,
+        timeout: 5000,
+      };
+      await writeFile(configPath, JSON.stringify(existing));
+
+      const success = await fileHandler.updateConfig({
+        enabled: true,
+        timeout: 8000,
+      });
+      expect(success).toBe(true);
+
+      const updated = JSON.parse(await readFile(configPath, "utf8"));
+      expect(updated.name).toBe("existing"); // Preserved
+      expect(updated.enabled).toBe(true); // Updated
+      expect(updated.timeout).toBe(8000); // Updated
+    });
+
+    test("creates config when file doesn't exist (via migration)", async () => {
+      const updates = { name: "new", enabled: true };
+
+      const success = await fileHandler.updateConfig(updates);
+      expect(success).toBe(true);
+
+      const created = JSON.parse(await readFile(configPath, "utf8"));
+      expect(created.name).toBe("new"); // From update
+      expect(created.version).toBe(2); // From migration (no file existed)
+    });
+
+    test("handles validation errors during update", async () => {
+      const existing = {
+        name: "existing",
+        version: 1,
+        enabled: false,
+        timeout: 5000,
+      };
+      await writeFile(configPath, JSON.stringify(existing));
+
+      const success = await fileHandler.updateConfig({ version: -1 }); // Invalid
+      expect(success).toBe(false);
+
+      // Original should be unchanged
+      const unchanged = JSON.parse(await readFile(configPath, "utf8"));
+      expect(unchanged.version).toBe(1);
+    });
+  });
+
+  describe("Error Resilience", () => {
+    test("handles write errors gracefully", async () => {
+      const invalidDefinition = new TestConfigDefinition(
+        "/invalid/readonly/path"
+      );
+      const invalidHandler = new ConfigFileHandler(invalidDefinition);
+
+      const config = {
+        name: "error-test",
+        version: 1,
+        enabled: false,
+        timeout: 5000,
+      };
+      const success = await invalidHandler.writeConfigFile(config);
+      expect(success).toBe(false);
+    });
+  });
+
+  describe("End-to-End Workflow", () => {
+    test("complete workflow: load -> update -> reload", async () => {
+      // 1. Load (triggers migration since no file)
+      let config = await fileHandler.loadConfig();
+      expect(config.name).toBe("migrated");
+
+      // 2. Update
+      await fileHandler.updateConfig({ name: "workflow-test", timeout: 6000 });
+
+      // 3. Reload from disk
+      config = await fileHandler.readConfigFile();
+      expect(config.name).toBe("workflow-test");
+      expect(config.timeout).toBe(6000);
+      expect(config.version).toBe(2); // Preserved from migration
+    });
+  });
+});

packages/unraid-shared/src/util/config-definition.ts

@@ -0,0 +1,100 @@
+import { Logger } from "@nestjs/common";
+
+/**
+ * Abstract base class for configuration behavior without NestJS dependencies.
+ * Provides core configuration logic including file path resolution, defaults,
+ * validation, and migration support.
+ *
+ * @template T The configuration object type that extends object
+ *
+ * @example
+ * ```typescript
+ * interface MyConfig {
+ *   enabled: boolean;
+ *   timeout: number;
+ * }
+ *
+ * class MyConfigDefinition extends ConfigDefinition<MyConfig> {
+ *   constructor(private configDir: string) {
+ *     super('MyConfig');
+ *   }
+ *
+ *   fileName() { return "my-config.json"; }
+ *   configPath() { return path.join(this.configDir, this.fileName()); }
+ *   defaultConfig(): MyConfig { return { enabled: false, timeout: 5000 }; }
+ *
+ *   async validate(config: object): Promise<MyConfig> {
+ *     const myConfig = config as MyConfig;
+ *     if (myConfig.timeout < 1000) throw new Error("Timeout too low");
+ *     return myConfig;
+ *   }
+ * }
+ * ```
+ */
+export abstract class ConfigDefinition<T extends object> {
+  protected logger: Logger;
+
+  /**
+   * @param loggerName Optional custom logger name (defaults to generic name)
+   */
+  constructor(loggerName?: string) {
+    this.logger = new Logger(loggerName ?? `ConfigDefinition:${this.fileName()}`);
+  }
+
+  /**
+   * Returns the filename for the configuration file.
+   *
+   * @returns The name of the config file (e.g., "my-config.json")
+   * @example "user-preferences.json"
+   */
+  abstract fileName(): string;
+
+  /**
+   * Returns the absolute path to the configuration file.
+   */
+  abstract configPath(): string;
+
+  /**
+   * Returns the default configuration object.
+   * Used as fallback when migration fails or as base for merging.
+   */
+  abstract defaultConfig(): T;
+
+  /**
+   * Validates and transforms a configuration object.
+   *
+   * Override to implement custom validation logic such as:
+   * - Schema validation
+   * - Range checking for numeric values
+   * - Data transformation/normalization
+   *
+   * @param config - The raw config object to validate
+   * @returns The validated and potentially transformed config
+   * @throws Error if the config is invalid
+   */
+  async validate(config: object): Promise<T> {
+    return config as T;
+  }
+
+  /**
+   * Migrates legacy or corrupted configuration to the current format.
+   *
+   * Called when:
+   * - Config file doesn't exist (first-time setup)
+   * - Config file contains invalid JSON
+   * - Config validation fails
+   *
+   * Override to provide custom migration logic for legacy formats,
+   * version upgrades, or first-time installations.
+   * 
+   * Note:
+   * - Backwards-compatible updates such as field additions are better handled via `defaultConfig()`
+   * because `defaultConfig()` is merged with the loaded config.
+   *
+   * @returns Migrated configuration object
+   * @throws Error if migration is not possible (falls back to defaults)
+   */
+  async migrateConfig(): Promise<T> {
+    throw new Error("Not implemented");
+  }
+}

packages/unraid-shared/src/util/config-file-handler.ts

@@ -0,0 +1,157 @@
+import { Logger } from "@nestjs/common";
+import { readFile, writeFile } from "node:fs/promises";
+import { isEqual } from "lodash-es";
+import { ConfigDefinition } from "./config-definition.js";
+import { fileExists } from "./file.js";
+
+/**
+ * Standalone configuration file handler that works with any ConfigDefinition.
+ * Can be used independently of NestJS DI container.
+ *
+ * This class provides robust file operations with the following features:
+ * - **Migration Priority**: When files don't exist, migration is attempted before falling back to defaults
+ * - **Change Detection**: Uses deep equality checks to avoid unnecessary disk writes (flash drive optimization)
+ * - **Error Resilience**: Graceful handling of file system errors, JSON parsing failures, and validation errors
+ * - **Atomic Operations**: Individual methods for specific file operations (read, write, update)
+ *
+ * @template T The configuration object type that extends object
+ *
+ * @example
+ * ```typescript
+ * const configDef = new MyConfigDefinition('/etc/myapp');
+ * const fileHandler = new ConfigFileHandler(configDef);
+ *
+ * // Load config with migration fallback
+ * const config = await fileHandler.loadConfig();
+ *
+ * // Update specific properties
+ * await fileHandler.updateConfig({ enabled: true });
+ * ```
+ */
+export class ConfigFileHandler<T extends object> {
+  private readonly logger: Logger;
+
+  /**
+   * @param definition The configuration definition that provides behavior
+   */
+  constructor(private readonly definition: ConfigDefinition<T>) {
+    this.logger = new Logger(`ConfigFileHandler:${definition.fileName()}`);
+  }
+
+  /**
+   * Loads configuration from file, with migration fallback.
+   *
+   * Strategy:
+   * 1. Load and validate existing config
+   * 2. If loading fails, attempt migration
+   * 3. If migration fails, use defaults
+   * 4. Merge result with defaults and persist if migrated
+   *
+   * @returns Complete configuration object
+   */
+  async loadConfig(): Promise<T> {
+    const defaultConfig = this.definition.defaultConfig();
+
+    try {
+      const fileConfig = await this.readConfigFile();
+      return await this.definition.validate({
+        ...defaultConfig,
+        ...fileConfig,
+      });
+    } catch (error) {
+      this.logger.warn(error, "Error loading config. Attempting to migrate...");
+
+      try {
+        const migratedConfig = await this.definition.migrateConfig();
+        const mergedConfig = await this.definition.validate({
+          ...defaultConfig,
+          ...migratedConfig,
+        });
+        // Persist migrated config for future loads
+        await this.writeConfigFile(mergedConfig);
+        return mergedConfig;
+      } catch (migrationError) {
+        this.logger.warn("Migration failed. Using defaults.", migrationError);
+        return defaultConfig;
+      }
+    }
+  }
+
+  /**
+   * Reads and validates configuration from file.
+   *
+   * @param configPath - Path to config file (defaults to `configPath()`)
+   * @returns Validated configuration object from disk
+   * @throws Error if file doesn't exist, contains invalid JSON, or fails validation
+   */
+  async readConfigFile(configPath = this.definition.configPath()): Promise<T> {
+    if (!(await fileExists(configPath))) {
+      throw new Error(`Config file does not exist at '${configPath}'`);
+    }
+    const content = await readFile(configPath, "utf8");
+    const parsed = JSON.parse(content);
+    return await this.definition.validate(parsed);
+  }
+
+  /**
+   * Writes configuration to file with change detection optimization.
+   * Uses deep equality checks to avoid unnecessary writes.
+   *
+   * @param config - The config object to write to disk
+   * @returns `true` if written to disk, `false` if skipped or failed
+   */
+  async writeConfigFile(config: T): Promise<boolean> {
+    try {
+      config = await this.definition.validate(config);
+    } catch (error) {
+      this.logger.error(error, `Cannot write invalid config`);
+      return false;
+    }
+
+    // Skip write if config is unchanged (flash drive optimization)
+    try {
+      const existingConfig = await this.readConfigFile();
+      if (isEqual(config, existingConfig)) {
+        this.logger.verbose(`Config is unchanged, skipping write`);
+        return false;
+      }
+    } catch (error) {
+      // File doesn't exist or is invalid, proceed with write
+      this.logger.verbose(`Existing config unreadable, proceeding with write`);
+    }
+
+    try {
+      const data = JSON.stringify(config, null, 2);
+      this.logger.verbose("Writing config");
+      await writeFile(this.definition.configPath(), data);
+      return true;
+    } catch (error) {
+      this.logger.error(
+        error,
+        `Error writing config to '${this.definition.configPath()}'`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Updates configuration by merging with existing config.
+   * Loads current config, shallow merges updates, and writes back to disk.
+   *
+   * @param updates - Partial configuration object with properties to update
+   * @returns `true` if updated on disk, `false` if failed or no changes
+   */
+  async updateConfig(updates: Partial<T>): Promise<boolean> {
+    try {
+      const currentConfig = await this.loadConfig();
+      const newConfig = await this.definition.validate({
+        ...currentConfig,
+        ...updates,
+      });
+      return await this.writeConfigFile(newConfig);
+    } catch (error) {
+      this.logger.error("Failed to update config", error);
+      return false;
+    }
+  }
+}

plugin/source/dynamix.unraid.net/usr/local/emhttp/plugins/dynamix.my.servers/include/web-components-extractor.php

@@ -39,6 +39,7 @@ class WebComponentsExtractor
         return $contents ? json_decode($contents, true) : [];
     }
 
+
     private function getRichComponentsFile(): string
     {
         $manifestFiles = $this->findManifestFiles('manifest.json');

unraid-ui/.prettierrc.json

@@ -4,5 +4,5 @@
   "tabWidth": 2,
   "printWidth": 105,
   "singleQuote": true,
-  "plugins": ["prettier-plugin-tailwindcss", "@ianvs/prettier-plugin-sort-imports"]
+  "plugins": ["@ianvs/prettier-plugin-sort-imports"]
 }

unraid-ui/.storybook/main.ts

@@ -19,29 +19,21 @@ const config: StorybookConfig = {
   staticDirs: ['./static'],
 
   async viteFinal(config) {
+    const storybookDir = dirname(new URL(import.meta.url).pathname);
+
     return {
       ...config,
-      root: dirname(require.resolve('@storybook/builder-vite')),
+      plugins: [...(config.plugins ?? [])],
       resolve: {
         alias: {
-          '@': join(dirname(new URL(import.meta.url).pathname), '../src'),
-          '@/components': join(dirname(new URL(import.meta.url).pathname), '../src/components'),
-          '@/lib': join(dirname(new URL(import.meta.url).pathname), '../src/lib'),
+          '@': join(storybookDir, '../src'),
+          '@/components': join(storybookDir, '../src/components'),
+          '@/lib': join(storybookDir, '../src/lib'),
         },
       },
       optimizeDeps: {
         include: [...(config.optimizeDeps?.include ?? []), '@unraid/tailwind-rem-to-rem'],
       },
-      css: {
-        postcss: {
-          plugins: [
-            (await import('tailwindcss')).default({
-              config: './tailwind.config.ts',
-            }),
-            (await import('autoprefixer')).default,
-          ],
-        },
-      },
     };
   },
 };

unraid-ui/.storybook/preview.ts

@@ -1,6 +1,7 @@
 import type { Preview } from '@storybook/vue3-vite';
 import { registerAllComponents } from '../src/register';
 import '@/styles/index.css';
+import '@/../.storybook/static/index.css';
 
 registerAllComponents({
   pathToSharedCss: '/index.css',

unraid-ui/README.md

@@ -27,36 +27,6 @@ Import the component library styles in your main entry file:
 import '@unraid/ui/style.css';
 ```
 
-### 2. Configure TailwindCSS
-
-Create a `tailwind.config.ts` file with the following configuration:
-
-```typescript
-import tailwindConfig from '@unraid/ui/tailwind.config.ts';
-import type { Config } from 'tailwindcss';
-
-export default {
-  presets: [tailwindConfig],
-  content: [
-    // ... your content paths
-    './components/**/*.{js,vue,ts}',
-    './layouts/**/*.vue',
-    './pages/**/*.vue',
-  ],
-  theme: {
-    extend: {
-      // your theme extensions
-    },
-  },
-} satisfies Partial<Config>;
-```
-
-This configuration:
-
-- Uses the Unraid UI library's Tailwind config as a preset
-- Properly types your configuration with TypeScript
-- Allows you to extend the base theme while maintaining all Unraid UI defaults
-
 ## Usage
 
 ```vue
@@ -249,7 +219,7 @@ const meta = {
   argTypes: {
     variant: {
       control: 'select',
-      options: ['primary', 'secondary', 'outline'],
+      options: ['primary', 'secondary', 'outline-solid'],
     },
     size: {
       control: 'select',

unraid-ui/components.json

@@ -3,7 +3,6 @@
   "style": "default",
   "typescript": true,
   "tailwind": {
-    "config": "tailwind.config.ts",
     "css": "src/styles/globals.css",
     "baseColor": "neutral",
     "cssVariables": true,

unraid-ui/package.json

@@ -9,11 +9,9 @@
   "types": "./dist/index.d.ts",
   "sideEffects": false,
   "files": [
-    "dist",
-    "tailwind.config.ts"
+    "dist"
   ],
   "scripts": {
-    "prepare": "pnpm build",
     "// Development": "",
     "dev": "vite",
     "preview": "vite preview",
@@ -34,11 +32,11 @@
     "preunraid:deploy": "pnpm build:wc",
     "unraid:deploy": "just deploy",
     "// Storybook": "",
-    "prestorybook": "pnpm storybook:css",
-    "storybook": "storybook dev -p 6006",
-    "storybook:css": "node scripts/build-style.mjs",
-    "prebuild-storybook": "pnpm storybook:css",
-    "build-storybook": "storybook build",
+    "storybook": "pnpm tailwind:watch & pnpm storybook:dev",
+    "storybook:dev": "storybook dev -p 6006",
+    "build-storybook": "pnpm tailwind:build && storybook build",
+    "tailwind:build": "tailwindcss -i ./src/styles/globals.css -o ./.storybook/static/index.css",
+    "tailwind:watch": "pnpm tailwind:build --watch",
     "// Cloudflare Workers Deployment": "",
     "deploy:storybook": "pnpm build-storybook && wrangler deploy",
     "deploy:storybook:staging": "pnpm build-storybook && wrangler deploy --env staging"
@@ -54,6 +52,7 @@
     "@jsonforms/core": "3.6.0",
     "@jsonforms/vue": "3.6.0",
     "@jsonforms/vue-vanilla": "3.6.0",
+    "@tailwindcss/cli": "4.1.11",
     "@vueuse/core": "13.5.0",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
@@ -64,6 +63,7 @@
     "reka-ui": "2.3.2",
     "shadcn-vue": "2.2.0",
     "tailwind-merge": "2.6.0",
+    "tw-animate-css": "1.3.5",
     "vue-sonner": "1.3.2"
   },
   "devDependencies": {
@@ -72,19 +72,18 @@
     "@storybook/addon-links": "9.0.17",
     "@storybook/builder-vite": "9.0.17",
     "@storybook/vue3-vite": "9.0.17",
-    "@tailwindcss/typography": "0.5.16",
+    "@tailwindcss/vite": "4.1.11",
     "@testing-library/vue": "8.1.0",
     "@types/jsdom": "21.1.7",
     "@types/node": "22.16.4",
     "@types/testing-library__vue": "5.3.0",
     "@typescript-eslint/eslint-plugin": "8.37.0",
-    "@unraid/tailwind-rem-to-rem": "1.1.0",
+    "@unraid/tailwind-rem-to-rem": "2.0.0",
     "@vitejs/plugin-vue": "6.0.0",
     "@vitest/coverage-v8": "3.2.4",
     "@vitest/ui": "3.2.4",
     "@vue/test-utils": "2.4.6",
     "@vue/tsconfig": "0.7.0",
-    "autoprefixer": "10.4.21",
     "concurrently": "9.2.0",
     "eslint": "9.31.0",
     "eslint-config-prettier": "10.1.5",
@@ -96,14 +95,10 @@
     "happy-dom": "18.0.1",
     "jiti": "2.4.2",
     "postcss": "8.5.6",
-    "postcss-import": "16.1.1",
     "prettier": "3.6.2",
-    "prettier-plugin-tailwindcss": "0.6.14",
     "rimraf": "6.0.1",
     "storybook": "9.0.17",
-    "tailwind-rem-to-rem": "github:unraid/tailwind-rem-to-rem",
-    "tailwindcss": "3.4.17",
-    "tailwindcss-animate": "1.0.7",
+    "tailwindcss": "4.1.11",
     "typescript": "5.8.3",
     "typescript-eslint": "8.37.0",
     "vite": "7.0.4",
@@ -124,20 +119,7 @@
       "require": "./dist/index.cjs"
     },
     "./styles": "./dist/style.css",
-    "./styles/*": "./src/styles/*",
-    "./tailwind.config": {
-      "types": "./dist/tailwind.config.d.ts",
-      "import": "./dist/tailwind.config.js",
-      "default": "./dist/tailwind.config.js"
-    },
-    "./tailwind.config.ts": {
-      "import": "./tailwind.config.ts",
-      "default": "./tailwind.config.ts"
-    },
-    "./theme/preset": {
-      "types": "./dist/theme/preset.d.ts",
-      "import": "./dist/theme/preset.js"
-    }
+    "./styles/*": "./src/styles/*"
   },
   "packageManager": "pnpm@10.13.1"
 }

unraid-ui/postcss.config.js

@@ -1,6 +0,0 @@
-export default {
-  plugins: {
-    tailwindcss: {},
-    autoprefixer: {},
-  },
-};

unraid-ui/scripts/build-style.mjs

@@ -1,30 +0,0 @@
-import fs from 'fs/promises';
-import autoprefixer from 'autoprefixer';
-import postcss from 'postcss';
-import postcssImport from 'postcss-import';
-import tailwindcss from 'tailwindcss';
-
-/**
- * Helper script for storybook to build the CSS file for the components. This is used to ensure that modals render using the shadow styles.
- */
-
-process.env.VITE_TAILWIND_BASE_FONT_SIZE = 16;
-
-const inputPath = './src/styles/index.css';
-const outputPath = './.storybook/static/index.css'; // served from root: /index.css
-
-const css = await fs.readFile(inputPath, 'utf8');
-
-const result = await postcss([
-  postcssImport(),
-  tailwindcss({ config: './tailwind.config.ts' }),
-  autoprefixer(),
-]).process(css, {
-  from: inputPath,
-  to: outputPath,
-});
-
-await fs.mkdir('./.storybook/static', { recursive: true });
-await fs.writeFile(outputPath, result.css);
-
-console.log('✅ CSS built for Storybook:', outputPath);

unraid-ui/src/components/brand/BrandButton.vue

@@ -42,18 +42,17 @@ const props = withDefaults(defineProps<BrandButtonProps>(), {
 defineEmits(['click']);
 
 const classes = computed(() => {
-  const iconSize = `w-${props.size}`;
-
   return {
     button: cn(
       brandButtonVariants({ variant: props.variant, size: props.size, padding: props.padding }),
       props.class
     ),
-    icon: `${iconSize} fill-current flex-shrink-0`,
+    icon: 'w-[var(--icon-size)] fill-current shrink-0',
+    iconSize: props.size ?? '16px',
   };
 });
 const needsBrandGradientBackground = computed(() => {
-  return ['outline', 'outline-primary'].includes(props.variant ?? '');
+  return ['outline-solid', 'outline-primary'].includes(props.variant ?? '');
 });
 </script>
 
@@ -71,15 +70,20 @@ const needsBrandGradientBackground = computed(() => {
   >
     <div
       v-if="variant === 'fill'"
-      class="absolute -top-[2px] -right-[2px] -bottom-[2px] -left-[2px] -z-10 bg-gradient-to-r from-unraid-red to-orange opacity-100 transition-all rounded-md group-hover:opacity-60 group-focus:opacity-60"
+      class="absolute -top-[2px] -right-[2px] -bottom-[2px] -left-[2px] -z-10 bg-linear-to-r from-unraid-red to-orange opacity-100 transition-all rounded-md group-hover:opacity-60 group-focus:opacity-60"
     />
     <!-- gives outline buttons the brand gradient background -->
     <div
       v-if="needsBrandGradientBackground"
-      class="absolute -top-[2px] -right-[2px] -bottom-[2px] -left-[2px] -z-10 bg-gradient-to-r from-unraid-red to-orange opacity-0 transition-all rounded-md group-hover:opacity-100 group-focus:opacity-100"
+      class="absolute -top-[2px] -right-[2px] -bottom-[2px] -left-[2px] -z-10 bg-linear-to-r from-unraid-red to-orange opacity-0 transition-all rounded-md group-hover:opacity-100 group-focus:opacity-100"
     />
 
-    <component :is="icon" v-if="icon" :class="classes.icon" />
+    <component
+      :is="icon"
+      v-if="icon"
+      :class="classes.icon"
+      :style="{ '--icon-size': classes.iconSize }"
+    />
 
     {{ text }}
     <slot />
@@ -92,6 +96,7 @@ const needsBrandGradientBackground = computed(() => {
         iconRightHoverDisplay &&
           'opacity-0 group-hover:opacity-100 group-focus:opacity-100 transition-all',
       ]"
+      :style="{ '--icon-size': classes.iconSize }"
     />
   </component>
 </template>

unraid-ui/src/components/brand/brand-button.variants.ts

@@ -21,15 +21,15 @@ export const brandButtonVariants = cva(
         'underline-hover-red':
           'opacity-75 underline border-transparent transition hover:text-white hover:bg-unraid-red hover:border-unraid-red focus:text-white focus:bg-unraid-red focus:border-unraid-red hover:opacity-100 focus:opacity-100',
         white: 'text-black bg-white transition hover:bg-grey focus:bg-grey',
-        none: '',
+        none: 'border-transparent hover:shadow-none focus:shadow-none',
       },
       size: {
-        '12px': 'text-12px gap-4px',
-        '14px': 'text-14px gap-8px',
-        '16px': 'text-16px gap-8px',
-        '18px': 'text-18px gap-8px',
-        '20px': 'text-20px gap-8px',
-        '24px': 'text-24px gap-8px',
+        '12px': 'text-xs gap-1',
+        '14px': 'text-sm gap-2',
+        '16px': 'text-base gap-2',
+        '18px': 'text-lg gap-2',
+        '20px': 'text-xl gap-2',
+        '24px': 'text-2xl gap-2',
       },
       padding: {
         default: '',
@@ -41,32 +41,32 @@ export const brandButtonVariants = cva(
       {
         size: '12px',
         padding: 'default',
-        class: 'p-8px',
+        class: 'p-2',
       },
       {
         size: '14px',
         padding: 'default',
-        class: 'p-8px',
+        class: 'p-2',
       },
       {
         size: '16px',
         padding: 'default',
-        class: 'p-12px',
+        class: 'p-3',
       },
       {
         size: '18px',
         padding: 'default',
-        class: 'p-12px',
+        class: 'p-3',
       },
       {
         size: '20px',
         padding: 'default',
-        class: 'p-16px',
+        class: 'p-4',
       },
       {
         size: '24px',
         padding: 'default',
-        class: 'p-16px',
+        class: 'p-4',
       },
     ],
     defaultVariants: {

unraid-ui/src/components/common/badge/Badge.vue

@@ -23,12 +23,12 @@ const props = withDefaults(defineProps<BadgeProps>(), {
 
 const badgeClasses = computed(() => {
   const iconSizes = {
-    xs: 'w-12px',
-    sm: 'w-14px',
-    md: 'w-16px',
-    lg: 'w-18px',
-    xl: 'w-20px',
-    '2xl': 'w-24px',
+    xs: 'w-3',
+    sm: 'w-3.5',
+    md: 'w-4',
+    lg: 'w-4.5',
+    xl: 'w-5',
+    '2xl': 'w-6',
   } as const;
 
   return {
@@ -40,8 +40,8 @@ const badgeClasses = computed(() => {
 
 <template>
   <span :class="[badgeClasses.badge, props.class]">
-    <component :is="icon" v-if="icon" class="flex-shrink-0" :class="badgeClasses.icon" />
+    <component :is="icon" v-if="icon" class="shrink-0" :class="badgeClasses.icon" />
     <slot />
-    <component :is="iconRight" v-if="iconRight" class="flex-shrink-0" :class="badgeClasses.icon" />
+    <component :is="iconRight" v-if="iconRight" class="shrink-0" :class="badgeClasses.icon" />
   </span>
 </template>

unraid-ui/src/components/common/badge/badge.variants.ts

@@ -22,12 +22,12 @@ export const badgeVariants = cva(
         custom: '',
       },
       size: {
-        xs: 'text-12px px-8px py-4px gap-4px',
-        sm: 'text-14px px-8px py-4px gap-8px',
-        md: 'text-16px px-12px py-8px gap-8px',
-        lg: 'text-18px px-12px py-8px gap-8px',
-        xl: 'text-20px px-16px py-12px gap-8px',
-        '2xl': 'text-24px px-16px py-12px gap-8px',
+        xs: 'text-xs px-2 py-1 gap-1',
+        sm: 'text-sm px-2 py-1 gap-2',
+        md: 'text-base px-3 py-2 gap-2',
+        lg: 'text-lg px-3 py-2 gap-2',
+        xl: 'text-xl px-4 py-3 gap-2',
+        '2xl': 'text-2xl px-4 py-3 gap-2',
       },
     },
     defaultVariants: {

unraid-ui/src/components/common/button/Button.test.ts

@@ -20,7 +20,7 @@ describe('Button', () => {
     });
 
     rerender({
-      props: { variant: 'outline' },
+      props: { variant: 'outline-solid' },
       slots: { default: 'Delete' },
     });
   });

unraid-ui/src/components/common/button/button.variants.ts

@@ -2,7 +2,7 @@ import type { VariantProps } from 'class-variance-authority';
 import { cva } from 'class-variance-authority';
 
 export const buttonVariants = cva(
-  'inline-flex items-center justify-center rounded-md text-base font-medium ring-offset-background transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  'inline-flex items-center justify-center rounded-md text-base font-medium ring-offset-background transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
   {
     variants: {
       variant: {

unraid-ui/src/components/common/popover/PopoverContent.vue

@@ -35,7 +35,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
       v-bind="{ ...forwarded, ...$attrs }"
       :class="
         cn(
-          'z-50 w-72 rounded-md bg-popover p-4 text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+          'z-50 w-72 rounded-md bg-popover p-4 text-popover-foreground shadow-md outline-hidden data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
           props.class
         )
       "

unraid-ui/src/components/common/sheet/SheetContent.vue

@@ -46,12 +46,12 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
 <template>
   <DialogPortal :disabled="disabled" :force-mount="forceMount" :to="teleportTarget">
     <DialogOverlay
-      class="fixed inset-0 z-50 bg-black/80 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0"
+      class="fixed inset-0 z-50 bg-black/60 data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0"
     />
     <DialogContent :class="sheetClass" v-bind="forwarded">
       <slot />
       <DialogClose
-        class="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-secondary"
+        class="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-hidden focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-secondary"
       >
         <X class="w-4 h-4 text-muted-foreground" />
       </DialogClose>

unraid-ui/src/components/common/stepper/StepperIndicator.vue

@@ -22,7 +22,7 @@ const forwarded = useForwardProps(delegatedProps);
       cn(
         'inline-flex items-center justify-center rounded-full text-muted-foreground/50 w-10 h-10',
         // Disabled
-        'group-data-[disabled]:text-muted-foreground group-data-[disabled]:opacity-50',
+        'group-data-disabled:text-muted-foreground group-data-disabled:opacity-50',
         // Active
         'group-data-[state=active]:bg-primary group-data-[state=active]:text-primary-foreground',
         // Completed

unraid-ui/src/components/common/stepper/StepperItem.vue

@@ -24,7 +24,7 @@ const forwarded = useForwardProps(delegatedProps);
         'flex flex-col items-start gap-1',
         'md:flex-row md:items-center md:gap-2',
         'group transition-all duration-200',
-        'data-[disabled]:pointer-events-none data-[disabled]:opacity-80',
+        'data-disabled:pointer-events-none data-disabled:opacity-80',
         props.class
       )
     "

unraid-ui/src/components/common/stepper/StepperSeparator.vue

@@ -22,7 +22,7 @@ const forwarded = useForwardProps(delegatedProps);
       cn(
         'hidden md:block bg-muted md:w-24 md:h-px md:my-0',
         // Disabled
-        'group-data-[disabled]:bg-muted group-data-[disabled]:opacity-75',
+        'group-data-disabled:bg-muted group-data-disabled:opacity-75',
         // Completed
         'group-data-[state=completed]:bg-accent-foreground',
         props.class

unraid-ui/src/components/common/tabs/TabsContent.vue

@@ -16,7 +16,7 @@ const delegatedProps = computed(() => {
     v-bind="delegatedProps"
     :class="
       cn(
-        'flex mt-2 ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
+        'flex mt-2 ring-offset-background focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2',
         props.class
       )
     "

unraid-ui/src/components/common/tabs/TabsTrigger.vue

@@ -19,7 +19,7 @@ const forwardedProps = useForwardProps(delegatedProps);
     v-bind="forwardedProps"
     :class="
       cn(
-        'inline-flex items-center justify-center whitespace-nowrap rounded px-4.5 py-2.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-sm',
+        'inline-flex items-center justify-center whitespace-nowrap rounded px-4.5 py-2.5 text-sm font-medium ring-offset-background transition-all focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50 data-[state=active]:bg-background data-[state=active]:text-foreground data-[state=active]:shadow-xs',
         props.class
       )
     "

unraid-ui/src/components/form/combobox/ComboboxInput.vue

@@ -30,7 +30,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
     v-bind="forwarded"
     :class="
       cn(
-        'flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+        'flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
         props.class
       )
     "

unraid-ui/src/components/form/combobox/ComboboxItem.vue

@@ -21,7 +21,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
     v-bind="forwarded"
     :class="
       cn(
-        'relative flex cursor-default gap-2 select-none justify-between items-center rounded-sm px-2 py-1.5 text-sm outline-none data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&_svg]:size-4 [&_svg]:shrink-0',
+        'relative flex cursor-default gap-2 select-none justify-between items-center rounded-sm px-2 py-1.5 text-sm outline-hidden data-highlighted:bg-accent data-highlighted:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&_svg]:size-4 [&_svg]:shrink-0',
         props.class
       )
     "

unraid-ui/src/components/form/combobox/ComboboxList.vue

@@ -33,7 +33,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
       v-bind="{ ...forwarded, ...$attrs }"
       :class="
         cn(
-          'z-50 w-[200px] rounded-md border bg-popover text-popover-foreground shadow-md outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
+          'z-50 w-[200px] rounded-md border bg-popover text-popover-foreground shadow-md outline-hidden data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2',
           position === 'popper' &&
             'data-[side=bottom]:translate-y-1 data-[side=left]:-translate-x-1 data-[side=right]:translate-x-1 data-[side=top]:-translate-y-1',
           props.class
@@ -45,7 +45,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
           cn(
             'p-1',
             position === 'popper' &&
-              'h-[--reka-combobox-trigger-height] w-full min-w-[--reka-combobox-trigger-width]'
+              'h-(--reka-combobox-trigger-height) w-full min-w-(--reka-combobox-trigger-width)'
           )
         "
       >

unraid-ui/src/components/form/input/Input.vue

@@ -24,7 +24,7 @@ const modelValue = useVModel(props, 'modelValue', emits, {
     v-model="modelValue"
     :class="
       cn(
-        'flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+        'flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
         props.class
       )
     "

unraid-ui/src/components/form/lightswitch/Lightswitch.vue

@@ -13,18 +13,18 @@ const checked = ref(false);
 </script>
 <template>
   <SwitchGroup as="div">
-    <div class="flex flex-shrink-0 items-center gap-16px">
+    <div class="flex shrink-0 items-center gap-4">
       <Switch
         v-model="checked"
         :class="[
           checked ? 'bg-green-500' : 'bg-gray-200',
-          'relative inline-flex h-24px w-[44px] flex-shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-200 ease-in-out focus:outline-none focus:ring-2 focus:ring-indigo-600 focus:ring-offset-2',
+          'relative inline-flex h-6 w-[44px] shrink-0 cursor-pointer rounded-full border-2 border-transparent transition-colors duration-200 ease-in-out focus:outline-hidden focus:ring-2 focus:ring-indigo-600 focus:ring-offset-2',
         ]"
       >
         <span
           :class="[
-            checked ? 'translate-x-20px' : 'translate-x-0',
-            'pointer-events-none relative inline-block h-20px w-20px transform rounded-full bg-white shadow ring-0 transition duration-200 ease-in-out',
+            checked ? 'translate-x-5' : 'translate-x-0',
+            'pointer-events-none relative inline-block h-5 w-5 transform rounded-full bg-white shadow-sm ring-0 transition duration-200 ease-in-out',
           ]"
         >
           <span
@@ -34,7 +34,7 @@ const checked = ref(false);
             ]"
             aria-hidden="true"
           >
-            <svg class="h-12px w-12px text-gray-400" fill="none" viewBox="0 0 12 12">
+            <svg class="h-3 w-3 text-gray-400" fill="none" viewBox="0 0 12 12">
               <path
                 d="M4 8l2-2m0 0l2-2M6 6L4 4m2 2l2 2"
                 stroke="currentColor"
@@ -51,7 +51,7 @@ const checked = ref(false);
             ]"
             aria-hidden="true"
           >
-            <svg class="h-12px w-12px text-green-500" fill="currentColor" viewBox="0 0 12 12">
+            <svg class="h-3 w-3 text-green-500" fill="currentColor" viewBox="0 0 12 12">
               <path
                 d="M3.707 5.293a1 1 0 00-1.414 1.414l1.414-1.414zM5 8l-.707.707a1 1 0 001.414 0L5 8zm4.707-3.293a1 1 0 00-1.414-1.414l1.414 1.414zm-7.414 2l2 2 1.414-1.414-2-2-1.414 1.414zm3.414 2l4-4-1.414-1.414-4 4 1.414 1.414z"
               />
@@ -59,7 +59,7 @@ const checked = ref(false);
           </span>
         </span>
       </Switch>
-      <SwitchLabel class="text-14px">
+      <SwitchLabel class="text-sm">
         {{ label }}
       </SwitchLabel>
     </div>

unraid-ui/src/components/form/number/NumberFieldContent.vue

@@ -12,7 +12,7 @@ const props = defineProps<{
   <div
     :class="
       cn(
-        'relative [&>[data-slot=input]]:has-[[data-slot=increment]]:pr-5 [&>[data-slot=input]]:has-[[data-slot=decrement]]:pl-5',
+        'relative has-data-[slot=increment]:*:data-[slot=input]:pr-5 has-data-[slot=decrement]:*:data-[slot=input]:pl-5',
         props.class
       )
     "

unraid-ui/src/components/form/number/NumberFieldInput.vue

@@ -13,7 +13,7 @@ const props = defineProps<{
     data-slot="input"
     :class="
       cn(
-        'flex h-10 w-full rounded-md border border-input bg-background py-2 text-sm text-center ring-offset-background placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+        'flex h-10 w-full rounded-md border border-input bg-background py-2 text-sm text-center ring-offset-background placeholder:text-muted-foreground focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
         props.class
       )
     "

unraid-ui/src/components/form/select/Select.vue

@@ -9,12 +9,11 @@ import {
   SelectTrigger,
   SelectValue,
 } from '@/components/ui/select';
+import type { AcceptableValue } from 'reka-ui';
 import { computed } from 'vue';
 
 type SelectValueType = string | number;
 
-type AcceptableValue = SelectValueType | SelectValueType[] | Record<string, unknown> | bigint | null;
-
 interface SelectItemInterface {
   label: string;
   value: SelectValueType;

unraid-ui/src/components/form/switch/Switch.vue

@@ -27,7 +27,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
     v-bind="forwarded"
     :class="
       cn(
-        'peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input',
+        'peer inline-flex h-6 w-11 shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent transition-colors focus-visible:outline-hidden focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input',
         props.class
       )
     "

unraid-ui/src/components/layout/PageContainer.vue

@@ -4,13 +4,13 @@ withDefaults(
     maxWidth?: string;
   }>(),
   {
-    maxWidth: 'max-w-1024px',
+    maxWidth: 'max-w-[1024px]',
   }
 );
 </script>
 
 <template>
-  <div class="grid gap-y-24px w-full mx-auto px-16px" :class="maxWidth">
+  <div class="grid gap-y-6 w-full mx-auto px-4" :class="maxWidth">
     <slot />
   </div>
 </template>

unraid-ui/src/components/layout/SettingsGrid.vue

@@ -0,0 +1,31 @@
+<script setup lang="ts">
+import { cn } from '@/lib/utils';
+
+const props = defineProps<{
+  class?: string;
+}>();
+</script>
+
+<template>
+  <div
+    :class="cn('settings-grid grid gap-2 items-baseline md:pl-3 md:gap-x-10 md:gap-y-6', props.class)"
+  >
+    <slot />
+  </div>
+</template>
+
+<style>
+.settings-grid {
+  grid-template-columns: 1fr;
+}
+
+@media (min-width: 768px) {
+  .settings-grid {
+    grid-template-columns: 35% 1fr;
+  }
+
+  .settings-grid > *:nth-child(odd) {
+    text-align: end;
+  }
+}
+</style>

unraid-ui/src/components/layout/index.ts

@@ -1,4 +1,5 @@
 import CardWrapper from '@/components/layout/CardWrapper.vue';
 import PageContainer from '@/components/layout/PageContainer.vue';
+import SettingsGrid from '@/components/layout/SettingsGrid.vue';
 
-export { CardWrapper, PageContainer };
+export { CardWrapper, PageContainer, SettingsGrid };

unraid-ui/src/components/ui/dialog/DialogContent.vue

@@ -44,7 +44,7 @@ const { teleportTarget } = useTeleport();
 
       <DialogClose
         v-if="showCloseButton !== false"
-        class="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground"
+        class="absolute right-4 top-4 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-hidden focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:pointer-events-none data-[state=open]:bg-accent data-[state=open]:text-muted-foreground"
       >
         <X class="w-4 h-4" />
         <span class="sr-only">Close</span>

unraid-ui/src/components/ui/dropdown-menu/DropdownMenuCheckboxItem.vue

@@ -24,7 +24,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
     v-bind="forwarded"
     :class="
       cn(
-        'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+        'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-hidden transition-colors focus:bg-accent focus:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50',
         props.class
       )
     "

unraid-ui/src/components/ui/dropdown-menu/DropdownMenuItem.vue

@@ -18,7 +18,7 @@ const forwardedProps = useForwardProps(delegatedProps);
     v-bind="forwardedProps"
     :class="
       cn(
-        'relative flex cursor-default select-none items-center rounded-sm gap-2 px-2 py-1.5 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 [&>svg]:size-4 [&>svg]:shrink-0',
+        'relative flex cursor-default select-none items-center rounded-sm gap-2 px-2 py-1.5 text-sm outline-hidden transition-colors focus:bg-accent focus:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50 [&>svg]:size-4 [&>svg]:shrink-0',
         inset && 'pl-8',
         props.class
       )

unraid-ui/src/components/ui/dropdown-menu/DropdownMenuRadioItem.vue

@@ -25,7 +25,7 @@ const forwarded = useForwardPropsEmits(delegatedProps, emits);
     v-bind="forwarded"
     :class="
       cn(
-        'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+        'relative flex cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-hidden transition-colors focus:bg-accent focus:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50',
         props.class
       )
     "

unraid-ui/src/components/ui/dropdown-menu/DropdownMenuSubTrigger.vue

@@ -17,7 +17,7 @@ const forwardedProps = useForwardProps(delegatedProps);
     v-bind="forwardedProps"
     :class="
       cn(
-        'flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none focus:bg-accent data-[state=open]:bg-accent',
+        'flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-hidden focus:bg-accent data-[state=open]:bg-accent',
         props.class
       )
     "

unraid-ui/src/components/ui/dropdown-menu/DropdownMenuTrigger.vue

@@ -8,7 +8,7 @@ const forwardedProps = useForwardProps(props);
 
 <template>
   <DropdownMenuTrigger
-    class="outline-none cursor-pointer [&[data-state=open]]:cursor-pointer"
+    class="outline-hidden cursor-pointer data-[state=open]:cursor-pointer"
     v-bind="forwardedProps"
   >
     <slot />

unraid-ui/src/components/ui/select/SelectContent.vue

@@ -48,7 +48,7 @@ const { teleportTarget } = useTeleport();
           cn(
             'p-1',
             position === 'popper' &&
-              'h-[--reka-select-trigger-height] w-full min-w-[--reka-select-trigger-width]'
+              'h-(--reka-select-trigger-height) w-full min-w-(--reka-select-trigger-width)'
           )
         "
       >

unraid-ui/src/components/ui/select/SelectItem.vue

@@ -23,7 +23,7 @@ const forwardedProps = useForwardProps(delegatedProps);
     v-bind="forwardedProps"
     :class="
       cn(
-        'relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50',
+        'relative flex w-full cursor-default select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-hidden focus:bg-accent focus:text-accent-foreground data-disabled:pointer-events-none data-disabled:opacity-50',
         props.class
       )
     "

unraid-ui/src/components/ui/select/SelectTrigger.vue

@@ -17,7 +17,7 @@ const forwardedProps = useForwardProps(delegatedProps);
     v-bind="forwardedProps"
     :class="
       cn(
-        'flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background data-[placeholder]:text-muted-foreground focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:truncate text-start',
+        'flex h-10 w-full items-center justify-between rounded-md border border-input bg-background px-3 py-2 text-sm ring-offset-background data-placeholder:text-muted-foreground focus:outline-hidden focus:ring-2 focus:ring-ring focus:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50 [&>span]:truncate text-start',
         props.class
       )
     "

unraid-ui/src/forms/ComboBoxField.vue

@@ -99,7 +99,7 @@ if (control.value.data !== undefined && control.value.data !== null) {
               <ComboboxItem
                 :value="suggestion.value"
                 @select="handleSelect"
-                class="relative flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none hover:bg-accent hover:text-accent-foreground data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground"
+                class="relative flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-hidden hover:bg-accent hover:text-accent-foreground data-highlighted:bg-accent data-highlighted:text-accent-foreground"
               >
                 <span>{{ suggestion.label || suggestion.value }}</span>
               </ComboboxItem>
@@ -113,7 +113,7 @@ if (control.value.data !== undefined && control.value.data !== null) {
           v-else
           :value="suggestion.value"
           @select="handleSelect"
-          class="relative flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none hover:bg-accent hover:text-accent-foreground data-[highlighted]:bg-accent data-[highlighted]:text-accent-foreground"
+          class="relative flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-hidden hover:bg-accent hover:text-accent-foreground data-highlighted:bg-accent data-highlighted:text-accent-foreground"
         >
           <span>{{ suggestion.label || suggestion.value }}</span>
         </ComboboxItem>

unraid-ui/src/forms/ControlWrapper.vue

@@ -13,7 +13,7 @@ const { control } = useJsonFormsControl(props);
 
 <template>
   <!-- Only render the wrapper if the control is visible -->
-  <div v-if="control.visible" class="flex-grow">
+  <div v-if="control.visible" class="grow">
     <!-- Render the actual control passed via the default slot -->
     <slot />
     <!-- Automatically display errors below the control -->

unraid-ui/src/forms/InputField.vue

@@ -46,7 +46,7 @@ const togglePasswordVisibility = () => {
     <Input
       v-model="value"
       :type="inputType"
-      :class="cn('flex-grow', classOverride, { 'pr-10': isPassword })"
+      :class="cn('grow', classOverride, { 'pr-10': isPassword })"
       :disabled="!control.enabled"
       :required="control.required"
       :placeholder="control.schema.description"

unraid-ui/src/forms/LabelRenderer.vue

@@ -70,7 +70,7 @@ const descriptionClass = computed(() => {
 
 <template>
   <!-- Use the computed isVisible based on renderer.value.visible -->
-  <div class="flex flex-col gap-2 flex-shrink-0">
+  <div class="flex flex-col gap-2 shrink-0">
     <!-- Replace native label with the Label component -->
     <Label v-if="labelText" :class="labelClass">{{ labelText }}</Label>
     <!-- Use v-html with the parsedDescription ref -->

unraid-ui/src/forms/SteppedLayout.vue

@@ -145,7 +145,10 @@ const getStepState = (stepIndex: number): StepState => {
 
     <!-- Render elements for the current step -->
     <!-- Added key to force re-render on step change, ensuring correct elements display -->
-    <div class="current-step-content rounded-md border p-4 shadow" :key="`step-content-${currentStep}`">
+    <div
+      class="current-step-content rounded-md border p-4 shadow-sm"
+      :key="`step-content-${currentStep}`"
+    >
       <DispatchRenderer
         v-for="(element, index) in currentStepElements"
         :key="`${layout.path}-${index}-step-${currentStep}`"

unraid-ui/src/forms/UnraidSettingsLayout.vue

@@ -15,6 +15,7 @@
  * @prop cells - Available cells
  */
 
+import SettingsGrid from '@/components/layout/SettingsGrid.vue';
 import { useJsonFormsVisibility } from '@/forms/composables/useJsonFormsVisibility';
 import type { HorizontalLayout } from '@jsonforms/core';
 import { DispatchRenderer, type RendererProps } from '@jsonforms/vue';
@@ -32,10 +33,7 @@ const elements = computed(() => {
 </script>
 
 <template>
-  <div
-    v-if="isVisible"
-    class="grid grid-cols-settings items-baseline pl-3 gap-y-6 [&>*:nth-child(odd)]:text-end [&>*:nth-child(even)]:ml-10"
-  >
+  <SettingsGrid v-if="isVisible">
     <template v-for="(element, _i) in elements" :key="_i">
       <DispatchRenderer
         :schema="layout.layout.value.schema"
@@ -46,5 +44,5 @@ const elements = computed(() => {
         :cells="layout.layout.value.cells"
       />
     </template>
-  </div>
+  </SettingsGrid>
 </template>

unraid-ui/src/index.ts

@@ -13,8 +13,5 @@ export * from '@/forms/renderers';
 // Lib
 export * from '@/lib/utils';
 
-// Config
-export { default as tailwindConfig } from '../tailwind.config';
-
 // Composables
 export { default as useTeleport } from '@/composables/useTeleport';

unraid-ui/src/styles/globals.css

@@ -1,98 +1,369 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
+@import 'tailwindcss';
+@import 'tw-animate-css';
 
+/* Force generation of all color utilities for custom colors across packages */
+@source inline("{bg,text,border,ring,fill,stroke}-{unraid-green,unraid-red}{,-50,-100,-200,-300,-400,-500,-600,-700,-800,-900,-950}");
+@source inline("{bg,text,border,ring,fill,stroke}-{yellow-accent,orange-dark,orange}");
+@source inline("{from,via,to}-{unraid-red,orange}");
+@source inline("bg-linear-to-{r,l,t,b,tr,tl,br,bl}");
+@source "../**/*.vue";
+@source "../stories/**/*.ts";
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+/*
+  The default border color has changed to `currentcolor` in Tailwind CSS v4,
+  so we've added these compatibility styles to make sure everything still
+  looks the same as it did with Tailwind CSS v3.
+
+  If we ever want to remove these styles, we need to add an explicit border
+  color utility to any element that depends on these defaults.
+*/
 @layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 0 0% 3.9%;
-
-    --muted: 0 0% 96.1%;
-    --muted-foreground: 0 0% 45.1%;
-
-    --popover: 0 0% 100%;
-    --popover-foreground: 0 0% 3.9%;
-
-    --card: 0 0% 100%;
-    --card-foreground: 0 0% 3.9%;
-
-    --border: 0 0% 89.8%;
-    --input: 0 0% 89.8%;
-
-    --primary: 0 0% 9%;
-    --primary-foreground: 0 0% 98%;
-
-    --secondary: 0 0% 96.1%;
-    --secondary-foreground: 0 0% 9%;
-
-    --accent: 0 0% 96.1%;
-    --accent-foreground: 0 0% 9%;
-
-    --destructive: 0 84.2% 60.2%;
-    --destructive-foreground: 0 0% 98%;
-
-    --ring: 0 0% 3.9%;
-
-    --radius: 0.5rem;
-
-    --chart-1: 12 76% 61%;
-
-    --chart-2: 173 58% 39%;
-
-    --chart-3: 197 37% 24%;
-
-    --chart-4: 43 74% 66%;
-
-    --chart-5: 27 87% 67%;
+  *,
+  ::after,
+  ::before,
+  ::backdrop,
+  ::file-selector-button {
+    border-color: var(--color-border);
   }
 
-  .dark {
-    --background: 0 0% 3.9%;
-    --foreground: 0 0% 98%;
-
-    --muted: 0 0% 14.9%;
-    --muted-foreground: 0 0% 63.9%;
-
-    --popover: 0 0% 3.9%;
-    --popover-foreground: 0 0% 98%;
-
-    --card: 0 0% 3.9%;
-    --card-foreground: 0 0% 98%;
-
-    --border: 0 0% 14.9%;
-    --input: 0 0% 14.9%;
-
-    --primary: 0 0% 98%;
-    --primary-foreground: 0 0% 9%;
-
-    --secondary: 0 0% 14.9%;
-    --secondary-foreground: 0 0% 98%;
-
-    --accent: 0 0% 14.9%;
-    --accent-foreground: 0 0% 98%;
-
-    --destructive: 0 62.8% 30.6%;
-    --destructive-foreground: 0 0% 98%;
-
-    --ring: 0 0% 83.1%;
-
-    --chart-1: 220 70% 50%;
-
-    --chart-2: 160 60% 45%;
-
-    --chart-3: 30 80% 55%;
-
-    --chart-4: 280 65% 60%;
-
-    --chart-5: 340 75% 55%;
+  /* Fix for Tailwind v4 border styles not working */
+  * {
+    --tw-border-style: solid;
   }
 }
 
+@theme static {
+  /* Breakpoints */
+  --breakpoint-xs: 30rem;
+  --breakpoint-2xl: 100rem;
+  --breakpoint-3xl: 120rem;
+
+  /* Container settings */
+  --container-center: true;
+  --container-padding: 2rem;
+  --container-screen-2xl: 1400px;
+
+  /* Font families */
+  --font-sans:
+    clear-sans, ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
+    'Segoe UI Symbol', 'Noto Color Emoji';
+
+  /* Grid template columns */
+  --grid-template-columns-settings: 35% 1fr;
+
+  /* Border color default */
+  --default-border-color: var(--color-border);
+
+  /* Color palette */
+  --color-inherit: inherit;
+  --color-transparent: transparent;
+  --color-black: #1c1b1b;
+  --color-grey-darkest: #222;
+  --color-grey-darker: #606f7b;
+  --color-grey-dark: #383735;
+  --color-grey-mid: #999999;
+  --color-grey: #e0e0e0;
+  --color-grey-light: #dae1e7;
+  --color-grey-lighter: #f1f5f8;
+  --color-grey-lightest: #f2f2f2;
+  --color-white: #ffffff;
+
+  /* Unraid colors */
+  --color-yellow-accent: #e9bf41;
+  --color-orange-dark: #f15a2c;
+  --color-orange: #ff8c2f;
+
+  /* Unraid red palette */
+  --color-unraid-red: #e22828;
+  --color-unraid-red-50: #fef2f2;
+  --color-unraid-red-100: #ffe1e1;
+  --color-unraid-red-200: #ffc9c9;
+  --color-unraid-red-300: #fea3a3;
+  --color-unraid-red-400: #fc6d6d;
+  --color-unraid-red-500: #f43f3f;
+  --color-unraid-red-600: #e22828;
+  --color-unraid-red-700: #bd1818;
+  --color-unraid-red-800: #9c1818;
+  --color-unraid-red-900: #821a1a;
+  --color-unraid-red-950: #470808;
+
+  /* Unraid green palette */
+  --color-unraid-green: #63a659;
+  --color-unraid-green-50: #f5f9f4;
+  --color-unraid-green-100: #e7f3e5;
+  --color-unraid-green-200: #d0e6cc;
+  --color-unraid-green-300: #aad1a4;
+  --color-unraid-green-400: #7db474;
+  --color-unraid-green-500: #63a659;
+  --color-unraid-green-600: #457b3e;
+  --color-unraid-green-700: #396134;
+  --color-unraid-green-800: #314e2d;
+  --color-unraid-green-900: #284126;
+  --color-unraid-green-950: #122211;
+
+  /* Header colors */
+  --color-header-text-primary: var(--header-text-primary);
+  --color-header-text-secondary: var(--header-text-secondary);
+  --color-header-background-color: var(--header-background-color);
+
+  /* Font sizes */
+  --font-10px: 10px;
+  --font-12px: 12px;
+  --font-14px: 14px;
+  --font-16px: 16px;
+  --font-18px: 18px;
+  --font-20px: 20px;
+  --font-24px: 24px;
+  --font-30px: 30px;
+
+  /* Spacing */
+  --spacing-4_5: 1.125rem;
+  --spacing--8px: -8px;
+  --spacing-2px: 2px;
+  --spacing-4px: 4px;
+  --spacing-6px: 6px;
+  --spacing-8px: 8px;
+  --spacing-10px: 10px;
+  --spacing-12px: 12px;
+  --spacing-14px: 14px;
+  --spacing-16px: 16px;
+  --spacing-20px: 20px;
+  --spacing-24px: 24px;
+  --spacing-28px: 28px;
+  --spacing-32px: 32px;
+  --spacing-36px: 36px;
+  --spacing-40px: 40px;
+  --spacing-64px: 64px;
+  --spacing-80px: 80px;
+  --spacing-90px: 90px;
+  --spacing-150px: 150px;
+  --spacing-160px: 160px;
+  --spacing-200px: 200px;
+  --spacing-260px: 260px;
+  --spacing-300px: 300px;
+  --spacing-310px: 310px;
+  --spacing-350px: 350px;
+  --spacing-448px: 448px;
+  --spacing-512px: 512px;
+  --spacing-640px: 640px;
+  --spacing-800px: 800px;
+
+  /* Width and Height values */
+  --width-36px: 36px;
+  --height-36px: 36px;
+
+  /* Min/Max widths */
+  --min-width-86px: 86px;
+  --min-width-160px: 160px;
+  --min-width-260px: 260px;
+  --min-width-300px: 300px;
+  --min-width-310px: 310px;
+  --min-width-350px: 350px;
+  --min-width-800px: 800px;
+
+  --max-width-86px: 86px;
+  --max-width-160px: 160px;
+  --max-width-260px: 260px;
+  --max-width-300px: 300px;
+  --max-width-310px: 310px;
+  --max-width-350px: 350px;
+  --max-width-640px: 640px;
+  --max-width-800px: 800px;
+  --max-width-1024px: 1024px;
+
+  /* Animations */
+  --animate-mark-2: mark-2 1.5s ease infinite;
+  --animate-mark-3: mark-3 1.5s ease infinite;
+  --animate-mark-6: mark-6 1.5s ease infinite;
+  --animate-mark-7: mark-7 1.5s ease infinite;
+
+  /* Radius */
+  --radius: 0.5rem;
+
+  /* Text Resizing */
+  --text-xs: 1.2rem; /* 12px at 10px base */
+  --text-sm: 1.4rem; /* 14px at 10px base */
+  --text-base: 1.6rem; /* 16px at 10px base */
+  --text-lg: 1.8rem; /* 18px at 10px base */
+  --text-xl: 2rem; /* 20px at 10px base */
+  --text-2xl: 2.4rem; /* 24px at 10px base */
+  --text-3xl: 3rem; /* 30px at 10px base */
+  --text-4xl: 3.6rem; /* 36px at 10px base */
+  --text-5xl: 4.8rem; /* 48px at 10px base */
+  --text-6xl: 6rem; /* 60px at 10px base */
+  --text-7xl: 7.2rem; /* 72px at 10px base */
+  --text-8xl: 9.6rem; /* 96px at 10px base */
+  --text-9xl: 12.8rem; /* 128px at 10px base */
+  --spacing: 0.4rem; /* 4px at 10px base */
+}
+
+/* Hybrid theme system: Native CSS + Theme Store fallback */
 @layer base {
+  /* Light mode defaults */
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 0 0% 3.9%;
+    --muted: 0 0% 96.1%;
+    --muted-foreground: 0 0% 45.1%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 0 0% 3.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 0 0% 3.9%;
+    --border: 0 0% 89.8%;
+    --input: 0 0% 89.8%;
+    --primary: 0 0% 9%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 0 0% 96.1%;
+    --secondary-foreground: 0 0% 9%;
+    --accent: 0 0% 96.1%;
+    --accent-foreground: 0 0% 9%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 0 0% 98%;
+    --ring: 0 0% 3.9%;
+    --chart-1: 12 76% 61%;
+    --chart-2: 173 58% 39%;
+    --chart-3: 197 37% 24%;
+    --chart-4: 43 74% 66%;
+    --chart-5: 27 87% 67%;
+  }
+
+  /* For web components: inherit CSS variables from the host */
+  :host {
+    --background: inherit;
+    --foreground: inherit;
+    --muted: inherit;
+    --muted-foreground: inherit;
+    --popover: inherit;
+    --popover-foreground: inherit;
+    --card: inherit;
+    --card-foreground: inherit;
+    --border: inherit;
+    --input: inherit;
+    --primary: inherit;
+    --primary-foreground: inherit;
+    --secondary: inherit;
+    --secondary-foreground: inherit;
+    --accent: inherit;
+    --accent-foreground: inherit;
+    --destructive: inherit;
+    --destructive-foreground: inherit;
+    --ring: inherit;
+    --chart-1: inherit;
+    --chart-2: inherit;
+    --chart-3: inherit;
+    --chart-4: inherit;
+    --chart-5: inherit;
+  }
+
+  /* Class-based dark mode support for web components using :host-context */
+  :host-context(.dark) {
+    --background: 0 0% 3.9%;
+    --foreground: 0 0% 98%;
+    --muted: 0 0% 14.9%;
+    --muted-foreground: 0 0% 63.9%;
+    --popover: 0 0% 3.9%;
+    --popover-foreground: 0 0% 98%;
+    --card: 0 0% 3.9%;
+    --card-foreground: 0 0% 98%;
+    --border: 0 0% 14.9%;
+    --input: 0 0% 14.9%;
+    --primary: 0 0% 98%;
+    --primary-foreground: 0 0% 9%;
+    --secondary: 0 0% 14.9%;
+    --secondary-foreground: 0 0% 98%;
+    --accent: 0 0% 14.9%;
+    --accent-foreground: 0 0% 98%;
+    --destructive: 0 62.8% 30.6%;
+    --destructive-foreground: 0 0% 98%;
+    --ring: 0 0% 83.1%;
+    --chart-1: 220 70% 50%;
+    --chart-2: 160 60% 45%;
+    --chart-3: 30 80% 55%;
+    --chart-4: 280 65% 60%;
+    --chart-5: 340 75% 55%;
+  }
+
+  /* Alternative class-based dark mode support for specific Unraid themes */
+  :host-context(.dark[data-theme='black']),
+  :host-context(.dark[data-theme='gray']) {
+    --background: 0 0% 3.9%;
+    --foreground: 0 0% 98%;
+    --border: 0 0% 14.9%;
+  }
+
   * {
     @apply border-border;
   }
+
   body {
     @apply bg-background text-foreground;
   }
-}
+}
+
+/* Keyframes */
+@keyframes mark-2 {
+  50% {
+    transform: translateY(-40px);
+  }
+  to {
+    transform: translateY(0);
+  }
+}
+
+@keyframes mark-3 {
+  50% {
+    transform: translateY(-62px);
+  }
+  to {
+    transform: translateY(0);
+  }
+}
+
+@keyframes mark-6 {
+  50% {
+    transform: translateY(40px);
+  }
+  to {
+    transform: translateY(0);
+  }
+}
+
+@keyframes mark-7 {
+  50% {
+    transform: translateY(62px);
+  }
+  to {
+    transform: translateY(0);
+  }
+}
+
+/* Define the theme colors that reference the existing CSS variables from web/themes */
+
+@theme inline {
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-muted: hsl(var(--muted));
+  --color-muted-foreground: hsl(var(--muted-foreground));
+  --color-popover: hsl(var(--popover));
+  --color-popover-foreground: hsl(var(--popover-foreground));
+  --color-card: hsl(var(--card));
+  --color-card-foreground: hsl(var(--card-foreground));
+  --color-border: hsl(var(--border));
+  --color-input: hsl(var(--input));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --color-secondary: hsl(var(--secondary));
+  --color-secondary-foreground: hsl(var(--secondary-foreground));
+  --color-accent: hsl(var(--accent));
+  --color-accent-foreground: hsl(var(--accent-foreground));
+  --color-destructive: hsl(var(--destructive));
+  --color-destructive-foreground: hsl(var(--destructive-foreground));
+  --color-ring: hsl(var(--ring));
+  --color-chart-1: hsl(var(--chart-1, 12 76% 61%));
+  --color-chart-2: hsl(var(--chart-2, 173 58% 39%));
+  --color-chart-3: hsl(var(--chart-3, 197 37% 24%));
+  --color-chart-4: hsl(var(--chart-4, 43 74% 66%));
+  --color-chart-5: hsl(var(--chart-5, 27 87% 67%));
+}

unraid-ui/src/styles/index.css

@@ -1,3 +1,3 @@
 /* global styles for unraid-ui */
-@import 'globals.css';
-@import 'sonner.css';
+@import './globals.css';
+@import './sonner.css';