This file is mostly aimed to developers.

Building instructions

0. Install Node.js 22
1. Launch npm run build-all in the root

At this stage you have a javascript output. For binary files you'll also have to npm run dist-bin.

Troubleshooting

• If you get error "Rollup failed to resolve import "@mui/icons-material/..."
  • edit admin/src/vite.config.ts and remove the vitePluginImport part

Dev environment

0. npm install
1. npm run watch-server-full and leave it running. It will serve server stuff plus will proxy frontend and admin files.

If you don't want this proxying version, you can use npm run watch-server but after both frontend and admin have been built, so their files are available in dist folder.

Tests

To run tests

• npm run build-all
• npm run test-with-server (backend tests)
• node --import tsx --test tests/shutdown.test.ts (shutdown tests, no server needed)
• node --import tsx --test tests/plugin-server-cleanup.test.ts (after compiling the server; starts isolated HTTP and HTTPS servers)
• Docker bootstrap: build with docker build --build-arg HFS_VERSION=3.3.0 -t hfs:bootstrap-test ., then run HFS_DOCKER_TEST_IMAGE=hfs:bootstrap-test node --import tsx --test tests/docker-bootstrap.test.ts (requires Docker; uses temporary containers and configuration directories).
• npx playwright test (UI tests)
• For the DataTable component regression, start Admin with npm run start --workspace=admin -- --port 3112 --strictPort, then run PLAYWRIGHT_HTML_OPEN=never ADMIN_DATA_TABLE_URL=http://127.0.0.1:3112/#/monitoring npx playwright test admin-data-table --workers=1 --project=chromium.
• With the same Vite server, test FileField and its real picker using PLAYWRIGHT_HTML_OPEN=never ADMIN_FILE_FIELD_URL=http://127.0.0.1:3112/#/monitoring npx playwright test admin-file-field --workers=1 --project=chromium. The test serves a local filesystem-list fixture and closes it afterwards.

For DateTimeField, use the same Vite setup with ADMIN_DATE_TIME_URL=http://127.0.0.1:3112/#/monitoring PLAYWRIGHT_HTML_OPEN=never npx playwright test admin-date-time --workers=1. Without the URL override the component test is skipped.

The normal Playwright configuration also starts its test servers, so prepare the build as above. Without ADMIN_APP_URL, this dev-only test is skipped.

File organization

The project is roughly divided in Server + Frontend + Admin, where Frontend is a web interface intended to access shared files, while Admin is the web interface for configuration/administration.
Server resides in the project's root, with its "src" folder, while Frontend and Admin are inside folders "frontend" and "admin" respectively, each with its own "src" folder within.

Additionally, you have the following folders:

• mui-grid-form: a lib used by Admin to easily build forms
• plugins: a collection of plugins that are pre-installed
• shared: code shared between Frontend and Admin
• tests: automated tests with related resources
• e2e: automated UI tests (first execution will give an error because it's creating screenshots)

Known problems

• vite's proxying server (but also CRA's) doesn't play nicely with SSE, leaving sockets open
• automatic tests 'upload.interrupted' is subject to race conditions and may occasionally fail

Guidelines

• For strings, I'm using double-quotes for text that's read by the user, and single-quotes elsewhere. Backticks can be any.
• All keys that go in yaml should use snake_case.
  • Reason: we want something that is both easy for the user and maps directly in our code. Spaces and kebab-case don't play well with javascript and camel is less readable for the user.
• API names should start with get_ if and only if they provide information without making changes.
• All parameters that contain a uri should have a name that starts with uri.
• React parts don't use JSX. I used JSX for a couple of years before deciding that it is not good enough to pay the price of using an extra language that is also necessary to switched in and out multiple times when stuff is nested.
• All calls to async functions that don't want/need to "await" should be using the "void" operator to clarify it's intentional and not that you just forgot to await. Don't confuse the void operator with the void type.

Project design

• At the moment the admin-panel was designed to be completely separated from the "user" frontend to keep the latter smaller and to allow alternative frontends creation without having to deal with the complexity of the admin-panel.

  Of course this comes with a price to pay on the programmer's side, more work to do.

Thanks to