The Debugging Den Documentation
Back
The Debugging Den Documentation  >  txAdmin  > Learn how to develop txAdmin

Learn how to develop txAdmin

This article covers how to download and run txAdmin from source and explains the basic project layout so you can jump into the parts you care about.

Note

This guide assumes you're familiar with Node.js and its ecosystem. Translations are not covered here.

Requirements

  • Windows (the builder does not work on other OSs)
  • Node.js v22.9 or newer
  • FXServer
  • Git
  • VSCode [or any other editor]
  • Bun

Project Structure

  • core: Node backend & modules. Transpiled by tsc then bundled via esbuild.
    • boot: Code used/triggered during the boot process.
    • deployer: Deploys new servers.
    • lib: Stateless utils, helpers, and business logic.
    • modules: Stateful classes that compose the txAdmin instance, providing interconnected features.
    • routes: Web routes and HTTP router logic.
    • testing: Top-level testing utilities.
  • resource: In-game resource running as monitor. Synced to the deploy path by dev:main.
  • menu: React source for the NUI Menu, built with Vite.
  • web: Legacy SSR templates & static assets for the web panel (EJS). Will be replaced by panel.
  • panel: New UI built with React + Vite.
  • scripts: Dev-only scripts.
  • shared: Cross-workspace utilities and types.

Preparing the environment

  1. Clone the txAdmin repository outside your FXServer directory:

    git clone https://github.com/tabarra/txAdmin

  2. Install dependencies & prepare the commit hook:

    # In the repo root
npm install
npm run prepare

  3. Create a .env at the repo root with TXDEV_FXSERVER_PATH pointing to your FXServer folder:

    TXDEV_FXSERVER_PATH='E:/FiveM/10309/'

Development Workflows

Core / Panel / Resource

Controlled by scripts/build/*, which:

  • Watches & copies static files to the deploy path.
  • Watches, re-transpiles core, bundles, and deploys.
  • Runs FXServer in the same terminal and restarts it on core changes (like nodemon, but fancier).

In dev mode, the core redirects panel/index.html to use Vite. Start Vite first, then the builder:

Small edit to make

# Head to scripts > build > dev.ts
# Comment out Line 14

# If it is not on line 14 look for
process.loadEnvFile();

Panel/Web browser

# Start Vite (panel)
cd panel
npm run dev

# In a new terminal make sure you are in the root folder [txAdmin], start the builder (core)
bun run --env-file=.env scripts/build/dev.ts

NUI Menu

cd nui

# Game dev mode
npm run dev

# Browser dev mode
npm run browser

For every change you must restart the monitor resource. Unless you started the server with +setr txAdmin-debugMode true, txAdmin will detect that as a crash and restart your server. When running in game mode, Vite can take 10–30s to finish before you can restart monitor in-game.

Resource event naming rules

  • Prefix must be tx<cl|sv>: to indicate where it is registered.
  • Server requests start with txsv:req.
  • Verbs are fine, e.g. txsv:checkAdminStatus, txcl:setServerCtx.
  • Most events are menu-related; extra scoping to “menu” isn’t required.

Testing & Building

Builds are typically produced by GitHub Actions. If you must build locally, output goes to dist/:

npm run test --workspaces
GITHUB_REF="refs/tags/v9.9.9" npm run build
FIXME: add linting & typechecking back into the workflow above.

Notes regarding the Settings system

  • config.json contains only changed, non-default values.
  • DEFAULT_NULL is only for values that cannot/should not have defaults (e.g. fxRunner.dataPath, discordBot.token). Note fxRunner.cfgPath does have a default.
  • All schemas must have a default (even if null).
  • schema.fixer fixes invalid values; it does not apply defaults for missing values.
  • schema.fixer runs during boot only, not on saves.
  • Use SYM_FIXER_FATAL sparingly—only for critical values where failing fast is preferred.
  • The schema ensures correct types (avoid TypeErrors); it does not validate dynamic/external concerns (e.g., file existence, or cross-schema conditions like “if bot enabled, token required”).
  • Validator transformers should only “polish” (e.g., de-dupe/sort), not fix invalid values.

Note regarding the Legacy UI

⚠ The /web/ UI is legacy and will be migrated to /panel/.

Do not modify css/coreui.css. Patch via custom.css or modify SCSS variables instead. The only change from CoreUI was the aside-menu width from 200px to 300px in scss/_variables.scss: $aside-menu-width. Other variables live under node_modules/@coreui/coreui/scss/coreui.

git clone https://github.com/coreui/coreui-free-bootstrap-admin-template.git coreui
cd coreui
npm i

# Optional: lock to the same CoreUI version
git checkout 0cb1d81a8471ff4b6eb80c41b45c61a8e2ab3ef6

# Compile:
npx node-sass --output-style expanded --source-map true --source-map-contents true --precision 6 src/scss/style.scss src/css/style.css

Then copy src/css/style.css into txAdmin's folder.

Helpful links