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:

fireberry create hello-world

This creates a new directory with everything you need:

hello-world/
├── manifest.yml              # App configuration
└── static/
    └── comp/
        └── build/
            └── index.html    # Your component's entry point

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: my-first-component
    id: "864fbfb2-e7ca-4e9e-8532-9f02b1e7936f"
    path: static/comp/build
    settings:
      iconName: "related-single"
      iconColor: "#7aae7f"
      objectType: 0

App Properties

Component Properties

📘

Learn More

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

Step 5: Build Your Component

The default index.html is just a starting point. For real apps, you'll want to:

Use the SDK

The Fireberry SDK lets your app communicate with Fireberry — access user info, read and write data, and more.

npm install @fireberry/sdk

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"',
});

Use the Design System

The Fireberry Design System provides React components that match Fireberry's look and feel.

npm install @fireberry/ds

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>
  );
}

Step 6: Deploy to Fireberry

Once your app is ready, deploy it:

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. my-first-component (864fbfb2...) - 2.34 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:

Quick Reference

Here's the complete workflow:

What's Next?

Now that you have a running app, dive deeper:

• 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