Writing custom modules

[aitor-imaz]

Sorry if this has been documented already but I wasn’t able to find an answer.

Are custom modules meant to be integrated within the Yuvomi infrastructure (database, routing, API, etc) or fully external? In other words, if I write a custom module, can it access to the Yuvomi database or is the module expected to have its own database? Likewise, can the module define routes within Yuvomi or is the module expected to call endpoints in a different server?

If the module is meant to be fully integrated, are there examples or recommended practices on how to implement the above?

Thanks.

[ulsklyc]

Good question — this is documented, but it's easy to miss: see MODULES.md at the repo root.

The short answer: third-party modules are client-side (frontend) only. They are not server-side plugins.

What a module is: a folder in modules/<id>/ with a module.json manifest and an entry .js file that exports render(container, context). Yuvomi's server discovers it, validates the manifest, and serves its static assets at /api/v1/modules/assets/<id>/.... The client registers a single page route at /m/<id> and (optionally) a left-menu entry. Copy the folder in, enable it under Settings → Modules → Navigation — no rebuild, no core edits.

On your specific questions:

• Can a module access the Yuvomi database? Not directly. There's no server-side hook — a module can't open a DB connection, add migrations, or register Express routes. What it can do is run in the browser and call the existing Yuvomi REST API via the built-in fetch wrapper (import { api } from '/api.js'), which carries the user's session auth and CSRF token automatically. So you read/write Yuvomi data through the same authorized endpoints the core UI uses.
• Can a module define routes within Yuvomi? Only the one client-side page route /m/<id> (the path is fixed to the module id by design). It cannot add new server /api/... endpoints.
• If you need your own persistence / server logic / custom endpoints: run a separate backend service and have your client module call it (respecting the same CSP/security rules — no external CDNs, no innerHTML, escape untrusted values). The alternative is forking core and adding a real server/routes/* + migration, but that's no longer a "module."

A minimal working example (manifest + render() entry calling /auth/me) is in MODULES.md. The modules/ folder ships empty, so that doc is currently the canonical reference.

[aitor-imaz]

Thanks for the clarification, that's very helpful. I was aware of the MODULES.md document, but it wasn't clear to me what the exact implementation model for modules is. Specifically whether modules could contain server-side components in addition to client-side code, or if they were strictly frontend-only. I don't think I fully appreciated that modules are intentionally limited to browser-side functionality.

That raises a follow-up question regarding external backends. Suppose I have a new backend service running on a different host and/or port. Since modules execute in the browser, CSP and browser security policies would typically restrict direct communication with that service unless it's explicitly allowed. How is this expected to be handled in Yuvomi? Should developers be placing a reverse proxy in front of the new backend service so everything appears under the Yuvomi origin? Or is there some intended mechanism for extending the CSP rules to allow specific external hosts?

One other (unrelated) thing I noticed: custom modules don't appear in the dashboard module listing. Is that omission intentional and part of the current design, or is it simply functionality that hasn't been implemented yet?

[ulsklyc]

Great follow-ups — both touch real boundaries of the current design.

External backends & CSP. You read it correctly. Yuvomi ships a strict CSP with connect-src 'self' (set in server/index.js via helmet), and there is currently no env var or config hook to add allowed origins. So a browser-side module cannot talk directly to a backend on a different host/port — the browser will block it.

The intended approach is exactly what you suspected: put your service behind a reverse proxy so it appears under the Yuvomi origin. Expose it on a path (e.g. /ext/myservice/…) on the same scheme+host+port that serves Yuvomi; your module then calls that same-origin path and CSP is satisfied. This also keeps everything behind the one TLS endpoint and the existing session/CSRF model. If you'd rather relax CSP instead, the only way today is to fork core and add your host to the connectSrc array — but at that point you're patching Yuvomi, not shipping a drop-in module. A configurable CSP allowlist would be a reasonable feature request if the proxy route doesn't fit your setup.

Modules on the dashboard. Not an oversight you can configure away — it's a current limitation. The dashboard widget catalog is a fixed, core-only set (tasks, calendar, meals, shopping, birthdays, budget, family, notes, weather), and there is no API for a module to register a dashboard widget. A module's only surfaces are its left-menu entry and its /m/<id> page. So enabled modules appear in the navigation but never on the dashboard. Worth a feature request if module-contributed dashboard widgets would be valuable to you.

[aitor-imaz]

Thanks for the clarifications. To be honest, I'm currently mostly playing with non-core modules, trying to understand what they can be used for and how they would be architected.

Putting the services behind a reverse proxy is a reasonable and easy to handle approach. For my testing purposes I have modified the helmet/CSP rules (connectSrc) to allow connections to my test backend services and it works well, but I'd rather not patch the Yuvomi source. I will experiment with a reverse proxy.

As for the dashboard, like I said, I'm only playing for now and the modules I have created don't make much sense on the dashboard, but it's good to know that if I were to come up with a module that did make sense, I could submit a feature request.

Thanks for your support!

[aitor-imaz]

As a follow-up, I'd like to mention an issue I encountered during testing. The MODULES.md document states that "Modules may import public Yuvomi browser libraries such as /api.js, /i18n.js, and utilities under /utils/." While this isn't necessarily a problem, I think the documentation should more strongly encourage the use of api.js.

One important reason is that api.js automatically prefixes API requests with api/v1. This matters because the service worker appears to treat requests differently depending on their path: only requests beginning with api/ bypass the cache and reach the backend. During testing, I found that custom backend endpoints that did not use the api/ prefix could return cached (stale) responses instead of fresh data from the server.

Because of this behavior, developers implementing custom backend services should either use api.js or ensure that their endpoints are registered under the api/ path. Calling this out explicitly in the documentation could help prevent some of the subtle caching issues that I experienced.

[ulsklyc]

Good catch, thank you. You are right about the important boundary here: Yuvomi's service worker bypasses /api/ requests, while other same-origin GET paths can still fall through to the app-shell caching strategy.

The intended guidance is:

• use import { api } from '/api.js' for Yuvomi's built-in /api/v1 endpoints, because it handles the prefix, session credentials, CSRF handling, and non-cached fetches for user data;
• if a module talks to a separate reverse-proxied backend with dynamic responses, expose that backend under a same-origin /api/... path, or explicitly extend the service-worker routing for that path.

I'll make this explicit in the module documentation so module authors do not accidentally put dynamic backend calls behind a cacheable app-shell path. Thanks for testing this so carefully.