doc: distinguish between backend and frontend DirEntry
Massimo Melina committed
Jan 28, 2026 at 14:37 UTC
49dd3e0371846aee11ab8e9830b5105c5793b649
2 files changed
+27
-17
README.md
+12
-9
@@ -22,7 +22,7 @@ Access your files via web, directly from your disk.
22
23
- Be your own server: share files **fresh from your disk** with **unlimited** space and bandwidth.
24
- **Fast:** try zipping 100GB – download starts immediately.
25
-- **Smart:** HFS detects problems and suggest solutions.
25
+- **Smart:** HFS detects problems and suggests solutions.
26
- Present things the way you want: share **even a single file**, even with a different name, with our *virtual file system*.
27
- **Monitor** all activities in real-time.
28
- **Bandwidth throttling**: decide how much to give.
@@ -61,7 +61,7 @@ Runs on: Windows, Linux, macOS, FreeBSD, Android
61
- [reverse-proxy support](https://github.com/rejetto/hfs/wiki/Reverse-proxy)
62
- comments in file descript.ion
63
- integrated media player
64
-- [customizable with html, css and javascript](https://github.com/rejetto/hfs/wiki/Customization)
64
+- [customizable with html, css, and javascript](https://github.com/rejetto/hfs/wiki/Customization)
65
- dynamic-dns updater
66
67
## Installation
@@ -75,17 +75,17 @@ The minimum Windows version required is 10 or Server 2019.
75
1. Download the zip file for your operating system from https://github.com/rejetto/hfs/releases
76
- ⚠️ Antivirus problems on Windows? [READ THIS](https://github.com/rejetto/hfs/wiki/Antivirus)
77
- ⚠️ If you have Linux ARM or other unlisted/unsupported platforms, please see the [Other systems](#other-systems) section.
78
-2. Unzip and launch `hfs` file.
78
+2. Unzip and launch the `hfs` file.
79
- ⚠️ Mac: if you get *"cannot be opened because it is from an unidentified developer"*,
80
you can hold `control` key while clicking, then click `open`.
81
-3. The browser should automatically open on `localhost` address, so you can configure the rest in the Admin-panel.
81
+3. The browser should automatically open at `localhost`, so you can configure the rest in the Admin-panel.
82
83
Troubleshooting
84
- - if a browser cannot be opened on the computer where you are installing HFS,
84
+ - If a browser cannot be opened on the computer where you are installing HFS,
85
you should enter this command in the HFS console: `create-admin <PASSWORD>`
86
- - if you cannot access the console (like when you are running as a service),
86
+ - If you cannot access the console (like when you are running as a service),
87
you can [edit the config file to add your admin account](config.md#accounts)
88
- - if you don't want to use an editor you can create the file with this command:
88
+ - If you don't want to use an editor, you can create the file with this command:
89
90
`echo "create-admin: PASSWORD" > config.yaml`
91
@@ -94,10 +94,10 @@ If you don't like this behavior, disable it in the Admin-panel or enter this con
94
95
### Other systems
96
97
-If can't or don't want to run our binary versions, you can try this:
97
+If you can't or don't want to run our binary versions, you can try this:
98
99
1. [install node.js](https://nodejs.org) version 20 (or greater, but then compatibility is not guaranteed)
100
-2. execute at command line `npx hfs@latest`
100
+2. run at the command line `npx hfs@latest`
101
102
The `@latest` part is optional, and ensures that you are always up to date.
103
@@ -138,6 +138,7 @@ If your language is missing, please consider [translating yourself](https://gith
138
- `--consoleFile PATH` to also output all stdout/stderr to a file
139
- Set env.var. `DISABLE_UPDATE=1` (for containers)
140
- Launch with `--debug` or env.var. `HFS_DEBUG=1` to generate additional console logs
141
+- Launch with `--no-central` to skip fetching updated info from GitHub (uses built-in data only)
142
143
## Contribute
144
@@ -172,6 +173,8 @@ There are several ways to contribute
173
174
## More
175
176
+- [Additional information (Wiki)](https://github.com/rejetto/hfs/wiki)
177
+
178
- [APIs](https://github.com/rejetto/hfs/wiki/APIs)
179
180
- [Build yourself](dev.md)
dev-plugins.md
+15
-8
@@ -166,9 +166,21 @@ used must be strictly JSON (thus, no single quotes, only double quotes for strin
166
You can read more in [the ctx object](#the-ctx-object) section.
167
168
- `unload: function` called when unloading a plugin. This is a good place for example to clearInterval().
169
-- `onDirEntry: ({ entry: DirEntry, listUri: string, ctx, node: VfsNode }) => Promisable<void | false>`
169
+- `onDirEntry: ({ entry: DirEntryBackend, listUri: string, ctx, node: VfsNode }) => Promisable<void | false>`
170
by providing this callback you can manipulate the record that is sent to the frontend (`entry`),
171
- or you can return false to exclude this entry from the results. Refer to source `frontend/src/state.ts`.
171
+ or you can return false to exclude this entry from the results.
172
+ `DirEntryBackend` fields:
173
+ - `n: string` name of the entry. (May include relative path when searching in sub-folders.)
174
+ - `s?: number` size of the entry, in bytes. It may be missing, for example for folders.
175
+ - `m?: Date` modified-time.
176
+ - `c?: Date` creation-time.
177
+ - `p?: string` permissions.
178
+ - `comment?: string` comment for the entry.
179
+ - `web?: boolean` true for web links.
180
+ - `url?: string` target url for links.
181
+ - `target?: string` target for links.
182
+ - `icon?: string | true` icon override or true for "specific for this file".
183
+ - `order?: number` custom sort order.
184
- `config: Functionable<{ [key]: FieldDescriptor }, values:object>` declare a set of admin-configurable values owned by the plugin
185
that will be displayed inside Admin-panel for change. Each property is identified by its key,
186
and the descriptor is another object with options about the field.
@@ -527,16 +539,11 @@ This is a list of available frontend-events, with respective object parameter an
539
540
- `additionalEntryDetails`
541
- use this to add HTML at the beginning of the `entry-details` container.
530
- - parameter `{ entry: DirEntry }` current entry. The `DirEntry` type is an object with the following properties:
542
+ - parameter `{ entry: DirEntry }` current entry. `DirEntry` extends `DirEntryBackend` and adds:
543
- `name: string` name of the entry.
544
- `ext: string` just the extension part of the name, dot excluded and lowercase.
545
- `isFolder: boolean` true if it's a folder.
534
- - `n: string` name of the entry, including relative path when searched in sub-folders.
546
- `uri: string` absolute uri of the entry.
536
- - `s?: number` size of the entry, in bytes. It may be missing, for example for folders.
537
- - `c?: Date` creation-time.
538
- - `m?: Date` modified-time.
539
- - `p?: string` permissions missing
547
- `cantOpen: boolean` true if current user has no permission to open this entry
548
- `getNext/getPrevious: ()=>DirEntry` return next/previous DirEntry in list
549
- `getNextFiltered/getPreviousFiltered: ()=>DirEntry` as above, but considers the filtered-list instead