Local Development

This project is a Bun workspace with three apps. The root scripts run a task in each app. Each app has scripts in its package.json.

App	Path	URL
api	apps/api	http://localhost:8787
docs	apps/docs	http://localhost:3000/docs
web	apps/web	http://127.0.0.1:3002

Prerequisites

• Bun: The JavaScript runtime and package manager of the project
• Git
• A text editor, for example, VS Code
• A Cloudflare account, only for remote D1 access or deployment

Procedure

1. Clone the Repository

git clone https://github.com/simonbetton/ratesapi.nz.git
cd ratesapi.nz

2. Install the Dependencies

bun i

One install at the root of the repository installs the dependencies of all apps.

3. Start All Apps

bun run dev

This command starts the API, the docs, and the web apps together. The API uses a local D1 database on your computer. A Cloudflare account is not necessary.

Each time the API starts, it makes the tables that do not exist. Then it adds sample data: one provider for each category, with a snapshot on 2026-04-30. The sample data does not replace rows that you already have.

Run One App

To run the script of one app, use --filter with the name of the app:

bun run --filter docs dev

Get Rate Data

The sample data is small. To get the newest rates into your local D1 database, run the scraper scripts:

bun run --filter api scrape:local

The scripts collect the rates from interest.co.nz and save them in the local database. The data stays when you start the API again.

The scraper scripts are in apps/api/bin/:

• scrape-mortgage-rates.ts: Collects mortgage rates
• scrape-personal-loan-rates.ts: Collects personal loan rates
• scrape-car-loan-rates.ts: Collects car loan rates
• scrape-credit-card-rates.ts: Collects credit card rates

Each scrape adds a maximum of one snapshot for each day. The sample snapshot of 2026-04-30 also stays in the history.

Remote D1 Data

To use the remote D1 database, log in to Cloudflare. Then run this command:

bun run --filter api dev:remote

This command gives the full production data and the full history.

WARNING: The development environment in apps/api/wrangler.toml has the same database ID as production. As a result, dev:remote connects to the production database. The API endpoints only read data. Do not run scripts that write data with this connection.

Checks

Before you open a pull request, run all checks:

bun run check

This command runs Oxlint and Oxfmt, does a type check of each app, and runs the Bun tests.

To build each app in the same way as CI, run this command:

bun run build

Frequent Tasks

Task	Files
Add an endpoint	apps/api/src/routes/, apps/api/src/models/, and apps/api/test/api-contract.test.ts
Change the documentation	apps/docs/content/docs/
Change the scraper behavior	apps/api/bin/ and apps/api/src/models/
Change the deployment	apps/api/wrangler.toml, apps/docs/wrangler.toml, and .github/workflows/