fix: plugins: apiRequired [max] was not working
Massimo Melina committed
Dec 24, 2025 at 00:38 UTC
f32779b6b9b79c2604830471e95daa6d398530e1
4 files changed
+22
-7
admin/src/RandomPlugin.ts
+1
-1
@@ -16,7 +16,7 @@ export function RandomPlugin() {
16
const serializedCache = localStorage.getItem(cacheKey)
17
const cached = useMemo(() => {
18
const obj = tryJson(serializedCache || '')
19
- return obj?.ts && Date.now() - obj.ts < DAY && _.shuffle(obj.list)
19
+ return obj?.ts && Date.now() - obj.ts < DAY && _.shuffle(obj.list)
20
}, [serializedCache])
21
const { list, initializing } = useApiList(!hideRandomPlugin && !cached && 'get_online_plugins')
22
const [idx, setIdx] = useState(-1)
dev-plugins.md
+15
-1
@@ -96,7 +96,21 @@ All the following properties are optional unless otherwise specified.
96
97
- `description: string` try to explain what this plugin is for. (JSON syntax)
98
- `version: number` use progressive numbers to distinguish each release
99
-- `apiRequired: number | [min:number,max:number]` declare version(s) for which the plugin is designed. Mandatory. [Refer to API version history](#api-version-history)
99
+- `apiRequired: number | [min:number,max:number]` declare version(s) for which the plugin is designed. Mandatory.
100
+ A single number represents the minimum required version; an array of two defines the min/max supported versions.
101
+ Refer to the [API version history](#api-version-history) to find the correct number for your case.
102
+ Set a maximum version only if you know your plugin is incompatible with later releases.
103
+
104
+ Backward compatibility is standard, with rare exceptions. Most breaking changes affecting plugins occur when relying
105
+ on undocumented features, particularly via `api.require`. If your plugin becomes incompatible with a new HFS version:
106
+ - If you don't want to release an update: you can push a commit to modify `apiRequired` and specify a maximum version.
107
+ - If you release a new version to fix the issue:
108
+ - You DO NOT to set a *max* version.
109
+ - Only if your update broke the compatibility with the previous HFS version:
110
+ - You MUST update `apiRequired` to the current API version
111
+ (found at the end of this document).
112
+ - You MAY create a branch from the previous commit and name it `api12.8` (where 12.8 is your previous *apiRequired*).
113
+ This optional step enables users of older versions of HFS to still install your plugin.
114
- `isTheme: boolean | "light" | "dark"` set true if this is a theme that's not supposed to work together with other themes.
115
Running a theme will cause other themes to be stopped. Missing this, HFS will check if the name of the plugin ends with `-theme`.
116
Special values "light" and "dark" to declare whether the theme is (for example) dark and forces HFS to use dark-theme as a base.
src/const.ts
+1
-1
@@ -10,7 +10,7 @@ import { argv } from './argv'
10
export * from './cross-const'
11
12
export const API_VERSION = 12.97
13
-export const COMPATIBLE_API_VERSION = 1 // while changes in the api are not breaking, this number stays the same, otherwise it is made equal to API_VERSION
13
+export const COMPATIBLE_API_VERSION = 1 // the day we break with the past, we'll update this
14
15
// you can add arguments with this file, currently used for the update process on mac/linux
16
export const ARGS_FILE = join(homedir(), 'hfs-args')
src/plugins.ts
+5
-4
@@ -452,7 +452,7 @@ function watchPlugin(id: string, path: string) {
452
return onUninstalled()
453
if (isPluginEnabled(id, true))
454
return start()
455
- const p = parsePluginSource(id, source)
455
+ const p = parsePluginSource(id, source) // plugin not running = json parsing
456
if (same(notRunning, p)) return
457
inactivePlugins[id] = p
458
events.emit(notRunning ? 'pluginUpdated' : 'pluginInstalled', p)
@@ -665,9 +665,10 @@ export function parsePluginSource(id: string, source: string) {
665
666
function calculateBadApi(data: InactivePlugin) {
667
const r = data.apiRequired
668
- const [min, max] = Array.isArray(r) ? r : [r, r] // normalize data type
669
- data.badApi = min! > API_VERSION ? "may not work correctly as it is designed for a newer version of HFS - check for updates"
670
- : max! < COMPATIBLE_API_VERSION ? "may not work correctly as it is designed for an older version of HFS - check for updates"
668
+ const [min=0, max=Infinity] = Array.isArray(r) ? r : [r] // normalize data type
669
+ data.badApi = !r ? "missing mandatory property apiRequired"
670
+ : min > API_VERSION ? "may not work correctly as it is designed for a newer version of HFS - check for updates"
671
+ : min < COMPATIBLE_API_VERSION || max < API_VERSION ? "may not work correctly as it is designed for an older version of HFS - check for updates"
672
: undefined
673
}
674