pebble-docs

Pebble Framework Documentation

Welcome to the official Pebble framework docs!

Pages

• Overview
• PebbleUI
• PebbleSRV

---

Table of Contents

• Pebble — Quick Overview
• The Concept of Pebblets
• How to Use a UI-Pebblet
• How to Use an SRV-Pebblet
• How a Pebblet is Built

---

The Concept of Pebble and Pebblet (UI-Pebblet & SRV-Pebblet) in Spacefix.xyz Limited

Pebble — Quick Overview

Pebble is a full-stack framework developed at Spacefix.xyz Limited. It consists of two independent but complementary frameworks: PebbleUI for the frontend and PebbleSRV for the backend.

Each framework is built, maintained, and consumed separately, allowing teams to use either one on its own. When used together, they form a twin-framework system designed to integrate seamlessly while remaining fully decoupled.

---

The Concept of Pebblets

UI-Pebblet & SRV-Pebblet

At Spacefix.xyz Limited, we use the concept of Pebblets: UI-Pebblets and SRV-Pebblets.

A UI-Pebblet (or SRV-Pebblet) is a usage blueprint tied to a specific MAJOR version of PebbleUI (or PebbleSRV). It defines how new applications are generated and structured using that version of the framework.

In practical terms, every MAJOR release of PebbleUI (or PebbleSRV) has a corresponding Pebblet. That Pebblet serves as the official blueprint for creating new apps based on that framework version.

Core Development Rules

1. Active Versions

At any point in time, there can only be two active MAJOR versions of PebbleUI (or PebbleSRV):

• Stable
• Latest

2. New Project Requirement

All new projects must be built using the Stable version.

This means every new project must use the Stable UI-Pebblet (or Stable SRV-Pebblet).

3. Pebble Shedding

During the last quarter of every two years, the Spacefix team performs a process called Pebble Shedding (or simply Shedding).

Shedding involves:

• Migrating all existing applications from Stable Pebblets to Latest Pebblets (if a Latest version already exists).
• If no Latest version exists, evaluating the feasibility of creating a new MAJOR version of PebbleUI (or PebbleSRV), along with its Pebblets, and then performing the migration within a practical timeframe.

4. Version Promotion

Once Shedding is complete:

• The Latest version becomes the new Stable version.
• The former Stable version of PebbleUI (or PebbleSRV), along with its Pebblets, is deprecated and removed.

5. Cycle Repetition

This cycle repeats.

---

How to Use a UI-Pebblet

General Guide

Each version of a UI-Pebblet (Stable or Latest) includes clear usage instructions in its README.md.

The steps below describe the general setup process:

Step 1: Download the UI-Pebblet Starter Project

From the GitHub repository, download the UI-Pebblet starter project corresponding to the version of PebbleUI you want to use (e.g., stable-ui-pebblet).

The starter project contains the required folder structure and startup files that guide how PebbleUI applications are built.

Step 2: Rename the Project

1. Rename the starter project folder to match your target app name.
2. Update the name field in package.json accordingly.

Step 3: Create and Configure the .env File

Create a .env file in the project root and provide values for the following environment variables:

VITE_APP_DEPLOYMENT_MODE=test
VITE_APP_SERVER_PORT=7777
VITE_APP_API_PROXY_PATH=/api/

# Backend NetBird IP (represents the API machine's localhost) + port + API prefix
VITE_APP_API_ROOT_URL=http://100.108.226.160:8888/api/

VITE_GOOGLE_MAPS_API_KEY=

VITE_PAYSTACK_TEST_PUBLIC_KEY=
VITE_PAYSTACK_LIVE_PUBLIC_KEY=

VITE_STREAM_API_KEY=

PEBBLE_UI_AUTH_TOKEN=

Notes:

• VITE_STREAM_API_KEY is only required if the app includes video functionality.
• PEBBLE_UI_AUTH_TOKEN is provided only by the Pebble framework maintenance team.
• Some values are app-specific and must be supplied by the App developer.

Step 4: Install Dependencies

npm i

Step 5: Install PebbleUI

If the installation above completes successfully:

1. Add to your project’s dependencies, the most recent release of the PebbleUI version (Stable or Latest) that you intend to use (e.g., “@spacefix/pebble-ui”: “^0.0.4”).
2. Install PebbleUI – npm run install:env

Step 6: Configure PebbleAppProvider

