Using fetch in backend scripts

[matshch]

Hi! I'm writing an importer from Notion and having trouble using fetch to get the data:

• in a frontend script fetch fails because Notion API does not set CORS headers, so it is a no-go,
• in a backend script I cannot properly call await fetch.

When I just use await fetch in a backend script, I get the next error: "await is only valid in async functions and the top level bodies of modules". I have found that since v0.48 your backend scripts are supposed to be synchronous, but I don't get how the fetch is supposed to be synchronous, looks like a gap in support there... I also can wrap this fetch call in an async function and call it, but I guess this will break transactional assumptions as the following code may execute after the main function has already ended.

The only proper solution to call fetch in a backend script that I see is api.runAsyncOnBackendWithManualTransactionHandling(), but then I don't understand the required transaction management, is it OK to ignore it and just call Api methods as is if I don't care about partial results?

[dosubot[bot]]

Hi @matshch! I'm Dosu and I’m helping the Trilium team.

Since Trilium v0.48, backend scripts are required to be synchronous, which means you can't use await fetch directly in a backend script because await only works inside async functions, and backend scripts should not be async for transaction safety and consistency release notes.

To perform asynchronous operations like fetch in backend scripts, you should use api.runAsyncOnBackendWithManualTransactionHandling(async () => { ... }) discussion. This lets you run async code, but you must manage transactions manually. If you ignore transaction management and just call API methods as is, it's technically possible, but you risk inconsistent state if something fails partway through—so it's only safe if you don't care about partial results or possible data inconsistency issue.

Here's a minimal example pattern:

await api.runAsyncOnBackendWithManualTransactionHandling(async () => {
    const response = await fetch("https://api.notion.com/v1/...");
    const data = await response.json();
    // Do Trilium API operations here
    // If you want transactional safety, group related changes and handle errors
});

If you want all-or-nothing changes, you'll need to implement your own rollback logic if something fails after partial changes. If you don't care about partial results, you can proceed without extra transaction handling, but be aware of the risks.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[matshch]

@dosu, that's basically what I've done for now, but there are still two issues worth discussing:

• Fetch API is not really usable for typical backend scripts, maybe that is something to consider fixing or documenting.
• It is not obvious how bad it is to skip transactions inside of api.runAsyncOnBackendWithManualTransactionHandling(). Is it only about atomicity of script changes, or is there some potential for internal consistency issues? If my script is idempotent, can I ignore the transaction handling?

[dosubot[bot]]

You're right that the Fetch API isn't straightforward to use in typical backend scripts—Trilium's backend scripting model is designed for synchronous code, so async operations like fetch require workarounds. This limitation isn't well-documented, and it would be helpful to clarify it in the official docs or improve support.

On transaction handling: skipping transactions inside api.runAsyncOnBackendWithManualTransactionHandling() is riskier than just losing atomicity. Without explicit transaction management, if an error or interruption happens mid-script, you can end up with partial updates and, more importantly, backend/frontend state divergence. The transactional wrapper in Trilium not only ensures all-or-nothing changes but also handles entity-change broadcasts and cache rollbacks to keep everything consistent. If you skip it, none of those safeguards run, so the system can get out of sync in subtle ways—not just incomplete data, but potentially stale or inconsistent state in the app itself (source).

If your script is idempotent, you reduce the risk of data corruption from partial updates, but you don't eliminate the risk of backend/frontend inconsistency. There's no official documentation or best practice that says idempotency is a safe workaround for skipping transaction handling—it's still at your own risk, and you should only do it if you fully understand and accept the potential for inconsistent state (source). If you want to be safe, always wrap your DB-modifying code in api.transactional() when using async backend scripts.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}