# Bolt

Bolt scaffolds full-stack JavaScript apps from a chat prompt — Vite + React + TypeScript by default, with optional Next.js, Astro and others. Address Finder runs in the browser, so the API key needs to reach the client bundle via a framework-prefixed `.env` variable. Bolt's separate **Secrets** panel (database icon → Secrets) is for server-only edge functions and will not reach the widget.

## 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. Add the key to `.env`[​](#2-add-the-key-to-env "Direct link to 2-add-the-key-to-env")

Pick the variable name your framework exposes to the browser:

* **Vite + React** (Bolt default): `VITE_IDEAL_POSTCODES_API_KEY`
* **Next.js**: `NEXT_PUBLIC_IDEAL_POSTCODES_API_KEY`
* **Astro**: `PUBLIC_IDEAL_POSTCODES_API_KEY`

Add it to `.env` in the file tree, or ask Bolt: *"Add `VITE_IDEAL_POSTCODES_API_KEY=ak_xxx` to .env."*

If you deploy through Netlify rather than Bolt Cloud, re-enter the variable in **Netlify → Site settings → Environment variables** — Bolt-side secrets do not always carry over when you claim the site.

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

Open Bolt with this prompt pre-filled:

[**Open in Bolt →**](https://bolt.new/?prompt=Add+UK+and+international+address+autocomplete+to+the+billing+form+using+%40ideal-postcodes%2Faddress-finder.+Install+the+npm+package+and+import+its+CSS.+In+a+useEffect%2C+call+AddressFinder.setup%28%29+against+the+address+line+1+input%2C+using+outputFields+to+populate+line+2%2C+city+and+postcode.+Read+the+API+key+from+import.meta.env.VITE_IDEAL_POSTCODES_API_KEY.+Reference+docs%3A+https%3A%2F%2Fdocs.ideal-postcodes.co.uk%2Fdocs%2Faddress-finder.md)

Or paste manually:

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

@ideal-postcodes/address-finder.



- Install the npm package and import its CSS.

- In a useEffect, call AddressFinder.setup() against the address line 1

  input. Use outputFields to populate line 2, city and postcode from the

  selected address.

- Read the API key from import.meta.env.VITE_IDEAL_POSTCODES_API_KEY

  (or process.env.NEXT_PUBLIC_IDEAL_POSTCODES_API_KEY for Next.js).

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

Name the package explicitly — Bolt will not pick `@ideal-postcodes/address-finder` from a vague prompt and will tend to scaffold a plain JSX field instead.

## 4. Allow the preview origin (avoid CORS)[​](#4-allow-the-preview-origin-avoid-cors "Direct link to 4. Allow the preview origin (avoid CORS)")

The widget calls our API from the browser. Without [Allowed URLs](/docs/guides/allowed-urls.md) the request fails with a CORS error in the preview console. Add every origin Bolt previews and deploys from:

* `localhost` — local sandbox
* `*.webcontainer.io`, `*.stackblitz.io` — in-browser preview
* `*.bolt.new` — shared Bolt preview links
* `*.netlify.app` (or your custom domain) — deployed site

This is also what stops your key being scraped from the public bundle and reused elsewhere — Allowed URLs is the defence, not key secrecy.

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