Skip to main content

Develop txAdmin from source

This guide explains the source-development workflow, project layout and the version-specific Bun workaround used in HSC's original notes.

Installing a compiled HSC theme does not require this workflow. The supplied monitor.zip is runtime output, not the editable source repository.

Version scope​

The development instructions bundled with the supplied txAdmin 8.1.1 package describe a Windows builder and Node.js 22.9 or newer. Upstream source can change independently of that package.

Before running commands, inspect the checked-out revision's package.json, workspace manifests and development documentation. Use the Node version, package manager and scripts declared there. A package manifest or lockfile is more reliable than assuming a command from an older guide still exists.

Use an isolated development FXServer installation. The builder copies files into its configured artifact directory and can launch or restart FXServer; never point it at your live installation by accident.

Requirements​

  • Windows for the builder documented with the supplied package.
  • Node.js 22.9 or newer, subject to the checked-out revision's engine requirements.
  • Git and an editor such as Visual Studio Code.
  • A separate FXServer installation and development profile.
  • Bun only if you deliberately use the optional workaround later in this guide.

Check the available tools:

node --version
npm --version
git --version

For the optional Bun workflow:

bun --version

Project layout​

DirectoryWhat it contains
coreBackend code and modules; built into runtime JavaScript
core/bootBoot-time behavior
core/deployerServer deployment functionality
core/libUtilities and shared backend logic
core/modulesStateful components of the txAdmin instance
core/routesHTTP routes and handlers
core/testingBackend testing helpers
resourceLua/server-client resource code deployed as monitor in the supplied package
panelReact/Vite browser interface
nuiMenu workspace used by the supplied development commands, where present
webLegacy web templates and assets in this generation of txAdmin
scriptsBuild and development automation
sharedTypes and helpers used across workspaces

The bundled development document labels the menu source menu in its structure list but uses cd nui in its commands. Check your checkout: use the folder containing the menu's actual package.json and scripts. Do not create a new folder just to match this guide.

1. Clone the source outside FXServer​

Example PowerShell commands:

Set-Location C:\Development
git clone https://github.com/citizenfx/txAdmin.git
Set-Location .\txAdmin

Use a working directory you control. Keep the source repository separate from the runtime system resource and from your txData directory.

Record the checkout:

git rev-parse HEAD
git status --short

For release-specific work, select the actual tag or commit associated with that release. Do not assume the current default branch matches your installed txAdmin version.

2. Install dependencies​

Read the repository's package manager declaration and lockfile first. For a checkout that uses npm:

npm install
npm run prepare

If the revision provides a compatible package-lock.json, npm ci is an alternative for installing the locked dependency tree. Do not mix package managers or replace lockfiles casually.

The prepare command must exist in the checkout. Review its script before running it, particularly if working from a third-party fork.

3. Configure the development artifact path​

Create .env in the repository root:

TXDEV_FXSERVER_PATH='E:/FiveM/DevelopmentServer/'

Replace the example with your separate development FXServer directory. Forward slashes avoid Windows backslash escaping issues.

Check that:

  1. The directory exists and contains the expected artifacts.
  2. The builder can write to it.
  3. It is not your production installation.
  4. The filename is exactly .env, not .env.txt.

Keep secrets out of commits. This example variable contains a local path, but other environment variables may contain sensitive values.

4. Start browser panel development​

The bundled development workflow starts the panel's Vite process before the backend builder.

In terminal A, from the repository root:

Set-Location .\panel
npm run dev

Leave this terminal open.

In terminal B, from the repository root:

Set-Location .\core
npm run dev

These commands apply when those scripts exist in the checkout. Read their actual definitions if the repository has changed.

The builder watches and deploys backend/resource files and can restart FXServer when core changes. The development backend serves the panel through its Vite integration. Open the address printed by the running tools rather than opening an HTML file directly.

Confirm the workflow​

  1. Confirm both processes remain running without startup errors.
  2. Open the development txAdmin instance.
  3. Make a small visible change to a panel source component.
  4. Confirm the browser updates.
  5. Revert the test change before beginning your real work.

Optional: HSC's Bun builder workaround​

The original HSC notes used Bun to start scripts/build/dev.ts while loading .env explicitly:

# Run from the repository root in a separate terminal
bun run --env-file=.env scripts/build/dev.ts

Use this only when that script exists and you understand how it differs from the checkout's normal development command.

The original notes also suggested commenting out process.loadEnvFile() in scripts/build/dev.ts. That is not a required setup step. Keep the normal call unless an actual runtime error shows it is incompatible with the chosen runtime.

If you encounter an environment-loading error:

  1. Check the Node/Bun version and the full error.
  2. Confirm .env exists at the expected working directory.
  3. Try the supported Node/npm workflow first.
  4. If deliberately using Bun, verify its environment-file behavior for your installed version.
  5. Make any workaround as a small local patch, document why it is necessary and review git diff.

