fivem-nui-react 1.0.0

package/README.md

@@ -0,0 +1,268 @@
+# fivem-nui-react
+
+React hooks and utilities for FiveM NUI development.
+
+## Installation
+
+```bash
+npm install fivem-nui-react
+```
+
+## Features
+
+- **useNuiEvent** - Listen for NUI messages from Lua
+- **fetchNui** - Send requests to Lua client and receive responses
+- **useNuiCallback** - Hook for NUI requests with loading/error states
+- **isEnvBrowser** - Check if running in browser (debug mode)
+- **Mock data support** - Test your UI in browser with simulated responses
+
+## API Reference
+
+### useNuiEvent
+
+Listen for NUI messages sent from Lua.
+
+```tsx
+useNuiEvent<T>(action: string, handler: (data: T) => void, options?: UseNuiEventOptions<T>): void
+```
+
+**Parameters:**
+
+- `action` - The action name to listen for
+- `handler` - Callback function executed when message is received
+- `options` - Optional mock data configuration for browser testing
+
+**Example:**
+
+```tsx
+import { useNuiEvent } from "fivem-nui-react";
+
+function App() {
+  const [visible, setVisible] = useState(false);
+
+  useNuiEvent<{ show: boolean }>("toggleUI", (data) => {
+    setVisible(data.show);
+  });
+
+  // With mock data for browser testing
+  useNuiEvent<{ show: boolean }>("toggleUI", (data) => setVisible(data.show), {
+    mockData: { show: true },
+    mockDelay: 1000,
+  });
+
+  return visible ? <div>UI Content</div> : null;
+}
+```
+
+**Fivem client side:**
+
+```lua
+SendNUIMessage({
+  action = "toggleUI",
+  data = { show = true }
+})
+```
+
+---
+
+### fetchNui
+
+Send a request to the Fivem client and receive a response.
+
+```tsx
+fetchNui<T, D>(eventName: string, data?: D, options?: FetchNuiOptions<T>): Promise<T>
+```
+
+**Parameters:**
+
+- `eventName` - The NUI callback event name
+- `data` - Data to send to Lua
+- `options` - Optional mock data configuration for browser testing
+
+**Example:**
+
+```tsx
+import { fetchNui } from "fivem-nui-react";
+
+interface PlayerData {
+  name: string;
+  level: number;
+}
+
+async function getPlayer() {
+  const player = await fetchNui<PlayerData>("getPlayerData", { id: 1 });
+  console.log(player.name, player.level);
+}
+
+// With mock data for browser testing
+async function getPlayerMocked() {
+  const player = await fetchNui<PlayerData>(
+    "getPlayerData",
+    { id: 1 },
+    {
+      mockData: { name: "John", level: 10 },
+      mockDelay: 500,
+    },
+  );
+  console.log(player.name, player.level);
+}
+```
+
+**Lua side:**
+
+```lua
+RegisterNUICallback("getPlayerData", function(data, cb)
+  local playerId = data.id
+  -- Fetch player data...
+  cb({ name = "John", level = 10 })
+end)
+```
+
+---
+
+### useNuiCallback
+
+A hook that wraps `fetchNui` with loading and error state management.
+
+```tsx
+useNuiCallback<T, D>(
+  eventName: string,
+  callback: (data: T) => void,
+  options?: UseNuiCallbackOptions<T>
+): [fetchFn: (data?: D) => Promise<T>, state: { loading: boolean, error: Error | null }]
+```
+
+**Parameters:**
+
+- `eventName` - The NUI callback event name
+- `callback` - Callback function executed when response is received
+- `options` - Optional mock data configuration for browser testing
+
+**Returns:**
+
+- `fetchFn` - Function to trigger the request
+- `state.loading` - Boolean indicating if request is in progress
+- `state.error` - Error object if request failed
+
+**Example:**
+
+```tsx
+import { useNuiCallback } from "fivem-nui-react";
+
+interface PlayerData {
+  name: string;
+  level: number;
+}
+
+function PlayerInfo() {
+  const [player, setPlayer] = useState<PlayerData | null>(null);
+
+  const [fetchPlayer, { loading, error }] = useNuiCallback<PlayerData>(
+    "getPlayerData",
+    (data) => setPlayer(data),
+    {
+      mockData: { name: "John", level: 10 },
+      mockDelay: 500,
+    },
+  );
+
+  useEffect(() => {
+    fetchPlayer({ id: 1 });
+  }, [fetchPlayer]);
+
+  if (loading) return <div>Loading...</div>;
+  if (error) return <div>Error: {error.message}</div>;
+  if (!player) return null;
+
+  return (
+    <div>
+      <p>Name: {player.name}</p>
+      <p>Level: {player.level}</p>
+    </div>
+  );
+}
+```
+
+---
+
+### isEnvBrowser
+
+Check if running in browser (outside FiveM).
+
+```tsx
+isEnvBrowser(): boolean
+```
+
+**Example:**
+
+```tsx
+import { isEnvBrowser } from "fivem-nui-react";
+
+if (isEnvBrowser()) {
+  console.log("Running in browser - debug mode");
+} else {
+  console.log("Running in FiveM");
+}
+```
+
+---
+
+## Browser Testing (Mock Data)
+
+All hooks and functions support mock data for testing your UI in a regular browser without FiveM.
+
+When `isEnvBrowser()` returns `true`:
+
+- `useNuiEvent` will trigger the handler with `mockData` after `mockDelay` milliseconds
+- `fetchNui` will return `mockData` after `mockDelay` milliseconds
+- `useNuiCallback` will call the callback with `mockData` after `mockDelay` milliseconds
+
+**Options:**
+
+- `mockData` - The data to return in browser mode
+- `mockDelay` - Delay in milliseconds before returning data (default: 500ms)
+
+---
+
+## TypeScript Support
+
+All functions are fully typed with generics:
+
+```tsx
+// Define your types
+interface ShowUIData {
+  visible: boolean;
+  title: string;
+}
+
+interface PlayerRequest {
+  id: number;
+}
+
+interface PlayerResponse {
+  name: string;
+  level: number;
+}
+
+// Use with type parameters
+useNuiEvent<ShowUIData>("showUI", (data) => {
+  // data is typed as ShowUIData
+  console.log(data.visible, data.title);
+});
+
+const player = await fetchNui<PlayerResponse, PlayerRequest>("getPlayer", {
+  id: 1,
+});
+// player is typed as PlayerResponse
+
+const [fetchPlayer, { loading }] = useNuiCallback<
+  PlayerResponse,
+  PlayerRequest
+>("getPlayer", (data) => console.log(data.name));
+```
+
+---
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,74 @@
+interface NuiMessageEvent<T = unknown> {
+    action: string;
+    data: T;
+}
+type NuiEventHandler<T = unknown> = (data: T) => void;
+interface UseNuiEventOptions<T = unknown> {
+    mockData?: T;
+    mockDelay?: number;
+}
+interface FetchNuiOptions<T = unknown> {
+    mockData?: T;
+    mockDelay?: number;
+}
+/**
+ * Checks if running in browser debug mode
+ */
+declare function isEnvBrowser(): boolean;
+/**
+ * React hook for listening to NUI messages from Lua
+ * @param action - The action name to listen for
+ * @param handler - Callback function to execute when message is received
+ * @param options - Options for mock data in browser mode
+ * @example
+ * useNuiEvent("showUI", (data) => {
+ *   setVisible(data.visible);
+ * }, { mockData: { visible: true }, mockDelay: 1000 });
+ */
+declare function useNuiEvent<T = unknown>(action: string, handler: NuiEventHandler<T>, options?: UseNuiEventOptions<T>): void;
+/**
+ * Sends a request to NUI callback (fivem client)
+ * @param eventName - The callback event name
+ * @param data - Data to send
+ * @param options - Options for mock data in browser mode
+ * @returns Promise<T> - Response from fivem client
+ * @example
+ * const result = await fetchNui("getPlayerData", { id: 1 }, {
+ *   mockData: { name: "John", level: 10 },
+ *   mockDelay: 500
+ * });
+ */
+declare function fetchNui<T = unknown, D = unknown>(eventName: string, data?: D, options?: FetchNuiOptions<T>): Promise<T>;
+interface UseNuiCallbackOptions<T = unknown> {
+    mockData?: T;
+    mockDelay?: number;
+}
+interface UseNuiCallbackState {
+    loading: boolean;
+    error: Error | null;
+}
+type UseNuiCallbackReturn<T, D> = [
+    (data?: D) => Promise<T>,
+    UseNuiCallbackState
+];
+/**
+ * React hook for making NUI callback requests with loading and error states
+ * @param eventName - The callback event name
+ * @param callback - Callback function to execute when response is received
+ * @param options - Options for mock data in browser mode
+ * @returns [fetchFunction, { loading, error }]
+ * @example
+ * const [fetchPlayer, { loading, error }] = useNuiCallback<PlayerData>("getPlayer", (data) => {
+ *   setPlayer(data);
+ * }, {
+ *   mockData: { name: "John", level: 10 },
+ *   mockDelay: 500
+ * });
+ *
+ * useEffect(() => {
+ *   fetchPlayer({ id: 1 });
+ * }, [fetchPlayer]);
+ */
+declare function useNuiCallback<T = unknown, D = unknown>(eventName: string, callback: (data: T) => void, options?: UseNuiCallbackOptions<T>): UseNuiCallbackReturn<T, D>;
+
+export { type FetchNuiOptions, type NuiEventHandler, type NuiMessageEvent, type UseNuiCallbackOptions, type UseNuiCallbackReturn, type UseNuiCallbackState, type UseNuiEventOptions, fetchNui, isEnvBrowser, useNuiCallback, useNuiEvent };

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+interface NuiMessageEvent<T = unknown> {
+    action: string;
+    data: T;
+}
+type NuiEventHandler<T = unknown> = (data: T) => void;
+interface UseNuiEventOptions<T = unknown> {
+    mockData?: T;
+    mockDelay?: number;
+}
+interface FetchNuiOptions<T = unknown> {
+    mockData?: T;
+    mockDelay?: number;
+}
+/**
+ * Checks if running in browser debug mode
+ */
+declare function isEnvBrowser(): boolean;
+/**
+ * React hook for listening to NUI messages from Lua
+ * @param action - The action name to listen for
+ * @param handler - Callback function to execute when message is received
+ * @param options - Options for mock data in browser mode
+ * @example
+ * useNuiEvent("showUI", (data) => {
+ *   setVisible(data.visible);
+ * }, { mockData: { visible: true }, mockDelay: 1000 });
+ */
+declare function useNuiEvent<T = unknown>(action: string, handler: NuiEventHandler<T>, options?: UseNuiEventOptions<T>): void;
+/**
+ * Sends a request to NUI callback (fivem client)
+ * @param eventName - The callback event name
+ * @param data - Data to send
+ * @param options - Options for mock data in browser mode
+ * @returns Promise<T> - Response from fivem client
+ * @example
+ * const result = await fetchNui("getPlayerData", { id: 1 }, {
+ *   mockData: { name: "John", level: 10 },
+ *   mockDelay: 500
+ * });
+ */
+declare function fetchNui<T = unknown, D = unknown>(eventName: string, data?: D, options?: FetchNuiOptions<T>): Promise<T>;
+interface UseNuiCallbackOptions<T = unknown> {
+    mockData?: T;
+    mockDelay?: number;
+}
+interface UseNuiCallbackState {
+    loading: boolean;
+    error: Error | null;
+}
+type UseNuiCallbackReturn<T, D> = [
+    (data?: D) => Promise<T>,
+    UseNuiCallbackState
+];
+/**
+ * React hook for making NUI callback requests with loading and error states
+ * @param eventName - The callback event name
+ * @param callback - Callback function to execute when response is received
+ * @param options - Options for mock data in browser mode
+ * @returns [fetchFunction, { loading, error }]
+ * @example
+ * const [fetchPlayer, { loading, error }] = useNuiCallback<PlayerData>("getPlayer", (data) => {
+ *   setPlayer(data);
+ * }, {
+ *   mockData: { name: "John", level: 10 },
+ *   mockDelay: 500
+ * });
+ *
+ * useEffect(() => {
+ *   fetchPlayer({ id: 1 });
+ * }, [fetchPlayer]);
+ */
+declare function useNuiCallback<T = unknown, D = unknown>(eventName: string, callback: (data: T) => void, options?: UseNuiCallbackOptions<T>): UseNuiCallbackReturn<T, D>;
+
+export { type FetchNuiOptions, type NuiEventHandler, type NuiMessageEvent, type UseNuiCallbackOptions, type UseNuiCallbackReturn, type UseNuiCallbackState, type UseNuiEventOptions, fetchNui, isEnvBrowser, useNuiCallback, useNuiEvent };

