QwikPress - Vision & Manifeste

Date : 29/12/2024 Priorite : HAUTE - CETTE SEMAINE Projet : QwikPress - CMS/Générateur de sites modulaire basé sur Qwik

PHILOSOPHIE FONDAMENTALE

Le Constat : 25 ans de Web

PHP avait amené tout un process intelligent avec le rendu côté serveur. Les SPA (React, Angular) ont été une régression :

Obligent à avoir des devices puissants
Excluent les populations défavorisées
Envoient tout le code au frontend (sécurité compromise)
Hydratation massive = ressources gaspillées

Qwik est la révolution : il reprend le meilleur du serveur avec la modernité du frontend.

LES PILIERS DE QWIKPRESS

1. Sécurité par Architecture (pas par discipline)

Principe : Les credentials ne PEUVENT PAS fuiter vers le frontend.

┌─────────────────────────────────────────────┐
│  PLUGIN (seul accès aux credentials)        │
│  sharedMap.set('storage', service)          │
│  sharedMap.set('connector-xxx', fn)         │
└─────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────┐
│  server$ (accès via sharedMap UNIQUEMENT)   │
│  const storage = this.sharedMap.get(...)    │
└─────────────────────────────────────────────┘

Avantages :

L'IA (Claude) ne peut PAS faire d'erreur de sécurité
Un développeur ne peut PAS oublier et exposer des secrets
Le code est auditable : si process.env.SUPABASE_* est hors plugin = violation

2. Portabilité des Connecteurs

Un connecteur défini via sharedMap.set('connector-xxx', ...) peut être réutilisé dans tous les projets Qwik.

// Dans n'importe quel projet Qwik
const fb = this.sharedMap.get('connector-facebook');
const posts = await fb('/posts', { limit: 10 });

3. Accessibilité Universelle

Qwik = ~10kb de JS initial, 0 hydratation

Fonctionne sur des devices bas de gamme
Pas d'exclusion des populations défavorisées
Code envoyé uniquement quand nécessaire
Respect de la planète (moins de CPU/RAM client)

4. Sécurité du Rendu

Qwik assure : le code admin n'est jamais envoyé si l'utilisateur n'est pas admin.

Pas de prebundle, pas de code inutile côté client. Si tu n'as pas accès = le code n'existe pas pour toi.

ARCHITECTURE TECHNIQUE

Stack Validée

Composant	Rôle	Pourquoi
Qwik	Frontend + SSR	Resumability, 0 hydratation
Bun	Runtime	Rapidité, légèreté
Elysia	API (si besoin)	Performance, DX
Supabase	Cloud DB + Auth + Storage	PostgreSQL, tout-en-un
Redis	Cache	Performance, sessions
Nginx	Reverse Proxy	SSL, routing, cache

Pattern Error-First

// ❌ INTERDIT
try {
  const result = await something();
} catch (e) { /* ... */ }

// ✅ OBLIGATOIRE
const result = await something();
if (!result) {
  return { success: false, error: 'Message' };
}
// Code normal...

Pattern Plugin/SharedMap

// plugins/storage.ts - SEUL ENDROIT avec credentials
const client = createClient(process.env.SUPABASE_URL, ...);
sharedMap.set('storage', new SupabaseStorageService(client));

// server$ - JAMAIS de credentials
const storage = this.sharedMap.get('storage');
const pages = await storage.getAllPages();

OBJECTIFS DU PROJET

1. Prouver que Humain + IA = Rapidité Sécurisée

Avec les bons outils (Qwik + pattern sharedMap), une IA comme Claude peut :

Créer des connecteurs
Créer des pages et modules
Router les URLs
Sans risque de fuite de credentials

2. Rendre WordPress Obsolète

QwikPress offre :

Performance native (pas besoin de plugins cache)
Sécurité par design (pas de plugins vulnérables)
Flexibilité totale (modules Qwik custom)
Mode local ou cloud transparent

3. Stack pour la Planète

Low resource côté client
Cache intelligent (Redis + server$)
Scalable facilement
Accessible à tous les devices

VISION CONNECTEURS

Principe

Les connecteurs sont des fonctions injectées via sharedMap qui encapsulent :

Les credentials (jamais exposés)
La logique d'appel API
Le format de réponse

Usage

// Plugin (une seule fois)
sharedMap.set('connector-facebook', async (endpoint, params) => {
  return fetch(`${config.baseUrl}${endpoint}`, {
    headers: { Authorization: `Bearer ${token}` }
  });
});

// Partout dans le code
const fb = this.sharedMap.get('connector-facebook');
const posts = await fb('/posts', { limit: 10 });

Avantages

Réutilisable : Un connecteur marche dans tout projet Qwik
Sécurisé : Credentials isolés dans le plugin
Testable : Mock facile pour les tests
AI-Friendly : L'IA ne peut pas faire d'erreur

VISION STORAGE

Abstraction Locale/Cloud

interface StorageService {
  readonly mode: 'local' | 'supabase';
  getPage(id: string): Promise<Page | null>;
  getAllPages(): Promise<Page[]>;
  savePage(id: string, page: Page): Promise<StorageResult<Page>>;
  // ... toutes les opérations CRUD
}

Modes

Mode	Variable ENV	Description
Local	`STORAGE_MODE=local`	Fichiers JSON dans STORAGE/
Cloud	`STORAGE_MODE=supabase`	Supabase (DB + Storage)

Code Identique

// server$ - Le code ne change PAS selon le mode
const storage = this.sharedMap.get('storage');
const pages = await storage.getAllPages();
// Que ce soit local ou Supabase, même code

CONTENUS VIA server$

Pourquoi ?