Do not comment out code by line number: source lines move between revisions. Do not run two backend builders against the same artifacts simultaneously.

5. Develop the in-game menu​

Find the menu workspace and inspect its scripts. For the nui workspace documented in the supplied package:

Set-Location .\nui
npm run dev

For its browser preview mode:

Set-Location .\nui
npm run browser

Run one mode at a time unless the checkout explicitly supports otherwise. Browser preview is useful for layout work, but does not replace in-game testing of NUI messages, authentication and actions.

Resource restarts in development​

The bundled upstream instructions describe restarting monitor when required and warn that txAdmin can interpret that restart as a crash unless development debug mode is enabled.

For an isolated development launch, the documented argument is:

+setr txAdmin-debugMode true

Keep this behavior confined to development. Wait for the builder to report completion before restarting; the bundled guide mentions roughly 10–30 seconds for its in-game build workflow, but actual times vary.

Use a complete controlled process restart if you are unsure which layers need reloading. Do not use repeated restart monitor commands on a live server while experimenting.

6. Resource event conventions​

When editing txAdmin's internal resource code:

  • Use txcl: for client-side registration and txsv: for server-side registration.
  • Follow the existing txsv:req... convention for server requests.
  • Keep event names descriptive, such as txsv:checkAdminStatus and txcl:setServerCtx.
  • Follow existing scoping instead of adding redundant menu prefixes.

These are internal naming conventions, not a promise that private events are a stable public API. Prefer documented integration events for external resources and validate authorization on server-side actions.

7. Test the change​

For the workspace test command present in the supplied development instructions:

npm run test --workspaces

Run it from the repository root. Also run the lint/type-check commands actually provided by your checkout; this guide does not assume script names that may not exist.

Manually verify the affected behavior:

  • Panel login, navigation and relevant dialogs.
  • Browser console and network requests.
  • Dark/light appearance where supported.
  • In-game menu opening, navigation and relevant actions.
  • Regular-admin permissions as well as owner access.
  • Both interfaces after a complete restart.

Do not describe a successful compilation as proof that all gameplay behavior works.

8. Build release output​

The supplied documentation says release builds normally run through GitHub Actions and write local output under dist/.

Its example build expects a tag-shaped GITHUB_REF. In PowerShell, use an environment assignment appropriate to Windows:

# Example local build label; use the label expected by your checkout.
$env:GITHUB_REF = 'refs/tags/v9.9.9'
npm run build
Remove-Item Env:GITHUB_REF

v9.9.9 is only the upstream example value, not a real release claim. Inspect the build script and release workflow before choosing a build label. Do not ship output labeled as an official release when it is a custom build.

In a POSIX-compatible shell, the equivalent example is:

GITHUB_REF='refs/tags/v9.9.9' npm run build

That shell syntax does not make the Windows-only builder portable to another OS.

If a build fails, resolve the reported error rather than copying half-built output into a server. Verify the resulting directory structure and asset references before packaging.

9. Settings-system notes​

For the settings system described by the supplied documentation:

  • config.json stores changed, non-default values.
  • Use DEFAULT_NULL only where a normal default is inappropriate.
  • Give each schema a default, even when it is null.
  • A schema fixer repairs invalid values; it is not the mechanism for missing defaults.
  • Fixers run during boot in the documented implementation, not on every save.
  • Reserve SYM_FIXER_FATAL for critical failures.
  • Type schemas do not replace filesystem, network or cross-setting validation.
  • Transformers should normalize valid values, such as sorting or deduplicating them.

Confirm these internals against your revision before changing settings code.

10. Legacy UI notes​

In this generation, web/ contains legacy templates/assets and panel/ contains the React interface. Confirm which interface renders the screen you are changing.

For legacy CoreUI styling, prefer the project's custom CSS hooks or its existing SCSS workflow over editing generated css/coreui.css directly.

The pasted guide contained a historical CoreUI checkout and a node-sass rebuild command. Those instructions are not presented here as a current default: they are version-specific and unrelated to compiling the modern panel/NUI theme. Use the dependencies and workflow belonging to the exact legacy source revision if you need to rebuild it.

Troubleshooting​

ProblemWhat to check
.env values are missingWorking directory, filename, runtime version and builder environment-loading logic
Script or workspace does not existSelected revision and actual package.json scripts
Panel will not connectBoth Vite and backend builder must be running; inspect the printed URLs and errors
Changes do not appearConfirm you edited source for the visible interface and deployed into the development artifact path
Server restarts unexpectedlyBuilder behavior and resource crash detection during menu development
Build fails after switching versionsRuntime requirements, dependency lockfile and stale generated output
Menu preview works but gameplay failsTest actual NUI callbacks, identifiers and permissions in-game

Sources and scope​

Adapted from HSC's supplied notes and the development documentation included with its txAdmin 8.1.1 package. Commands are version-dependent and were not executed against a Windows development server during this conversion.