Créer un site pour votre serveur FiveM

La plupart des communautés FiveM démarrent avec une invitation Discord et une page Tebex, et remettent le site à plus tard, jusqu'à ce que quelqu'un demande où se trouvent les règles. Ce guide est la version courte de la construction de ce site : configurer le modèle, le pointer vers votre serveur, écrire vos propres pages, publier. La première fois, cela prend environ une heure, et à aucun moment vous n'avez besoin d'écrire du React.

Les étapes ci-dessous utilisent RPWebsite, le modèle vendu par ce site. Lorsqu'une étape concerne plutôt FiveM que ce modèle, c'est indiqué comme tel, pour que le guide reste utile même si vous construisez votre site autrement.

Ce dont vous avez besoin avant de commencer

Quatre choses, et seules les deux premières sont vraiment obligatoires.

Node.js 20 ou plus récent, et pnpm. Le modèle est une application Next.js. node --version doit afficher v20 ou supérieur.
Un nom de domaine. Il n'a pas encore besoin de pointer quelque part, mais le site doit connaître sa propre adresse dès la compilation, donc décidez-le maintenant.
Votre code de connexion cfx.re, si vous voulez le nombre de joueurs en direct et un bouton de connexion fonctionnel. Ce sont les six caractères dans cfx.re/join/xxxxxx, que vous pouvez aussi lire depuis la console F8 en jeu.
Un endroit où publier. Vercel est la voie de moindre résistance et propose un plan gratuit suffisant pour un site communautaire. Tout ce qui exécute next start fonctionne aussi bien.

Vous n'avez besoin ni de base de données, ni de CMS, ni de système de connexion, ni de backend. Le site lit le statut de votre serveur depuis une API publique au moment de la requête, et tout le reste depuis des fichiers du dépôt.

L'installer et le lancer en local

Décompressez le modèle, puis depuis le dossier :

pnpm install
cp .env.example .env.local
pnpm dev

Ouvrez http://localhost:3000. Vous voyez un site complet avec du contenu d'exemple : page d'accueil, règles, FAQ, actualités et pages légales, en quatre langues.

Laissez pnpm dev tourner dans ce terminal pour le reste de ce guide. Il recharge à chaque modification, donc chaque changement ci-dessous est visible en une ou deux secondes.

Pointer le site vers votre serveur FiveM

Ouvrez .env.local, le fichier que vous venez de copier. Deux valeurs comptent maintenant.

NEXT_PUBLIC_SITE_URL=https://votre-domaine.example
NEXT_PUBLIC_CFX_JOIN_CODE=abc123

NEXT_PUBLIC_SITE_URL est l'adresse publique du site terminé. Chaque URL absolue en découle : le lien canonique, les balises hreflang, le sitemap, la carte de prévisualisation sociale. C'est la seule valeur sans laquelle pnpm build refuse de continuer, et c'est voulu. Un site qui dit à Google qu'il vit sur localhost est pire qu'un site qui ne compile pas du tout.

NEXT_PUBLIC_CFX_JOIN_CODE alimente à la fois la section de statut en direct et le bouton de connexion. Enregistrez le fichier, redémarrez pnpm dev pour qu'il prenne en compte les nouvelles variables, et la section de statut devrait afficher votre nombre réel de joueurs.

Si le compteur indique que votre serveur est hors ligne alors qu'il tourne manifestement, passez directement à la dernière section.

Définir l'identité de votre serveur

Ouvrez src/config/site.ts. C'est ici que le modèle se configure, sous la forme d'un simple objet TypeScript commenté sur chaque champ. Ceux à modifier dès le premier jour :