Précache possible : Les données sont en mémoire serveur Qwik
Protection cloud : Évite de surcharger Supabase/APIs
Sécurité : Les APIs privées ne sont jamais exposées
Flexibilité : Switch local/cloud transparent

Pattern

// Toujours via server$, jamais direct
export const getPageContent = server$(async function(slug: string) {
  const storage = this.sharedMap.get('storage');
  return storage.getPageBySlug(slug);
});

RÈGLES DE DÉVELOPPEMENT

Obligatoire

AUCUN process.env.SUPABASE_* hors des plugins
AUCUN try/catch dans server$
Pattern error-first systématique
Types QRL<> pour les callbacks Qwik
Tester après chaque modification

Interdit

Supposer comment Qwik fonctionne (demander si pas sûr)
Modifier sans lire le code existant
Ignorer les corrections de l'expert
Mélanger plusieurs changements en même temps

PROPRIÉTÉS ÉMERGENTES

Si on fait bien les choses :

Développement ultra-rapide avec IA
Sécurité garantie par architecture
Performance native sans optimisation manuelle
Portabilité des connecteurs entre projets
Accessibilité universelle (devices bas de gamme)
Scalabilité facile (stateless + cache)
Maintenance simplifiée (code procédurier)

CITATIONS CLÉS

"Les credentials ne doivent JAMAIS être accessibles dans les composants ou server$."

"Un connecteur peut servir dans tout type de projet Qwik très facilement."

"Qwik assure que les fichiers que quelqu'un ne peut pas voir est possible, pas de prebundle."

"Cette stack est bonne pour la planète et l'accès à tous."

"On va prouver que humain et IA avec les bons outils vont très vite et de manière sécurisée."

FICHIERS CLÉS

Fichier	Rôle
`types/storage.ts`	Interface StorageService
`services/storage/file-storage.service.ts`	Implémentation locale
`services/storage/supabase-storage.service.ts`	Implémentation cloud
`plugins/storage.ts`	Injection sharedMap (SEUL accès credentials)
`CLAUDE.md`	Documentation pour l'IA

PROCHAINES ÉTAPES

[ ] Intégrer le plugin storage dans layout.tsx
[ ] Refactorer TOUS les server$ pour utiliser sharedMap.get('storage')
[ ] Supprimer l'ancien DataService (doublon)
[ ] Supprimer toutes les violations process.env.SUPABASE_*
[ ] Créer les connecteurs portables (Facebook, etc.)
[ ] Mode mixte local+cloud (backlog futur)

MÉDIAS - PRINCIPES CRITIQUES

Règle Fondamentale

On ne passe JAMAIS src: string pour une image. C'est TOUJOURS image: MediaRef avec les métadonnées.

// ❌ INTERDIT
interface HeroData { backgroundImage: string; }

// ✅ OBLIGATOIRE
interface HeroData { backgroundImage: MediaRef; }

Le MediaRef contient TOUJOURS : src, width, height, ratio, mimeType, alt.

Pourquoi ?

Performance : Pas de CLS (Cumulative Layout Shift)
SSR : Le HTML contient déjà les dimensions
Accessibilité : Les lecteurs d'écran ont l'info
Lazy loading : Le placeholder a la bonne taille

Pattern Média

// ❌ INTERDIT - Le front découvre la taille
<img src="/media/photo.jpg" />

// ✅ OBLIGATOIRE - Dimensions pré-fournies
<img
  src="/api/medias/abc123"
  width={metadata.dimensions.width}
  height={metadata.dimensions.height}
  alt={metadata.alt}
  style={{ aspectRatio: metadata.ratio }}
/>

Réponse API Média

// L'API retourne TOUJOURS les métadonnées
{
  url: "/api/medias/abc123",
  metadata: {
    dimensions: { width: 1920, height: 1080 },
    ratio: 1.777,
    ratioFormatted: "16:9",
    mimeType: "image/jpeg",
    dominantColor: "#2a3f5f" // Pour placeholder
  },
  urls: {
    thumbnail: "/api/medias/abc123?preset=thumbnail",
    medium: "/api/medias/abc123?w=640",
    large: "/api/medias/abc123?w=1024"
  },
  srcset: "...?w=320 320w, ...?w=640 640w, ...?w=1024 1024w"
}

Pattern URL pour Tailles

/api/medias/{id}                    → Original
/api/medias/{id}?w=800              → Largeur 800px
/api/medias/{id}?h=600              → Hauteur 600px
/api/medias/{id}?preset=thumbnail   → 150x150
/api/medias/{id}?preset=og          → 1200x630 (Open Graph)
/api/medias/{id}?w=800&format=webp  → WebP optimisé

Système Resize/Cache

Le développeur ajuste la taille via les helpers, le serveur resize + cache automatiquement.

import { getResizedUrl, getResizedDimensions, getResizedMediaRef } from '~/types/media';

// Générer l'URL redimensionnée
const thumbUrl = getResizedUrl(image, { preset: 'thumbnail' });
const mediumUrl = getResizedUrl(image, { width: 640, format: 'webp' });

// Connaître les dimensions finales (pour le HTML)
const dims = getResizedDimensions(image, { width: 800 });
// dims = { width: 800, height: 450 } (ratio préservé)

// Créer un nouveau MediaRef avec les nouvelles dimensions
const resized = getResizedMediaRef(image, { width: 800 });
// resized.width = 800, resized.height = 450, resized.src = "...?w=800"

Côté serveur :

Requête avec paramètres (?w=800&format=webp)
Vérification cache (Redis/disque)
Si pas en cache → resize + stocke
Retourne l'image optimisée

Ce document est la référence pour la présentation du projet au lancement.