Create and Deploy Your First Fireberry App

Ready to extend Fireberry with your own custom functionality? This guide takes you from zero to a running app in minutes.

What You'll Build

By the end of this guide, you'll have a working Fireberry app with a component that displays inside the Fireberry interface. Along the way, you'll learn:

• How Fireberry apps are structured
• How to use the CLI to create and deploy apps
• How to configure your app's manifest
• How to install and test your app

What is a Fireberry App?

A Fireberry app is a custom extension that runs inside the Fireberry platform. Here's the key architecture:

flowchart LR
    A[Your App Code] -->|Push| B[Fireberry Servers]
    B -->|Render in iframe| C[Fireberry UI]
    C -->|SDK Communication| D[Your Component]

Key concepts:

• Hosted on Fireberry — Your code is hosted on Fireberry's servers. No external hosting needed.
• Rendered in iframes — Your app runs inside an iframe within Fireberry's interface.
• Component-based — Each app has one or more components. Each component is a standalone single-page application.
• Three component types — Record, Side Menu, and Global Menu components serve different purposes.

📘

Note

Fireberry apps are client-side only. You write frontend code (HTML, CSS, JavaScript, React, etc.) that runs in the browser.

Prerequisites

Before you start, make sure you have:

• Node.js (v16 or later) and npm installed
• A Fireberry account with developer access
• Your API token from the Fireberry platform

Step 1: Install the CLI

The Fireberry CLI is your main tool for creating and managing apps.

npm install -g @fireberry/cli

Verify it's installed:

fireberry --version

📘

Resources

• npm package
• GitHub repository

Step 2: Authenticate

Store your API token so the CLI can communicate with Fireberry:

fireberry init

You'll be prompted to enter your token:

? Enter Fireberry token id ****************************
✔ Token saved successfully

💡

Tip

You can also pass the token directly: fireberry init YOUR_TOKEN_HERE

See Authentication for how to obtain your API token.

Step 3: Create Your App

Scaffold a new app with your first component:

fireberry create hello-world

The CLI will guide you through creating your first component interactively. You'll be prompted for:

• Component name
• Component type (record, side-menu, or global-menu)
• Type-specific settings (objectType for record components, etc.)

This creates a complete app structure with a ready-to-use React component:

hello-world/
├── manifest.yml              # App configuration
└── hello-world-component/
    ├── src/
    │   ├── App.jsx       # Your component code
    │   ├── main.jsx      # Entry point
    │   └── App.css       # Styles
    ├── dist/             # Build output
    ├── package.json      # Dependencies
    └── vite.config.js    # Vite configuration

📘

Note

The create command now uses Vite + React by default, giving you a modern development environment with hot module replacement (HMR) out of the box.

Step 4: Understand the Manifest

The manifest.yml file is the heart of your app. It defines what your app is and what components it contains.

app:
  id: "1f3a3eca-d551-4cd0-a1d7-4a1f2e431e26"
  name: "hello-world"
  description: ""

components:
  - type: record
    title: hello-world-component
    id: "864fbfb2-e7ca-4e9e-8532-9f02b1e7936f"
    path: hello-world-component/dist
    settings:
      iconName: "related-single"
      iconColor: "#7aae7f"
      objectType: 0
      height: "M"

App Properties

Component Properties

📘

Learn More

Each component type has different settings. See Component Types for details.

Step 5: Develop Your Component

Your component is scaffolded with Vite + React and includes the Fireberry SDK and Design System out of the box.

Local Development

Navigate to your component directory and start the dev server:

cd hello-world-component
npm run dev

Vite starts a development server with hot module replacement. Edit src/App.jsx to build your component.

The SDK is Pre-Installed

The Fireberry SDK is already included. Use it to communicate with Fireberry:

import FireberryClientSDK from "@fireberry/sdk/client";

const client = new FireberryClientSDK();
await client.initializeContext();

// Access current user
const { user } = client.context;
const { fullName } = user;
console.log(`Hello, ${fullName}!`);

// Query data from Fireberry
const results = await client.api.query(1, {
  fields: "accountid,accountname,status",
  query: 'status = "active"',
});

The Design System is Pre-Installed

The Fireberry Design System is already included:

import { DSThemeContextProvider, Button, Typography } from "@fireberry/ds";

function App() {
  return (
    <DSThemeContextProvider isRtl={false}>
      <Typography type="h1">My Fireberry App</Typography>
      <Button label="Click me" color="success" variant="primary" />
    </DSThemeContextProvider>
  );
}

Build for Production

When ready to deploy, build your component:

npm run build

This outputs to the dist/ directory (referenced in your manifest).

Step 6: Deploy to Fireberry

Once your app is ready, deploy it from your app's root directory:

cd hello-world
fireberry push

The CLI validates your manifest, packages your code, and uploads it:

✔ Manifest loaded successfully
✔ 1 component validated and zipped

Components ready to push:
  1. hello-world-component (864fbfb2...) - 45.23 KB

✔ Components pushed successfully

Step 7: Install on Your Account

After pushing, install the app to make it available:

fireberry install

App installed successfully

Your app is now live! 🎉

Step 8: See It in Action

Where your app appears depends on the component type:

Adding More Components

Your app can have multiple components. Add another component anytime:

fireberry create-component

You'll be prompted for:

• Component name — A unique identifier
• Component type — record, side-menu, or global-menu
• Type-specific settings — Object type, width, display name, etc.

The CLI scaffolds a new React project, installs dependencies, and updates your manifest.

✔ Successfully created component "analytics-panel"!
Component ID: abc-123
Type: global-menu
Path: analytics-panel/dist

Your component "analytics-panel" is ready!
   cd analytics-panel
   npm run dev    # Start development server
   npm run build  # Build for production

Each component lives in its own directory with its own dependencies and build process:

my-app/
├── manifest.yml
├── hello-world-component/
│   ├── src/
│   ├── dist/
│   └── package.json
└── analytics-panel/
    ├── src/
    ├── dist/
    └── package.json

After adding components, build and push:

cd analytics-panel
npm run build

cd ..
fireberry push

Quick Reference

Here's the complete workflow:

Adding more components:

What's Next?

Now that you have a running app, dive deeper:

• Local Development — Learn the debug workflow for faster development
• Component Types — Understand when to use each component type
• Developer Tools — Learn about the CLI, SDK, and Design System
• Install Your App — Learn about testing, updating, and removing apps