The phone operating system
for FiveM servers.

Overview

rde_phone is a FiveM smartphone resource built for one purpose: making it fast to give any other resource its own polished phone app, without that resource needing to know anything about NUI internals, iframes, or cross-resource plumbing.

Most FiveM phone frameworks solve this with Module Federation — a React app split across resources, sharing a runtime, loaded via a remoteEntry.js. It works, until it doesn't: shared React versions drift, federation chunks fail to resolve, and debugging a broken remote entry eats a night you didn't plan for. rde_phone doesn't use it at all.

Why this exists

The alternative most servers ship with couples every app's frontend to a shared bundler, a shared React tree, and a shared point of failure. One app's dependency bump can break every other app on the phone. rde_phone's iframe-per-app model means a broken app is a broken app — not a broken phone.

Design pillars

Quick Start

Installing rde_phone and getting the base OS running.

1. Dependencies & load order

rde_phone depends on ox_core, ox_lib, oxmysql, and ox_inventory. Any resource that registers an app should depend on rde_phone so it always starts first.

-- load order matters
ensure ox_core
ensure ox_lib
ensure oxmysql
ensure ox_inventory
ensure rde_phone
-- any app resource goes after rde_phone
ensure rde_banking

2. Register the phone item

The phone opens only if the player is holding the item — no item, no phone. Register it in ox_inventory's own item list:

['phone'] = {
    label = 'Phone',
    weight = 190,
    stack = false,
    close = true,
    client = {
        export = 'rde_phone.use_phone',
    },
},

3. Open it

F2 by default (Config.OpenKey), or use the item from the inventory. Both routes go through the same server-validated check — pressing the key with no phone in your inventory does nothing but show an error toast.

Architecture

Every request from every app — built-in or third-party — takes the same four-hop path.

The iframe boundary

Apps never call Lua directly — NUI only talks to the resource that served the current page. So the app calls the SDK, the SDK posts a message to the parent window (the phone shell), and the shell is the only thing that ever actually calls fetch() against a NUI endpoint.

Cross-resource apps

A third-party app doesn't have to live inside rde_phone's own files. Any resource can serve its own app and reference rde_phone's shared assets by their cross-resource NUI origin:

<link rel="stylesheet" href="https://cfx-nui-rde_phone/web/theme/rdui-phone.css" />
<script src="https://cfx-nui-rde_phone/web/vendor/lucide.js"></script>
<script src="https://cfx-nui-rde_phone/web/sdk/rde-phone-sdk.js"></script>

Your app's own backend calls don't go through RDEPhone.request() though — that only reaches rde_phone's own server callbacks. For your own data, fetch() your own resource's NUI endpoint directly. See Your First App for the full pattern.

SDK Reference

One script tag gives every app the full SDK surface:

<script src="../../sdk/rde-phone-sdk.js"></script>

Example: fetching and rendering data

await RDEPhone.ready;
const contacts = await RDEPhone.request('getContacts');
list.innerHTML = contacts.map(c => `<div>${c.name}</div>`).join('');

RDEPhone.on('sms:received', (msg) => {
    RDEPhone.notify({ title: 'New message', body: msg.body, icon: 'message-circle' });
});

Your First App

A complete, working app in under 40 lines. No build step, no bundler — this file runs as-is.

1. The Lua side

Register a server callback for your app's data, and register the app itself so it shows up on the homescreen.

lib.callback.register('my_app:cb:phoneGetGreeting', function(src)
    local player = Ox.GetPlayer(src)
    return { message = 'Hello, ' .. (player and player.name or 'stranger') }
end)

local function RegisterMyApp()
    pcall(function()
        exports.rde_phone:RegisterPhoneApp({
            slug  = 'my_app',
            title = 'My App',
            icon  = 'sparkles',      -- any Lucide icon name
            color = '#a855f7',       -- optional icon tint
            url   = ('https://cfx-nui-%s/web/phone/index.html'):format(GetCurrentResourceName()),
            order = 70,
        })
    end)
end

