# Replit

Replit Agent generates real React + Vite + Express apps and stores credentials in **Repl Secrets**, which are surfaced as environment variables to your running app. If you ask Agent for a service that needs an API key, it will pause mid-build and prompt you to paste one into Secrets.

## 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. Store the key in Repl Secrets[​](#2-store-the-key-in-repl-secrets "Direct link to 2. Store the key in Repl Secrets")

In your Repl:

1. Open the **Secrets** tool (padlock icon in the workspace sidebar).
2. Add a new secret: key `IDEAL_POSTCODES_API_KEY`, value `ak_…`.
3. Save.

Agent will read `process.env.IDEAL_POSTCODES_API_KEY` (Node) directly. If the app uses **Vite** (Replit Agent's default React stack), the secret must be renamed `VITE_IDEAL_POSTCODES_API_KEY` so it reaches the browser bundle via `import.meta.env`. The starter prompt below tells Agent to handle this.

Tip: if you skip step 2 and ask Agent to wire the widget up first, it will prompt you for the key mid-build and add the Secret for you.

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

Paste this into the Replit Agent chat:

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

@ideal-postcodes/address-finder.



- Install the npm package.

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

  other address fields from the callback.

- Read the API key from a Repl Secret named IDEAL_POSTCODES_API_KEY.

  If the app uses Vite, expose it as VITE_IDEAL_POSTCODES_API_KEY and

  read via import.meta.env. Prompt me for the value if it isn't set.

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

- Reference for callback wiring: https://docs.ideal-postcodes.co.uk/docs/address-finder/configure.md
```

For multi-turn projects, add a one-liner to `replit.md` (the file Agent reads on every turn) so it stays on the SDK:

```
Address autocomplete: @ideal-postcodes/address-finder, docs at

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

## 4. Lock down the key[​](#4-lock-down-the-key "Direct link to 4. Lock down the key")

The widget runs in the browser, so the key is visible to site visitors — [Allowed URLs](/docs/guides/allowed-urls.md) is what makes it unusable elsewhere. Add **both** of these to your key:

* `*.replit.dev` — the workspace preview pane (rotates per project; without this the widget will 403 during development)
* `*.replit.app` — Replit Autoscale and Reserved VM deployments

Plus any custom domain you point at your deployed app.

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

* **403 `allowed_url_mismatch` in the workspace preview** — add `*.replit.dev` to Allowed URLs.
* **Suggestions never appear and the network tab shows no calls** — the key isn't reaching the browser. In a Vite app, rename the Secret to `VITE_IDEAL_POSTCODES_API_KEY` and reference it via `import.meta.env.VITE_IDEAL_POSTCODES_API_KEY`.
* **Server errors land in the Console pane, browser errors in the Preview's DevTools** — if Agent is "fixing" the wrong layer, check the other pane and paste the real error back into chat.

## 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>