package/dist/index.js

@@ -0,0 +1,105 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  fetchNui: () => fetchNui,
+  isEnvBrowser: () => isEnvBrowser,
+  useNuiCallback: () => useNuiCallback,
+  useNuiEvent: () => useNuiEvent
+});
+module.exports = __toCommonJS(index_exports);
+var import_react = require("react");
+var resourceName = window.GetParentResourceName ? window.GetParentResourceName() : "nui-frame-app";
+function isEnvBrowser() {
+  return !window.invokeNative;
+}
+function useNuiEvent(action, handler, options) {
+  const savedHandler = (0, import_react.useRef)(handler);
+  (0, import_react.useEffect)(() => {
+    savedHandler.current = handler;
+  }, [handler]);
+  (0, import_react.useEffect)(() => {
+    if (isEnvBrowser()) {
+      if ((options == null ? void 0 : options.mockData) === void 0) return;
+      const delay = options.mockDelay ?? 500;
+      const timeout = setTimeout(
+        () => savedHandler.current(options.mockData),
+        delay
+      );
+      return () => clearTimeout(timeout);
+    }
+    const eventListener = (event) => {
+      const { action: eventAction, data } = event.data;
+      if (eventAction === action) savedHandler.current(data);
+    };
+    window.addEventListener("message", eventListener);
+    return () => window.removeEventListener("message", eventListener);
+  }, [action, options == null ? void 0 : options.mockData, options == null ? void 0 : options.mockDelay]);
+}
+async function fetchNui(eventName, data, options) {
+  if (isEnvBrowser()) {
+    if ((options == null ? void 0 : options.mockData) === void 0) return Promise.resolve(null);
+    const delay = options.mockDelay ?? 500;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    return options.mockData;
+  }
+  const response = await fetch(`https://${resourceName}/${eventName}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json; charset=UTF-8"
+    },
+    body: JSON.stringify(data ?? {})
+  });
+  return response.json();
+}
+function useNuiCallback(eventName, callback, options) {
+  const [state, setState] = (0, import_react.useState)({
+    loading: false,
+    error: null
+  });
+  const callbackRef = (0, import_react.useRef)(callback);
+  (0, import_react.useEffect)(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  const fetch2 = (0, import_react.useCallback)(
+    async (data) => {
+      setState({ loading: true, error: null });
+      try {
+        const result = await fetchNui(eventName, data, options);
+        callbackRef.current(result);
+        setState({ loading: false, error: null });
+        return result;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        setState({ loading: false, error });
+        throw error;
+      }
+    },
+    [eventName, options]
+  );
+  return [fetch2, state];
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  fetchNui,
+  isEnvBrowser,
+  useNuiCallback,
+  useNuiEvent
+});

package/dist/index.mjs

@@ -0,0 +1,78 @@
+// src/index.ts
+import { useCallback, useEffect, useRef, useState } from "react";
+var resourceName = window.GetParentResourceName ? window.GetParentResourceName() : "nui-frame-app";
+function isEnvBrowser() {
+  return !window.invokeNative;
+}
+function useNuiEvent(action, handler, options) {
+  const savedHandler = useRef(handler);
+  useEffect(() => {
+    savedHandler.current = handler;
+  }, [handler]);
+  useEffect(() => {
+    if (isEnvBrowser()) {
+      if ((options == null ? void 0 : options.mockData) === void 0) return;
+      const delay = options.mockDelay ?? 500;
+      const timeout = setTimeout(
+        () => savedHandler.current(options.mockData),
+        delay
+      );
+      return () => clearTimeout(timeout);
+    }
+    const eventListener = (event) => {
+      const { action: eventAction, data } = event.data;
+      if (eventAction === action) savedHandler.current(data);
+    };
+    window.addEventListener("message", eventListener);
+    return () => window.removeEventListener("message", eventListener);
+  }, [action, options == null ? void 0 : options.mockData, options == null ? void 0 : options.mockDelay]);
+}
+async function fetchNui(eventName, data, options) {
+  if (isEnvBrowser()) {
+    if ((options == null ? void 0 : options.mockData) === void 0) return Promise.resolve(null);
+    const delay = options.mockDelay ?? 500;
+    await new Promise((resolve) => setTimeout(resolve, delay));
+    return options.mockData;
+  }
+  const response = await fetch(`https://${resourceName}/${eventName}`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json; charset=UTF-8"
+    },
+    body: JSON.stringify(data ?? {})
+  });
+  return response.json();
+}
+function useNuiCallback(eventName, callback, options) {
+  const [state, setState] = useState({
+    loading: false,
+    error: null
+  });
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+  const fetch2 = useCallback(
+    async (data) => {
+      setState({ loading: true, error: null });
+      try {
+        const result = await fetchNui(eventName, data, options);
+        callbackRef.current(result);
+        setState({ loading: false, error: null });
+        return result;
+      } catch (err) {
+        const error = err instanceof Error ? err : new Error(String(err));
+        setState({ loading: false, error });
+        throw error;
+      }
+    },
+    [eventName, options]
+  );
+  return [fetch2, state];
+}
+export {
+  fetchNui,
+  isEnvBrowser,
+  useNuiCallback,
+  useNuiEvent
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "fivem-nui-react",
+  "version": "1.0.0",
+  "description": "React hooks and utilities for FiveM NUI development",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch"
+  },
+  "keywords": [
+    "fivem",
+    "nui",
+    "react",
+    "hooks",
+    "cfx"
+  ],
+  "author": "",
+  "license": "MIT",
+  "type": "commonjs",
+  "peerDependencies": {
+    "react": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.2.8",
+    "@types/react-dom": "^19.2.3",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  }
+}