title: "Local Development" description: "Debug your Fireberry app with hot module replacement and instant feedback"

Local Development

Develop and debug your Fireberry components locally with instant feedback. The debug workflow lets you run components from your local development server, so changes appear in Fireberry without pushing on every edit.

The Debug Workflow

flowchart LR
    Dev[Local Dev Server] -->|Debug Mode| FB[Fireberry Platform]
    FB -->|Load Component| UI[Your Browser]
    UI -->|Hot Reload| Dev

    style Dev fill:#37C998
    style FB fill:#269DD9

Without debug mode:

1. Edit code
2. Build component
3. Push to Fireberry
4. Refresh browser
5. Repeat

With debug mode:

1. Edit code
2. Changes appear instantly (hot module replacement)

Quick Start

1. Start Your Dev Server

Navigate to your component and start Vite:

cd my-component
npm run dev

Vite starts on http://localhost:5173 by default.

2. Enable Debug Mode

In another terminal, from your app's root directory:

fireberry debug <component-id> localhost:5173

✔ Debug mode started!
  Component: abc-123-def-456
  URL: localhost:5173

3. Develop with Instant Feedback

• Edit src/App.jsx
• Changes appear instantly in Fireberry
• No build or push needed

4. Stop Debug Mode

When finished:

fireberry debug <component-id> --stop

The component reverts to the production build.

Finding Your Component ID

Component IDs are UUIDs in your manifest.yml:

components:
  - type: record
    title: my-record-component
    id: "abc-123-def-456" # Copy this
    path: my-record-component/dist

Complete Workflow Example

Initial Setup

# Create app with component
fireberry create my-app
cd my-app

# Push and install
fireberry push
fireberry install

Best Practices

Use Two Terminals

Keep your workflow clean:

• Terminal 1: Dev server (npm run dev)
• Terminal 2: CLI commands (fireberry debug, fireberry push)

Check Your Component ID

Before debugging, verify the ID:

cat manifest.yml | grep "id:"

Stop Debug Mode Before Pushing

Good practice:

# Stop debugging
fireberry debug <component-id> --stop

# Build production version
cd my-component
npm run build

# Push to Fireberry
cd ..
fireberry push

This ensures you're testing the production build before deployment.

Troubleshooting

Dev Server Not Starting

Debug Mode Errors

Changes Not Appearing

Testing Production Build

Before pushing, test the production build locally:

# Build
npm run build

# Preview build
npm run preview

Vite's preview server runs the production build locally so you can test before deploying.

Advanced: Debugging with TypeScript

If using TypeScript, Vite handles it automatically:

// src/App.tsx
import { useState } from "react";
import FireberryClientSDK from "@fireberry/sdk/client";

const App = () => {
  const [client] = useState(() => new FireberryClientSDK());

  // TypeScript type checking works in dev mode
  // Errors appear in terminal and browser

  return <div>My Component</div>;
};

export default App;

TypeScript errors appear in:

• Your editor
• Terminal where npm run dev runs
• Browser console

Quick Reference

What's Next?

Now that you've mastered local development:

• Component Types — Understand different component contexts
• SDK — Use the SDK to access Fireberry data
• Design System — Build UIs with Fireberry components
• CLI — Complete CLI command reference