# Lovable

Lovable generates React + Vite apps backed by Lovable Cloud (Supabase). The Address Finder widget runs in the browser — give Lovable your API key via its built-in **Add API Key** modal, then restrict the key to your deployed domain.

## What you'll add[​](#what-youll-add "Direct link to What you'll add")

UK and international address autocomplete on any address form, powered by the [Address Finder](/docs/address-finder.md) widget. For UK-only postcode → address dropdowns, use [Postcode Lookup](/docs/postcode-lookup.md) instead.

## 1. Get an API key[​](#1-get-an-api-key "Direct link to 1. Get an API key")

* Quick test: paste `ak_test` as your key. Capped at 5 lookups/day. Will break in production.
* Real key: [sign up at ideal-postcodes.co.uk/signup](https://ideal-postcodes.co.uk/signup) for a free trial balance.

## 2. Starter prompt[​](#2-starter-prompt "Direct link to 2. Starter prompt")

Open Lovable with this prompt pre-filled:

[**Open in Lovable →**](https://lovable.dev/?autosubmit=true#prompt=Add%20UK%20and%20international%20address%20autocomplete%20to%20the%20billing%20form%20using%20%40ideal-postcodes/address-finder.%20Install%20the%20npm%20package%2C%20mount%20AddressFinder.setup%28%29%20on%20the%20address%20line%201%20input%2C%20and%20populate%20the%20other%20address%20fields%20from%20the%20suggestion%20callback.%20Use%20Lovable%27s%20Add%20API%20Key%20feature%20to%20store%20my%20Ideal%20Postcodes%20key%20as%20VITE_IDEAL_POSTCODES_API_KEY%20%28the%20widget%20runs%20in%20the%20browser%2C%20so%20the%20VITE_%20prefix%20is%20required%20for%20import.meta.env%29.%20Reference%20docs%3A%20https%3A//docs.ideal-postcodes.co.uk/docs/address-finder.md)

Or paste manually:

```
Add UK and international address autocomplete to the billing form using

the @ideal-postcodes/address-finder npm package.



- Install the package.

- Mount AddressFinder.setup() on the address line 1 input. Populate

  line 2, city, postcode and county from the suggestion callback.

- Use Lovable's "Add API Key" feature to store my Ideal Postcodes key

  as VITE_IDEAL_POSTCODES_API_KEY — the widget runs in the browser, so

  the VITE_ prefix is required for it to reach client code via

  import.meta.env.

- Reference docs:

  https://docs.ideal-postcodes.co.uk/docs/address-finder.md

  https://docs.ideal-postcodes.co.uk/docs/address-finder/configure.md
```

Lovable installs the package, generates the form, then pops up the **Add API Key** modal asking for your key value. Paste it there — not into the chat — and Lovable stores it as a secret in your project (Cloud → Secrets).

## 3. Lock down the key (required before going live)[​](#3-lock-down-the-key-required-before-going-live "Direct link to 3. Lock down the key (required before going live)")

The widget calls our API from the browser, so the key is visible to anyone who views your deployed site. Restrict it to your origin:

1. After Lovable deploys, copy the preview URL (e.g. `your-app.lovable.app`).
2. In your [Ideal Postcodes dashboard](https://ideal-postcodes.co.uk/account), open the key's settings.
3. Add `your-app.lovable.app` and your custom production domain (if any) to [Allowed URLs](/docs/guides/allowed-urls.md).
4. If `*` is present, remove it — that's the default-permissive setting and accepts requests from any origin.

Skip this step and a casual visitor can lift the key from your site's network tab and burn your quota elsewhere.

## Prefer to keep the key server-side?[​](#prefer-to-keep-the-key-server-side "Direct link to Prefer to keep the key server-side?")

For higher-security setups, ask Lovable to proxy the lookup through a Supabase Edge Function:

```
Move the address autocomplete calls behind a Supabase Edge Function.

The function accepts a search query, calls

https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses with the

IDEAL_POSTCODES_API_KEY secret, and returns suggestions to the

frontend. The frontend should not import @ideal-postcodes/address-finder

directly — instead build a simple autocomplete that hits the Edge

Function.
```

Store the key as `IDEAL_POSTCODES_API_KEY` (no `VITE_` prefix) so it stays server-side. The Edge Function reads it via `Deno.env.get("IDEAL_POSTCODES_API_KEY")`. Allowed URLs is then optional since the key never reaches the browser. Trade-off: you lose the polished suggestion UI the widget provides.

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

* **`401 Unauthorized` after deploy:** your `*.lovable.app` subdomain isn't on the key's Allowed URLs list. Add it in the [dashboard](https://ideal-postcodes.co.uk/account).
* **`process.env.VITE_IDEAL_POSTCODES_API_KEY` is `undefined`:** Vite exposes client env vars on `import.meta.env`, not `process.env`. Tell Lovable: *"Read the key from `import.meta.env.VITE_IDEAL_POSTCODES_API_KEY`."*
* **The agent stored `IDEAL_POSTCODES_API_KEY` (no `VITE_` prefix) and the widget can't see it:** the prefix is what makes Vite bundle the variable into the client. Rename the secret in Cloud → Secrets, or ask the agent to recreate it with `VITE_IDEAL_POSTCODES_API_KEY`.
* **CORS error in the browser console:** check the request URL — the widget should hit `api.ideal-postcodes.co.uk`. If Lovable proxied it incorrectly, ask: *"Call api.ideal-postcodes.co.uk directly from the browser. Don't proxy through Supabase."*

## Need help?[​](#need-help "Direct link to Need help?")

* File an issue: [github.com/ideal-postcodes/feedback](https://github.com/ideal-postcodes/feedback/issues)
* Email: <support@ideal-postcodes.co.uk>