# Lovable

Lovable generates React + Vite apps backed by Lovable Cloud (Supabase). The Address Lookup 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")

International address autocomplete on any address form, powered by the [Address Lookup](/docs/address-lookup.md) widget.

## 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 addresszen.com/signup](https://addresszen.com/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%20international%20address%20autocomplete%20to%20the%20billing%20form%20using%20%40addresszen/address-lookup.%20Install%20the%20npm%20package%2C%20mount%20AddressLookup.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%20AddressZen%20key%20as%20VITE_ADDRESSZEN_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.addresszen.com/docs/address-lookup.md)

Or paste manually:

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

@addresszen/address-lookup npm package.



- Install the package.

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

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

- Use Lovable's "Add API Key" feature to store my AddressZen key as

  VITE_ADDRESSZEN_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.addresszen.com/docs/address-lookup.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 [AddressZen dashboard](https://addresszen.com/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.addresszen.com/v1/autocomplete/addresses with the

ADDRESSZEN_API_KEY secret, and returns suggestions to the frontend. The

frontend should not import @addresszen/address-lookup directly —

instead build a simple autocomplete that hits the Edge Function.
```

Store the key as `ADDRESSZEN_API_KEY` (no `VITE_` prefix) so it stays server-side. The Edge Function reads it via `Deno.env.get("ADDRESSZEN_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://addresszen.com/account).
* **`process.env.VITE_ADDRESSZEN_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_ADDRESSZEN_API_KEY`."*
* **The agent stored `ADDRESSZEN_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_ADDRESSZEN_API_KEY`.
* **CORS error in the browser console:** check the request URL — the widget should hit `api.addresszen.com`. If Lovable proxied it incorrectly, ask: *"Call api.addresszen.com directly from the browser. Don't proxy through Supabase."*

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

* File an issue: [github.com/addresszen/feedback](https://github.com/addresszen/feedback/issues)
* Email: <support@addresszen.com>