name est le nom de votre serveur, lu à la fois par l'onglet du navigateur, l'en-tête et la carte sociale.
platform vaut fivem ou ragemp. Il décide quel adaptateur de statut s'exécute et ce que fait le bouton de connexion.
theme vaut noir, crimson ou azure. Une valeur inconnue fait volontairement échouer la compilation, car une faute de frappe dans un panneau d'hébergement resterait sinon invisible jusqu'à ce que quelqu'un capture les mauvaises couleurs.
features contient les interrupteurs pour des pages entières. Désactivez ce que vous n'allez pas maintenir. Une page d'actualités vide est pire que pas de page d'actualités du tout.
legal contient les informations de votre opérateur. Gérer un site communautaire à titre commercial oblige généralement à les publier, et les laisser vides n'affiche strictement rien.

Écrire vos propres pages

Deux dossiers contiennent tout ce qu'un visiteur lit.

messages/fr.json contient le texte de l'interface : titres, libellés de boutons, introductions de section. Il y a un fichier par langue. Une clé qui existe dans une langue et pas dans une autre est une erreur de compilation plutôt qu'un repli silencieux, donc les quatre fichiers restent synchronisés par construction.

content/fr/ contient les pages longues au format Markdown : vos règles, votre FAQ, vos actualités, vos mentions légales et votre politique de confidentialité. Ajouter un fichier publie une page. Il n'y a aucune route à enregistrer ni aucune entrée de configuration à retenir, car l'emplacement d'une page dans la navigation est déclaré dans son propre frontmatter.

Commencez par content/fr/rules.mdx. C'est la page que les nouveaux joueurs lisent réellement, et le texte d'exemple qu'elle contient n'est pas votre règlement.

Publier

Avant de publier, lancez la vérification qu'exécute aussi la CI :

pnpm check

Cela compile, vérifie les types et exécute le linter, dans cet ordre, parce que next build génère les types de routes que TypeScript vérifie ensuite contre les pages. Si ça passe, le site est prêt à être publié.

Sur Vercel : importez le dépôt, renseignez dans les paramètres d'environnement du projet les mêmes variables que dans .env.local, puis publiez. Il n'y a aucune étape de build en dehors de next build et aucun service à provisionner.

Sur un VPS, Coolify, Docker ou Railway : tout ce qui exécute next start fonctionne à l'identique. Configurez les variables d'environnement dans le panneau de votre hébergeur plutôt que de versionner .env.local.

Une chose à savoir avant de la chercher : l'export statique n'est pas pris en charge tel quel. Un proxy s'exécute à chaque requête pour résoudre la langue du visiteur, et un export statique n'a pas de phase de requête. Le README du modèle documente la recette en quatre étapes pour devenir statique malgré tout, et ce que vous y perdez : la carte sociale générée, l'assistant de recherche RAGE:MP et l'optimisation des images.

Quand le compteur de joueurs indique hors ligne

C'est la question de support la plus fréquente, et elle a généralement l'une de ces trois causes.

Le code de connexion est erroné ou manquant. Comparez-le à cfx.re/join/xxxxxx de votre serveur. Le code est sensible à la casse.

Votre serveur refuse la requête. Le paramètre sv_requestParanoia de FiveM, à partir de 2, fait que les points de terminaison JSON intégrés refusent tout le monde, y compris votre propre site. La solution n'est pas de le baisser. Configurez plutôt la ressource de statut fournie dans integrations/fivem-status/ sur votre serveur, et pointez le site vers elle :

CUSTOM_STATUS_URL=http://votre-serveur:30120/fivem-status/?token=votre-secret

Ce chemin permet aussi d'obtenir le pic quotidien de joueurs, que l'API Cfx ne peut absolument pas fournir.

Vous essayez d'utiliser txAdmin. Il n'expose aucune API REST publique, et son unique point de terminaison protégé par variable d'environnement rapporte des métriques d'hôte derrière le port d'administration plutôt que des joueurs. La ressource ci-dessus est la voie prise en charge.

Si le nombre est correct en local mais faux en production, vérifiez que la variable d'environnement est bien définie dans le panneau de votre hébergeur. .env.local n'est pas publié, et c'est voulu.