# Starting a Frontend Project with LARS and CARS

Canonical: https://docs.projectbabbage.com/docs/quickstarts/lars-cars-frontend-project

Learn to create a frontend project with LARS, ship it to the cloud, and add your custom domain!

This guide walks you through:

1. Bootstrapping a clean React-BSV project
2. Spinning it up locally with **LARS** (Local Automated Runtime System)
3. Pushing it to production with **CARS** (Cloud Automated Runtime System)
4. Attaching a custom domain

> Although this example uses React/Vite, the same flow works for any static or SPA frontend (Vue, Svelte, plain HTML, etc.).

---

### Prerequisites

* **Node.js** 22 or 24 (maintained and patched)
* **Docker** (with Compose plugin)
* **Git** (optional, but recommended)
* A **BRC-100 wallet** such as BSV Desktop installed and running

---

### 1. Create your project skeleton

```bash
# 1. Make a workspace and enter it
mkdir my-bsv-frontend && cd my-bsv-frontend

# 2. Scaffold a React+TypeScript app (or your preferred framework)
npm create vite@latest frontend -- --template react-ts
cd frontend && npm install && cd ..

# 3. Initialize a root package.json for dev-tool deps
npm init -y
```

> **If you’re using Vite**, update `vite.config.ts` so the production build lands in `./build`:

```ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
  build: { outDir: "build" }
});
```

Your directory should now look like:

```
my-bsv-frontend/
├─ deployment-info.json       ← create next
├─ package.json               ← root (dev deps only)
└─ frontend/                  ← your React/Vite code
```

---

### 2. Add a “start” script

Open `frontend/package.json` and add:

```json
{
  // …
  "scripts": {
    "start": "vite",
    // …
  }
}
```

This lets LARS and you run `npm run start` in dev.

---

### 3. Define your deployment-info.json

Create `deployment-info.json` in the project root:

```json
{
  "schema": "bsv-app",
  "schemaVersion": "1.0",
  "frontend": {
    "language": "react",
    "sourceDirectory": "./frontend"
  },
  "configs": [
    {
      "name": "Local LARS",
      "provider": "LARS",
      "network": "testnet",
      "run": ["frontend"]
    }
  ]
}
```

---

## Local development with LARS

### 4. Install and launch LARS

```bash
npm install --save-dev @p2ppsr/lars
npx lars
```

#### LARS Main Menu

Once you run `npx lars`, you’ll see the following options to configure and launch your frontend:

- **Edit LARS Deployment Info**  
  Reads or updates your `Local LARS` entry in `deployment-info.json`.
- **Start LARS (local only)**  
  Runs `npm run start` in `frontend/`, opens your browser, and watches for changes.
- **Exit**  
  Quit the CLI

Under the hood, Start LARS will:

* Run `npm run start` in `frontend/`
* Open your browser to the app
* Hot-reload on code changes

You can also skip LARS and run directly:

```bash
cd frontend
npm run dev       # Vite hot-reload
# or
npm run build && npx serve build
```

---

### 5. (Optional) Add BSV micropayments or wallet features

Drop any pay-button or BRC-100 wallet code into `frontend/src/App.tsx`. LARS already speaks SPV and BRC-100 via `@bsv/sdk`.

---

## Production deployment with CARS

### 6. Append a Production config

Edit `deployment-info.json` and add:

```diff
"configs": [
  …,
  {
    "name": "Production",
    "provider": "CARS",
    "CARSCloudURL": "https://cars.babbage.systems",
    "network": "mainnet",
    "deploy": ["frontend"],
    "frontendHostingMethod": "HTTPS"
  }
]
```

---

### 7. Install the CARS CLI

```bash
npm install -g @p2ppsr/cars-cli
```

---

### 8. Register your project

```bash
cars
```

#### CARS Configurations Menu

* **Manage CARS configurations** → **Edit an existing CARS configuration**
* **Select** the `Production` config

Follow prompts to

  1. **Configuration name** (e.g. `my-bsv-frontend`)
  2. **CARS Cloud URL** Custom → Default (https://cars.babbage.systems)
  3. **Network** Default (mainnet)
  4. **What to release?** frontend
  5. **Frontend Hosting Method** HTTPS

Next, Select **Create a new project on this CARS Cloud** and name the project

---

### 9. Top up your hosting balance

In the CARS Main Menu:

```text
Manage Projects → Billing: Top Up Balance
```

Send \~`10000` sats from your Metanet client.

---

### 10. Build a deployable artifact

```bash
cars build        # or `cars build Production`
```

* Runs `npm install && npm run build` in `frontend/`
* Zips `frontend/build` + metadata into `my-bsv-frontend-<timestamp>.tgz`

Verify with:

```bash
cars artifact ls
```

---

### 11. Release (“deploy”) to the cloud

**Fast path:**

```bash
cars release now
```

**Manual path:**

```bash
cars release get-upload-url
cars release upload-files <uploadURL> ./my-bsv-frontend-*.tgz
```

Then check the **Releases** menu for logs and **View Project Info** in the Project menu for the new frontend URL:

```
https://<random>.projects.babbage.systems
```

---

### 12. Attach a custom domain

1. Point your DNS (`A` or `CNAME`) and add a `cars_project` TXT record
2. Run:

```bash
cars project domain:frontend www.mysite.com
cars project info     # to verify
```

TLS via Let’s Encrypt is provisioned automatically. DNS can take a few minutes.

---

## Daily workflow

```bash
# Dev
cd frontend && npm run dev
# or at project root
npx lars start

# Prod
cars build
cars release now

# Other
cars project resource-logs --resource frontend --since 1h --tail 200
```

---

## What you’ve achieved

* **Local dev**: full React+BSV app via LARS
* **Production**: one-click builds & deployments with CARS
* **No backend code** required—your app talks SPV/BRC-100 directly
* **Custom domain** + HTTPS out of the box

Happy building!