Skip to main content

base44 integration rules

This page is the detailed rule set referenced by the base44 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.

base44 builds React SPAs (Vite + Tailwind), and a naive integration breaks in predictable ways: AddressLookup.setup() with CSS-selector outputFields fights React's controlled inputs, the agent guesses an outdated package version, and it assumes the API key can reach the browser through a Secret when the plan doesn't allow it. Follow every rule below to pre-empt them.

Install the package​

  • Install @addresszen/address-lookup at the latest major: @addresszen/address-lookup@2. Do not guess a version number — older versions are out of date and the API differs.

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 component are mounted, guarded by a useRef so it runs exactly once (React Strict Mode mounts effects twice):

    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 setup() or outputFields / CSS-selector autofill for them — React overwrites direct DOM writes, so the fields never populate.

API key​

The AddressZen API key is a publishable browser key — it is designed to ship in client-side code and is protected by Allowed URLs, not by secrecy (exactly like a Stripe pk_ publishable key). How you supply it depends on the base44 plan:

  • Free plan (no Secrets / backend functions): Secrets and backend functions require Builder+. Do not try to read the key from a Secret, a VITE_ env var, or a backend function — none of those are available, and the autocomplete will silently never load. Instead, paste the ak_… key directly into the component as a constant. This is safe because it is a publishable key locked to your origin via Allowed URLs.
  • Builder+ plan: read the key from the ADDRESSZEN_API_KEY Secret via a small backend function that returns it to the frontend, and fetch it on mount into state. A VITE_-prefixed env var also works if your build injects it at build time.

If you are unsure which plan is active, just paste the key directly — it always works and is safe for a publishable 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. A 401 almost always means the app's origin is missing from the key's Allowed URLs.

Reference docs​