Configure PebbleAppProvider with the minimum required setup to verify that the app can build and run in development mode.

Step 7: Start the Development Server

npm run dev

If the app starts successfully, you’re all set 🎉

You can now continue building your application.

Note:

PebbleUI requires access to environment variables during installation in order to authenticate and download the privately published package. For this reason, we use the custom script “npm run install:env” instead of a standard install.

---

How to Use an SRV-Pebblet

General Guide

Each version of an SRV-Pebblet (Stable or Latest) includes clear usage instructions in its README.md.

The steps below describe the general setup process:

Step 1: Download the SRV-Pebblet Starter Project

From the GitHub repository, download the SRV-Pebblet starter project corresponding to the version of PebbleSRV you want to use (e.g., stable-srv-pebblet).

The starter project contains the required folder structure and startup files that guide how PebbleSRV applications are built.

Step 2: Rename the Project

1. Rename the starter project folder to match your target app name.
2. Update the name field in package.json accordingly.

Step 3: Create and Configure the .env File

Create a .env file in the project root and provide values for the following environment variables:

APP_DEPLOYMENT_MODE=test

# DB
DB_TEST_URI=''
DB_LIVE_URI=''

# Auth
AUTH_COOKIE_NAME='-id'
AUTH_COOKIE_SECRET=''
SESSION_PREFIX='healthsenta:'
SESSION_STORE_URI=redis://127.0.0.1:6379
SESSION_ID_ENCRYPTION_KEY=
PRODUCT_KEY_SECRET=

# Root User Credentials
ROOT_EMAIL=
ROOT_PASSWORD=
ROOT_WORK_EMAIL=

# APP UI
API_SERVER_PORT=8888
APP_UI_URL=http://localhost:5173
API_DOCS_SERVE_ROOT=/docs/healthsenta-service
API_DOCS_URL=http://localhost:8888/docs/healthsenta-service
PLATFORM_NAME=HealthSenta

# OTP
OTP_VERIFICATION_KEY_SECRET=
OTP_HASH_SECRET=

# EMAIL SMTP SETUP
SMTP_TRANSPORTER=''
HOST_USER_EMAIL=''

# Required if Zoho Transporter
ZOHO_APP_PASSWORD=

# Required if Google (Oauth2 SMTP) Transporter
CLIENT_ID=''
CLIENT_SECRET=''
OAUTH_PLAYGROUND=''
REFRESH_TOKEN=''

# Cloudinary
CLOUD_NAME=
CLOUDINARY_API_KEY=
CLOUDINARY_API_SECRET=

# Error Monitoring - Sentry
# This SENTRY_DSN value will be invalid if you put in in any string quotes
SENTRY_DSN=

# Payment Processor
PROCESSOR_CRYPTO_SECRET=

PAYSTACK_TEST_SECRET_KEY=
PAYSTACK_LIVE_SECRET_KEY=

FLUTTERWAVE_TEST_SECRET_KEY=
FLUTTERWAVE_LIVE_SECRET_KEY=

# Stream.io
STREAM_API_KEY=
STREAM_SECRET_KEY=

PEBBLE_SRV_AUTH_TOKEN=

Notes:

• STREAM_API keys are only required if the app includes video functionality.
• PEBBLE_SRV_AUTH_TOKEN is provided only by the Pebble framework maintenance team.
• Some values are app-specific and must be supplied by the App developer.

Step 4: Install Dependencies

npm i

Step 5: Install PebbleSRV

If the installation above completes successfully:

1. Add to your project’s dependencies, the most recent release of the PebbleSRV version (Stable or Latest) that you intend to use (e.g., “@spacefix/pebble-srv”: “^0.0.4”).
2. Install PebbleSRV – npm run install:env

Step 6: Configure PebbleServer

Configure PebbleServer with the minimum required setup to verify that the app can build and run in development mode.

Step 7: Start the Development Server

npm run start:dev

If the app starts successfully, you’re all set 🎉

You can now continue building your application.

Note:

PebbleSRV requires access to environment variables during installation in order to authenticate and download the privately published package. For this reason, we use the custom script “npm run install:env” instead of a standard install.

---

How a Pebblet is Built

For a Given PebbleUI (PebbleSRV) Major Version (Stable/Latest)

---

Last updated: February 2026
Maintained by: Spacefix.xyz Limited