Runtime Under the Hood
What happens when a user opens and interacts with a ProofKit hybrid app.
This page explains the runtime behavior of a deployed ProofKit Web Viewer app: loading, communication, data fetching, caching, saving, and FileMaker-specific behavior.
Loading the app
When a user opens a FileMaker layout with a ProofKit Web Viewer, the Web Viewer loads the deployed HTML and JavaScript bundle from the FileMaker file.
Initial props
Many apps start by calling a FileMaker script before rendering the full UI. That script can return user context, configuration, permissions, or startup data the web app needs.
This is optional, but it is a good pattern when the app needs FileMaker context before showing a meaningful screen.
Communication bridge
The Web Viewer and FileMaker are separate runtimes. They communicate by passing JSON through FileMaker's script bridge:
- The web app calls FileMaker.
- A FileMaker script performs work.
- FileMaker returns structured data to the Web Viewer.
Under the hood, that bridge uses two FileMaker features:
- JavaScript in the Web Viewer can call
FileMaker.PerformScriptWithOption(script, parameter, option)to ask FileMaker to run a script. Claris documents this on Scripting with JavaScript in web viewers. - FileMaker can call back into the Web Viewer with the Perform JavaScript in Web Viewer script step.
Those APIs are asynchronous and string-based, so the raw version usually involves passing JSON, tracking callbacks, and deciding how a currently running FileMaker script should behave when JavaScript starts another one.
ProofKit libraries hide most of that callback plumbing so app code can use modern async patterns. fmFetch wraps the Web Viewer-to-FileMaker call and callback cycle. @proofkit/fmdapi and @proofkit/typegen build on FileMaker's data APIs and layout metadata so generated clients can read and write strongly typed FileMaker data without every app reimplementing the bridge details.
Caching and reactivity
ProofKit apps use TanStack Query for server state. In this context, server state means FileMaker state: the data in your FileMaker tables and the behavior exposed through your FileMaker scripts. You can think of those scripts and databases as the server-side piece, even when the app is running in a FileMaker file that is not hosted on a server.
TanStack Query is a React data-fetching library that handles caching, background refreshes, request deduping, and update synchronization for data that lives outside the browser. See the TanStack Query overview for more detail.
Data can be cached locally in the browser, refreshed in the background, and invalidated after writes so the UI stays responsive without manually reloading every screen.
Saving data
Web Viewer apps usually use explicit save and cancel actions. They do not automatically commit records when a user exits a field the way native FileMaker layouts can.
When saves need business logic, validation, or transactional behavior, send the payload to a FileMaker script and let the script perform the write.
Record locking
Typing into a Web Viewer form does not hold a FileMaker record lock. This is normal web app behavior, but it is different from editing directly in a FileMaker field.
Common strategies include:
- Check modification counts before saving.
- Use script-mediated saves for transaction-sensitive changes.
- Alert the user when a record changed since it was loaded.
Container data
Data passed through the Web Viewer bridge is JSON. Container data usually needs to be Base64-encoded before it is included in a JSON payload.
Printing and PDFs
For print or PDF workflows, the web app can generate an image or document payload, pass it to FileMaker, and let FileMaker use its native printing or Save as PDF capabilities.
Next step
Read Data Access for practical layout and Execute Data API guidance.