Starting a Frontend Project with LARS and CARS

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

1## 1. Make a workspace and enter it
2mkdir my-bsv-frontend && cd my-bsv-frontend
3
4# 2. Scaffold a React+TypeScript app (or your preferred framework)
5npm create vite@latest frontend -- --template react-ts
6cd frontend && npm install && cd ..
7
8# 3. Initialize a root package.json for dev-tool deps
9npm init -y

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

1import { defineConfig } from "vite";
2import react from "@vitejs/plugin-react";
3
4export default defineConfig({
5  plugins: [react()],
6  build: { outDir: "build" }
7});

Your directory should now look like:

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

2. Add a “start” script

Open frontend/package.json and add:

1{
2  // …
3  "scripts": {
4    "start": "vite",
5    // …
6  }
7}

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:

1{
2  "schema": "bsv-app",
3  "schemaVersion": "1.0",
4  "frontend": {
5    "language": "react",
6    "sourceDirectory": "./frontend"
7  },
8  "configs": [
9    {
10      "name": "Local LARS",
11      "provider": "LARS",
12      "network": "testnet",
13      "run": ["frontend"]
14    }
15  ]
16}

Local development with LARS

4. Install and launch LARS

1npm install --save-dev @p2ppsr/lars
2npx 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:

1cd frontend
2npm run dev       # Vite hot-reload
3# or
4npm 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:

1"configs": [
2  …,
3  {
4    "name": "Production",
5    "provider": "CARS",
6    "CARSCloudURL": "https://cars.babbage.systems",
7    "network": "mainnet",
8    "deploy": ["frontend"],
9    "frontendHostingMethod": "HTTPS"
10  }
11]

7. Install the CARS CLI

1npm install -g @p2ppsr/cars-cli

8. Register your project

1cars

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:

1Manage Projects → Billing: Top Up Balance

Send ~10000 sats from your Metanet client.

10. Build a deployable artifact

1cars 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:

1cars artifact ls

11. Release (“deploy”) to the cloud

Fast path:

1cars release now

Manual path:

1cars release get-upload-url
2cars 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:

1https://<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:

1cars project domain:frontend www.mysite.com
2cars project info     # to verify

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

Daily workflow

1# Dev
2cd frontend && npm run dev
3# or at project root
4npx lars start
5
6# Prod
7cars build
8cars release now
9
10# Other
11cars 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!