1# Bienvenue
2
3Ce projet _sandbox_, à but non lucratif, recrée l'ambiance des salons de discussion de l'époque AOL/AIM ; il est accessible à l'adresse : https://pdraim.org.
4
5## Technologies utilisées
6
7- SvelteKit (version 5)
8- Node.js
9- TypeScript
10- Convex (base de données temps réel)
11- XP.css
12- Tailwind CSS
13
14## Prérequis
15
16- Node.js (>=22.13.0)
17- npm ou pnpm pour la gestion des packages
18
19## Installation
20
21Clonez le dépôt et installez les dépendances :
22
23```bash
24npm install
25# ou
26pnpm install
27```
28
29## Lancement du projet
30
31Lancez le projet en mode développement :
32
33```bash
34npm run dev
35# ou
36pnpm dev
37```
38
39Le site sera accessible via http://localhost:5173 par défaut.
40
41## Contribution
42
43Toute contribution visant à améliorer le réalisme et la qualité du projet est la bienvenue !
44Pour contribuer :
45
46- Forkez ce dépôt
47- Créez une branche pour vos modifications
48- Envoyez une pull request en décrivant clairement vos changements
49
50## Base de données
51
52Le projet utilise [Convex](https://convex.dev/) comme base de données temps réel. Convex gère automatiquement les mises à jour en temps réel des messages et de la liste des utilisateurs.
53
54### Configuration locale
55
561. Créez un compte sur [Convex](https://convex.dev/) et un nouveau projet
572. Copiez `.env.example` vers `.env.local` et remplissez les variables :
58   - `PUBLIC_CONVEX_URL` : URL de votre déploiement Convex
59   - `CONVEX_API_SECRET` : Clé secrète pour les appels serveur
60
61### Lancer Convex en développement
62
63Dans un terminal séparé, lancez le serveur Convex :
64
65```bash
66npx convex dev
67```
68
69Cela synchronise automatiquement vos fonctions backend avec Convex et affiche les logs en temps réel.
70
71### Dashboard Convex
72
73Vous pouvez visualiser et gérer vos données via le dashboard Convex :
74
75```bash
76npx convex dashboard
77```
78
79## Déploiement Cloudflare Pages
80
81Le projet est déployé sur [Cloudflare Pages](https://pages.cloudflare.com/). Les Workers Cloudflare ont des **limitations strictes** à respecter.
82
83### Opérations interdites au niveau global/module
84
85Cloudflare Workers **n'autorisent PAS** les opérations suivantes au niveau global (en dehors des handlers de requête) :
86
87```typescript
88// INTERDIT - provoque "Disallowed operation called within global scope"
89setInterval(() => { ... }, 1000);
90setTimeout(() => { ... }, 1000);
91fetch('https://api.example.com');
92crypto.getRandomValues(new Uint8Array(16));
93
94// AUTORISE - à l'intérieur d'un handler
95export const GET: RequestHandler = async () => {
96  const random = crypto.getRandomValues(new Uint8Array(16));
97  const response = await fetch('https://api.example.com');
98  // ...
99};
100```
101
102### Bonnes pratiques
103
104| A eviter                                              | Alternative                                            |
105| ----------------------------------------------------- | ------------------------------------------------------ |
106| `setInterval` pour cleanup                            | Lazy cleanup à chaque requête                          |
107| `fetch()` au chargement du module                     | `fetch()` dans les handlers                            |
108| Création de clients API au niveau module              | Création lazy ou dans les handlers                     |
109| `process.exit()`                                      | Retourner une Response avec status d'erreur            |
110| Bibliothèques avec worker threads (ex: `pino-pretty`) | Versions compatibles edge (ex: `pino` sans transports) |
111
112### Variables d'environnement
113
114- Utilisez `$env/dynamic/private` (runtime) au lieu de `$env/static/private` (build-time)
115- Les variables définies dans le dashboard Cloudflare ne sont disponibles qu'au runtime
116
117### Références
118
119- [Cloudflare Workers Runtime APIs](https://developers.cloudflare.com/workers/runtime-apis/)
120- [SvelteKit Cloudflare Adapter](https://svelte.dev/docs/kit/adapter-cloudflare)
121
122## Documentation et Ressources
123
124Si vous n'avez jamais utilisé Svelte/Kit ou Convex, référez-vous aux documentations officielles :
125
126- [Documentation de Svelte](https://svelte.dev/docs/)
127- [Documentation de SvelteKit](https://svelte.dev/docs/kit/@sveltejs-kit)
128- [Documentation de Convex](https://docs.convex.dev/)
129- [Convex + Svelte](https://docs.convex.dev/client/svelte)