AddEventHandler('onResourceStart', function(name)
    if name ~= GetCurrentResourceName() then return end
    SetTimeout(500, RegisterMyApp)
end)
AddEventHandler('rde_phone:ready', RegisterMyApp) -- covers the other start order too

2. The client-side bridge

NUI can only reach the resource that served the page — you need one relay callback so your app can reach your own server callbacks.

RegisterNUICallback('phone:request', function(data, cb)
    CreateThread(function()
        local ok, result = pcall(function()
            return lib.callback.await('my_app:cb:phone' .. data.action, false, data.payload)
        end)
        cb(ok and result or { error = true })
    end)
end)

3. The app itself

<link rel="stylesheet" href="https://cfx-nui-rde_phone/web/theme/rdui-phone.css">
<script src="https://cfx-nui-rde_phone/web/sdk/rde-phone-sdk.js"></script>

<div id="greeting"></div>

<script>
const resourceName = GetParentResourceName();
async function myRequest(action, payload) {
  const r = await fetch(`https://${resourceName}/phone:request`, {
    method: 'POST', body: JSON.stringify({ action, payload }),
  });
  return r.json();
}

(async () => {
  const { message } = await myRequest('GetGreeting');
  document.getElementById('greeting').textContent = message;
})();
</script>

App Registry

The homescreen has no hardcoded app list — every icon on it, including the four built-in apps, came from a call to RegisterPhoneApp.

Ordering-race safety

If your resource starts before rde_phone, the export call would fail. Handle both directions:

AddEventHandler('onResourceStart', function(name)
    if name ~= GetCurrentResourceName() then return end
    SetTimeout(500, RegisterMyApp)   -- covers: rde_phone already running
end)
AddEventHandler('rde_phone:ready', RegisterMyApp) -- covers: rde_phone starts after you

Simplest fix: just declare rde_phone as a dependency in your fxmanifest.lua and FXServer guarantees the order — the event fallback is defense in depth for when someone restarts resources individually.

Removing an app

exports.rde_phone:UnregisterPhoneApp('my_app')

Localization

English is the default everywhere. Every string — Lua-side messages and NUI-side UI text — lives in exactly one place: Config.Locales in config.lua. Neither Lua nor the NUI keep a second copy.

Config.DefaultLanguage = 'en'
Config.Locales = {
    en = { greeting = 'Hello, %s' },
    de = { greeting = 'Hallo, %s' },
}

Lua side reads via Config.GetString(key, ...). NUI apps read the exact same table through the SDK:

await RDEPhone.ready;
title.textContent = RDEPhone.t('greeting', playerName);

Push Notifications

RDEPhone.notify() only works while your app's iframe is actually loaded. For events that happen while the player is on a different app — or has the phone closed entirely — use the generic server-side push API:

exports.rde_phone:PushNotification(targetSource, {
    title = 'Bank',
    body  = 'Wire received: $500',
    icon  = 'landmark',
    app   = 'banking',  -- ties the badge count to your homescreen icon
})

Gated server-side by phone possession — same check as every other phone action. If the target doesn't have a phone on them, it silently no-ops, exactly like a real phone not vibrating in a drawer.

Design System

Reusable classes from theme/rdui-phone.css. Link it once, get every component below for free.

Glass buttons

Semi-transparent, blurred, with a diagonal shine — reserved for primary actions. Tint is driven by CSS custom properties, so any color works without redefining the blur/shine/border treatment.

<div class="glyph rdui-glass" style="--glass-c1:20,255,20;--glass-c2:0,60,0;--glass-glow:0,255,0;"></div>

Buttons, toggles, badges

Icons

Lucide, self-hosted — web/vendor/lucide.js. After changing the DOM, call lucide.createIcons() again; it only converts <i data-lucide> tags present at call time.

Common Pitfalls

Real bugs found and fixed building the built-in apps and three production ports. Worth reading before you hit them yourself.

Built-in Apps

Case Studies

Three production resources ported from NPWD/Module Federation onto this SDK. Same architecture, three very different feature sets.

FAQ

Changelog