fivem-react-ui-lib

FiveM React UI Library

A library for FiveM UI communication between Lua and React, with a powerful store system based on Zustand.

Installation

npm install fivem-react-ui-lib

Features

• NUI communication with FiveM using fetchNui
• Mock data system for development without FiveM
• Powerful state management using Zustand
• Real-time updates with NUI events
• Type-safe API

Store System

The library provides a powerful store system based on Zustand that makes it easy to communicate with FiveM and manage your UI state.

Basic Usage

import { createStore } from 'fivem-react-ui-lib';

// Define your data interface
interface Vehicle {
  id: number;
  plate: string;
  model: string;
  owner: string;
}

// Create a store
const useVehicleStore = createStore<Vehicle[], Vehicle>({
  name: 'vehicles',
  fetchEvent: 'getVehicles',
  createEvent: 'createVehicle',
  updateEvent: 'updateVehicle',
  deleteEvent: 'deleteVehicle',
  initialData: []
});

// In your component
function VehicleList() {
  const { data: vehicles, isLoading, fetch, create, update, delete: deleteVehicle } = useVehicleStore();
  
  useEffect(() => {
    fetch();
  }, [fetch]);
  
  // Use store methods for CRUD operations
  const handleAddVehicle = () => {
    create({ plate: 'ABC123', model: 'adder', owner: 'Player' });
  };
  
  return (
    <div>
      {isLoading ? <p>Loading...</p> : (
        <ul>
          {vehicles?.map(vehicle => (
            <li key={vehicle.id}>{vehicle.model} ({vehicle.plate})</li>
          ))}
        </ul>
      )}
      <button onClick={handleAddVehicle}>Add Vehicle</button>
    </div>
  );
}

Cached Stores

For better performance, you can use cached stores:

import { createCachedStore } from 'fivem-react-ui-lib';

const usePlayerStore = createCachedStore<Player[], Player>(
  {
    name: 'players',
    fetchEvent: 'getPlayers',
    initialData: []
  },
  {
    ttl: 60000, // Cache valid for 60 seconds
    invalidateOnMutation: true // Invalidate cache on create/update/delete
  }
);

Real-time Updates

Listen for NUI events to update your store in real-time:

import { useStoreEvents } from 'fivem-react-ui-lib';

function PlayerList() {
  const { data: players, fetch, setData } = usePlayerStore();
  
  // Initial data fetch
  useEffect(() => {
    fetch();
  }, [fetch]);
  
  // Set up real-time updates
  useStoreEvents({
    actions: {
      'playerJoined': (newPlayer) => {
        setData([...(players || []), newPlayer]);
      },
      'playerLeft': (data) => {
        setData(players?.filter(p => p.id !== data.id) || []);
      }
    }
  });
  
  // Rest of your component...
}

Development Mode

The library includes a development mode that works without FiveM, allowing you to develop your UI in any browser.

import { registerMockData, IsDevMode } from 'fivem-react-ui-lib';

// Set up mock data for development
if (IsDevMode()) {
  registerMockData({
    getVehicles: {
      request: {},
      response: [
        { id: 1, plate: 'ABC123', model: 'adder', owner: 'Player1' },
        { id: 2, plate: 'XYZ789', model: 'zentorno', owner: 'Player2' }
      ]
    }
  });
}

License

MIT