Getting NUI asset paths right
Paths in your HTML are relative to the ui_page file. Every file must be listed in files (wildcards allowed). Reference other resources with https://cfx-nui-<resource>/<path>. Match file-name case exactly — Linux servers are case-sensitive. For bundlers, build with relative asset paths: Vite base: './', Create React App "homepage": ".", Next.js static export with its /_next/ URLs made relative.
Most “my UI is blank” and “my images are missing” reports are path problems. NUI serves files from your resource over a special URL, only the files you list are sent to players, and the server’s file system may be case-sensitive. Once the rules are clear, 404s disappear.
Relative to the page
ui_page 'web/dist/index.html'
files {
'web/dist/index.html',
'web/dist/assets/*',
'web/dist/images/*.webp',
'web/dist/fonts/*.woff2',
}Inside index.html, ./assets/app.js points to web/dist/assets/app.js. A leading slash (/assets/app.js) points to the root of the NUI origin instead and usually fails.
Bundler settings
| Tool | Setting |
|---|---|
| Vite | base: './' in vite.config |
| Create React App | "homepage": "." in package.json |
| Next.js (static export) | output: 'export', images.unoptimized: true, and relative asset URLs — a relative assetPrefix, or a post-build step that rewrites /_next/ to ./_next/ |
| Plain HTML | Relative paths everywhere |
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
export default defineConfig({
plugins: [react()],
base: './',
build: { outDir: 'dist', assetsDir: 'assets' },
});A full React/Vite setup is in React and Vite loading screens.
Files from other resources
Use https://cfx-nui-ox_inventory/web/images/water.png to show another resource’s image. That resource must list the file in its own files. The older nui://resource/path form is deprecated in favour of https://cfx-nui-.
Case sensitivity
Windows ignores letter case; Linux does not. An image referenced as img/Logo.png but saved as img/logo.png works on your Windows test server and breaks on a Linux host. Use lowercase file names everywhere.
Fonts and external files
- Ship fonts as
.woff2inside the resource for reliability, listed infiles. - External URLs (a CDN, Google Fonts) work too, but add a network dependency during loading.
- Large media (videos, music) is often better hosted on a CDN — see loading screen fonts and video backgrounds.
Finding the missing file
Open the NUI devtools, go to the Network tab and reload the UI: every red 404 shows the exact URL requested. Compare it with your files list and file names — see NUI devtools.
Common questions
Why are my NUI images not loading?
The file is not in files, the path is absolute instead of relative, or the case of the file name differs.
Why is my Vite/React NUI blank in game?
The build uses absolute /assets/ paths. Set base: './' and rebuild.
How do I use an image from another resource?
https://cfx-nui-<resource>/<path>, with the file listed in that resource’s files.
Can I use wildcards in files?
Yes, for example 'web/dist/assets/*'.
Want a loading screen you never have to debug?
Build it in the browser, export once, and edit it whenever — no HTML, no re-uploads.
Start free