fmBridge()

fmBridge() is the Vite plugin that lets you develop a Web Viewer app in a browser instead of inside FileMaker's Web Viewer. With it running, code that calls window.FileMaker or uses @adt/fmdapi works the same in pnpm dev as it does after you deploy: no rebuild, no re-upload, no mock data.

Why it matters

A Web Viewer app expects to live inside FileMaker. Outside of FileMaker, window.FileMaker doesn't exist and any script call throws. Without a bridge, the only way to test the real integration is to build, deploy, and reopen the file every time you change a line of code.

fmBridge() removes that loop by forwarding window.FileMaker calls from the development browser to your open FileMaker file. A deployed Web Viewer doesn't use it because FileMaker provides window.FileMaker directly.

Apps created by adt app add already have this wired up in vite.config.ts. This page covers what the bridge does and how to diagnose it when something's off.

How it works

fmBridge() asks FileMaker Pro which files it has open, using the same Agent Access feature ADT's other development-time tools use. It resolves which file to talk to on every call — there's no persistent session to keep alive:

  1. Your development page calls window.FileMaker.PerformScriptAsync (or a @adt/fmdapi function that wraps it), the same call it would make inside a real Web Viewer.

  2. fmBridge() supplies that function during vite dev. It sends the call same-origin, to the Vite dev server at /__fm/fmfetch.

  3. The dev server asks FileMaker Pro for its open files and picks the one to use — the only one open, or the one named by the fileName option.

  4. The dev server performs the script in that file over Agent Access and returns its Exit Script result to the page.

Setup

Copy 
import { fmBridge } from "@adt/fmdapi/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [fmBridge()],
});

fmBridge() only activates during vite dev (Vite's serve command). In a production build it does nothing, so shipping the plugin in vite.config.ts is safe.

Options are all optional:

  • fileName — tell the bridge which open FileMaker file to use. Needed only when FileMaker Pro has more than one file open at once; with a single file open, fmBridge() uses it automatically.

Developing in a real browser

To actually exercise the bridge, your FileMaker file needs to be open with Agent Access on, separate from your Vite dev server:

  1. Open your FileMaker file in FileMaker Pro 26.1 with Agent Access on. There's no script to run and nothing to keep open — the file just needs to be open in FileMaker Pro. See System Requirements for turning on Agent Access.

    The first call that reaches the file makes FileMaker Pro show a prompt asking you to allow it. The prompt appears in FileMaker Pro, not in your browser, so a page that seems to be waiting on data may be waiting on you to click Allow. The grant lasts until you quit FileMaker Pro; after a restart, the dev server's next call asks again.

  2. Start your dev server.

    Copy 
    pnpm dev

  3. Open the Vite dev URL in your browser. By default the template's dev server runs on port 5175. The page loads normally, and any FileMaker script calls in your code route through the bridge to the real, open file.

When no file is open, the dev server still starts — it injects a stub window.FileMaker whose methods reject with a message explaining that FileMaker Pro doesn't have the file open.

When the file is closed or the prompt is waiting

If FileMaker quits, restarts, or the file closes while your development page is open, script calls stop responding — fmBridge() re-resolves the file on every call, so there's nothing to reach once it's closed. Reopen the file, then reload the browser page.

A call that seems to hang is often the grant prompt waiting behind another window rather than a real failure, especially right after FileMaker Pro has been restarted — check for it before assuming something is broken. See Components and Web Viewer connection problems for the full diagnosis and fix.