shadcn-ts-boilerplate

A modern FiveM resource boilerplate using TypeScript, Svelte 5, and Tailwind CSS. Features a clean Controllers/Services architecture with NUI communication utilities ready to go.

Features

• TypeScript with strict type checking
• Svelte 5 for reactive NUI interfaces
• Tailwind CSS for styling
• Hot module replacement during development
• Optimized production builds with esbuild
• Built-in localization system (ox_lib)
• Clean Controllers/Services pattern
• Browser development mode for testing UI without FiveM

Requirements

• Node.js v18+ (LTS recommended)
• Package manager: bun (recommended), pnpm, npm, or yarn

Quick Start

# Install dependencies
bun install

# Build the resource
bun build

# Watch mode (auto-rebuild on changes)
bun watch

# Develop NUI in browser (hot reload on port 3000)
bun web:dev

Scripts

Project Structure

├── dist/                    # Compiled output (auto-generated)
│   ├── client.js
│   ├── server.js
│   └── web/
├── locales/                 # Translation files (ox_lib locale system)
│   └── en.json
├── scripts/                 # Build scripts
├── src/
│   ├── client/
│   │   ├── Controllers/     # Event handlers & command registration
│   │   ├── Services/        # Business logic & reusable functions
│   │   └── index.ts         # Client entry point
│   ├── server/
│   │   ├── Controllers/     # Event handlers & command registration
│   │   ├── Services/        # Business logic & database operations
│   │   └── index.ts         # Server entry point
│   ├── common/              # Shared code (client + server)
│   └── fxmanifest.lua       # Template for manifest generation
├── static/
│   └── config.json          # Runtime configuration
├── web/                     # NUI web interface (Svelte + Vite)
│   └── src/
│       ├── lib/
│       │   ├── nui/         # NUI communication utilities
│       │   └── utils.ts     # Utility functions
│       ├── App.svelte       # Root component
│       └── app.css          # Global styles
└── fxmanifest.lua           # Auto-generated manifest (do not edit)

Controllers vs Services Pattern

Controllers (src/[client|server]/Controllers/)

• Register events, commands, and NUI callbacks
• Thin orchestration layer
• Delegate business logic to services

Services (src/[client|server]/Services/)

• Stateless business logic
• Reusable across multiple controllers
• Game world interactions and data processing

NUI Communication

Client to NUI

// Client
SendNUIMessage({
  action: 'setVisible',
  data: true
});

<!-- NUI (Svelte) -->
<script lang="ts">
  import { useNuiEvent } from "$lib/nui";

  let visible = $state(false);

  useNuiEvent<boolean>("setVisible", (data) => {
    visible = data;
  });
</script>

NUI to Client

<!-- NUI (Svelte) -->
<script lang="ts">
  import { fetchNui } from "$lib/nui";

  async function handleAction() {
    const response = await fetchNui<{ success: boolean }>("doAction", { id: 1 });
  }
</script>

// Client
RegisterNuiCallback('doAction', (data: { id: number }, cb) => {
  // Handle the action
  cb({ success: true });
});

Adding UI Components

This boilerplate comes without pre-built UI components. To add shadcn-svelte components:

1. Install the CLI: bunx shadcn-svelte@latest init
2. Add components: bunx shadcn-svelte@latest add button

See shadcn-svelte documentation for more details.

Path Aliases

Configuration

Runtime Config (static/config.json)

import Config from '@common/config';

if (Config.debug) {
  console.log('Debug mode enabled');
}

Localization (locales/en.json)

import { Locale } from '@common/locale';

const message = Locale('welcome', playerName);

Dependencies

• @nativewrappers/fivem - Type-safe native wrappers
• @communityox/ox_lib - Utility library for FiveM
• Svelte 5 - NUI framework
• Tailwind CSS - Styling
• Biome - Linting and formatting

Documentation

See CLAUDE.md for comprehensive development documentation including:

• Detailed architecture overview
• NUI utilities reference
• Adding new features step-by-step
• Common patterns and best practices
• Troubleshooting guide