| 1 | This file is mostly aimed to developers. |
| 2 | |
| 3 | # Building instructions |
| 4 | |
| 5 | 0. Install [Node.js](https://nodejs.org/) 22 |
| 6 | 1. Launch `npm run build-all` in the root |
| 7 | |
| 8 | At this stage you have a javascript output. For binary files you'll also have to `npm run dist-bin`. |
| 9 | |
| 10 | ## Troubleshooting |
| 11 | |
| 12 | - If you get error "Rollup failed to resolve import "@mui/icons-material/..." |
| 13 | - edit `admin/src/vite.config.ts` and remove the `vitePluginImport` part |
| 14 | |
| 15 | # Dev environment |
| 16 | |
| 17 | 0. `npm install` |
| 18 | 1. `npm run watch-server-full` and leave it running. It will serve server stuff plus will proxy frontend and admin files. |
| 19 | |
| 20 | If you don't want this proxying version, you can use `npm run watch-server` but after both frontend and admin have |
| 21 | been built, so their files are available in `dist` folder. |
| 22 | |
| 23 | # Tests |
| 24 | |
| 25 | To run tests |
| 26 | - `npm run build-all` |
| 27 | - `npm run test-with-server` (backend tests) |
| 28 | - `npx playwright test` (UI tests) |
| 29 | |
| 30 | # File organization |
| 31 | |
| 32 | The project is roughly divided in Server + Frontend + Admin, where Frontend is a web interface intended to access |
| 33 | shared files, while Admin is the web interface for configuration/administration. |
| 34 | Server resides in the project's root, with its "src" folder, while Frontend and Admin are inside folders "frontend" |
| 35 | and "admin" respectively, each with its own "src" folder within. |
| 36 | |
| 37 | Additionally, you have the following folders: |
| 38 | - mui-grid-form: a lib used by Admin to easily build forms |
| 39 | - plugins: a collection of plugins that are pre-installed |
| 40 | - shared: code shared between Frontend and Admin |
| 41 | - tests: automated tests with related resources |
| 42 | - e2e: automated UI tests (first execution will give an error because it's creating screenshots) |
| 43 | |
| 44 | # Known problems |
| 45 | - vite's proxying server (but also CRA's) doesn't play nicely with SSE, leaving sockets open |
| 46 | - automatic tests 'upload.interrupted' is subject to race conditions and may occasionally fail |
| 47 | |
| 48 | # Guidelines |
| 49 | |
| 50 | - For strings, I'm using double-quotes for text that's read by the user, and single-quotes elsewhere. Backticks can be any. |
| 51 | - All keys that go in yaml should use snake_case. |
| 52 | - Reason: we want something that is both easy for the user and maps directly in our code. |
| 53 | Spaces and kebab-case don't play well with javascript and camel is less readable for the user. |
| 54 | - API names should start with get_ if and only if they provide information without making changes. |
| 55 | - All parameters that contain a *uri* should have a name that starts with `uri`. |
| 56 | - 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 |
| 57 | price of using an extra language that is also necessary to switched in and out multiple times when stuff is nested. |
| 58 | - All calls to async functions that don't want/need to "await" should be using the "void" operator to clarify it's |
| 59 | intentional and not that you just forgot to await. Don't confuse the void operator with the void type. |
| 60 | |
| 61 | # Project design |
| 62 | |
| 63 | - At the moment the admin-panel was designed to be completely separated from the "user" frontend |
| 64 | to keep the latter smaller and to allow alternative frontends creation without having to deal with |
| 65 | the complexity of the admin-panel. |
| 66 | |
| 67 | Of course this comes with a price to pay on the programmer's side, more work to do. |
| 68 | |
| 69 | # Thanks to |
| 70 | |
| 71 | [](https://jb.gg/OpenSource) |