shiva-api

External standalone API server for the Shiva FiveM framework. Provides REST endpoints, real-time WebSocket broadcasting, and a bridge between shiva-core (FiveM) and external consumers like admin panels, Discord bots, and mobile apps.

Requirements

• Node.js 18+
• A running shiva-core instance (for bridge connection)

Getting Started

cp .env.example .env   # fill in your values
npm install
npm run dev

The server starts on http://localhost:3000 by default. The FiveM bridge will retry automatically until shiva-core is available.

Configuration

See .env.example for all options. Key variables:

| Variable | Default | Description | |---|---|---| | PORT | 3000 | HTTP server port | | FIVEM_WS_URL | ws://localhost:30120/shiva | FiveM bridge URL (internal only) | | API_SECRET | — | JWT signing secret | | DISCORD_CLIENT_ID | — | Discord OAuth2 app ID | | DISCORD_CLIENT_SECRET | — | Discord OAuth2 app secret | | BROADCAST_DRIVER | websocket | Broadcasting driver (websocket, reverb, pusher, socketio) |

Scripts

npm run dev        # start with file watching
npm start          # production start
npm test           # run Jest tests with coverage
npm run lint       # ESLint

Docker

docker compose up -d

Requires a fivem Docker network (docker network create fivem). See compose.yml for all options.

Architecture

┌──────────────┐     WebSocket      ┌──────────────┐     REST/WS     ┌──────────────┐
│  FiveM       │◄──────────────────►│  shiva-api   │◄──────────────►│  shiva-panel │
│  shiva-core  │   (internal only)   │  (this repo) │   (external)   │  Discord bot │
└──────────────┘                    └──────────────┘                └──────────────┘

The bridge WebSocket (FIVEM_WS_URL) is internal — never expose it to the internet. All game data flows through the bridge; this server never touches the database directly.

Related Repositories

| Repo | Purpose | |---|---| | shiva | FiveM Docker boilerplate | | shiva-fw | Shared Lua foundation | | shiva-core | FiveM framework engine | | shiva-modules | 71 default RP modules | | shiva-db | Database layer | | shiva-cli | Developer CLI | | shiva-boot | Boot utilities | | shiva-test | Testing framework | | shiva-docs | Documentation |