Skip to main content

Anything integration rules

This page is the detailed rule set referenced by the Anything starter prompt. It exists so the prompt you paste into the builder can stay short — the agent fetches this page and follows the rules below. It is intentionally kept out of the sidebar.

Anything builds React apps, and a naive integration breaks in predictable ways: a <script> tag written in JSX never executes (so the widget never loads), CSS-selector autofill (outputFields) silently loses to React's controlled inputs, and setup runs before the script or API key is ready. Follow every rule below to pre-empt them.

Loading the library​

  • Do not put a <script> tag in the JSX/returned markup. React does not execute script tags rendered that way, so the widget never loads and window.AddressZen stays undefined.

  • Load it inside a useEffect by creating the element yourself, and track readiness in state:

    useEffect(() => {
      const s = document.createElement("script");
      s.src = "https://cdn.jsdelivr.net/npm/@addresszen/address-lookup@2";
      s.async = true;
      s.onload = () => setScriptReady(true);
      document.body.appendChild(s);
    }, []);

    The global is window.AddressZen.AddressLookup.

  • If, and only if, your build can resolve npm packages, you may instead import { AddressLookup } from "@addresszen/address-lookup" and skip the script loader. Do not invent any other package name.

Wiring the widget​

  • The search input (address line 1) must be uncontrolled: give it id="line_1" but do not put value=... or onChange=... on it. The widget reads and writes this field directly; binding React state to it fights the library and breaks the dropdown.

  • Initialise with AddressLookup.watch (not setup), once both the API key and the script are ready, guarded by a useRef so it runs exactly once:

    AddressLookup.watch({
      inputField: "#line_1",
      apiKey,
      onAddressRetrieved: (address) => {
        setForm({
          line_1: address.line_1,
          line_2: address.line_2,
          city: address.city,
          state: address.state,
          zip_plus_4_code: address.zip_plus_4_code,
          country: address.country,
        });
      },
    });

  • Populate every other field from the onAddressRetrieved callback into React state. Those fields are controlled (value + onChange). Do not use outputFields / CSS-selector autofill for them — React overwrites direct DOM writes.

API key​

  • Add a backend function at web/api/azen-config/route.ts that reads the ADDRESSZEN_API_KEY Saved Secret and returns it to the frontend. Fetch it on mount into state. Do not hardcode the key.

Errors​

  • Pass onSearchError and onSuggestionError to watch(). If the AddressZen API returns a 4xx error, surface the error's message to the user — do not swallow it.

Reference docs​