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), so use the @ideal-postcodes/react component. It renders its own <input>, attaches the widget, and hands the selected address back through onAddressRetrieved: no useEffect, useRef, CSS selectors, or controlled/uncontrolled juggling. The one thing base44 still gets wrong is the API key: it assumes a Secret can reach the browser when the plan doesn't allow it. The rule below pre-empts that.

Install the package​

  • Install @ideal-postcodes/react. It pulls in @ideal-postcodes/address-finder automatically; you don't need to add it separately.

Wiring the widget​

  • Render the component and read the resolved address from onAddressRetrieved:

    import { AddressFinder } from "@ideal-postcodes/react";

    <AddressFinder
      apiKey={apiKey}
      onAddressRetrieved={(address) => {
        setForm({
          line_1: address.line_1,
          line_2: address.line_2,
          line_3: address.line_3,
          post_town: address.post_town,
          postcode: address.postcode,
          country: address.country,
        });
      }}
    />

  • The component draws its own search <input>. To reuse a styled input from your design system, pass it as a single child instead (wrap mode): <AddressFinder apiKey={apiKey} ...><input className="..." /></AddressFinder>.

  • Populate every other field from the onAddressRetrieved callback into React state. Those fields are controlled (value + onChange) as normal; the component never writes to them directly.

  • The stylesheet is auto-injected by default (injectStyle defaults to true), so the dropdown is styled out of the box. No separate CSS import is required.

API key​

The Ideal Postcodes 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 to the apiKey prop 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, pass the ak_… key directly as the apiKey prop 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 IDEAL_POSTCODES_API_KEY Secret via a small backend function that returns it to the frontend, fetch it on mount into state, and pass that state as apiKey. A VITE_-prefixed env var also works if your build injects it at build time.

If you are unsure which plan is active, just pass the key directly. It always works and is safe for a publishable key.

Errors​

  • Pass onSearchError and onSuggestionError props. If the Ideal Postcodes 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​