Documentation
Du zip à la mise en ligne
Tout ce qui suit part du principe que vous n'avez jamais touché à Astro. Si vous bloquez quelque part, écrivez à contact@alohapixel.com : une vraie personne répond.
Démarrer en 5 minutes
Il vous faut Node 22.18 ou plus récent, et pnpm (npm i -g pnpm). Ensuite, dans le dossier décompressé :
pnpm install
pnpm dev # http://localhost:4321
pnpm build # build de production dans dist/
pnpm preview # sert le build de production en local
pnpm check # vérifie tous les types
pnpm test # contrôles du thème
pnpm verify # banc de rendu sur le build (390, 768 et 1440 px)
pnpm lint:house # règles maison du code
pnpm dev:moteur # le site avec son back office, en local
pnpm build:moteur # le build du site avec back officeMoteur éteint, vos contenus vivent dans des fichiers en clair : l'identité du site dans src/config/siteData.json.ts, la navigation dans navData.json.ts, le reste juste à côté ou dans src/data/ selon le thème (articles de Reef et d'Aloha, produits de Kai, projets de Koa). Moteur allumé, tout ce que voient les visiteurs vit en base et se change dans le back office, sans toucher à un fichier. pnpm dev:moteur l'ouvre en local, à http://localhost:4321/_emdash/admin.
Deux façons de faire tourner votre site
Chaque thème se construit de deux façons, et une seule variable choisit : ALOHA_MOTEUR. Le design, les adresses et le référencement sont les mêmes dans les deux cas : on passe de l'un à l'autre sans réécrire une page.
Moteur éteint : le site statique
Le réglage d'origine. Le build ne produit que des fichiers HTML : rapide, sans serveur ni base, hébergé gratuitement où vous voulez (Cloudflare, Netlify, Vercel). Les contenus vivent dans des fichiers texte, et un changement passe par une modification puis un nouveau build. Le bon choix pour un site que vous tenez vous-même.
Moteur allumé : le site administrable
Avec ALOHA_MOTEUR=emdash, le même code devient un site sur Cloudflare, avec sa base de données et ses médias. Tout ce que voient les visiteurs se change dans le back office EmDash et se voit en ligne dès la publication, sans build. Le bon choix pour un site que votre client tient sans vous.
EmDash est un système de gestion de contenu libre (licence MIT), conçu pour Astro et pour Cloudflare. Les thèmes ne le réécrivent pas : ils s'y branchent, l'habillent aux couleurs et aux polices du thème, et le livrent en français, avec ce qu'EmDash ne fait pas seul : la barre d'édition sur chaque bloc, les courriels du site, la boutique de Kai, le bouton « Mettre le site à jour ».
Moteur allumé, il faut un compte Cloudflare avec Workers, D1 (la base) et R2 (les médias) ; Cloudflare Images est conseillé pour alléger les photos, et les courriels du site passent par Cloudflare Email Sending, qui demande l'offre Workers Paid. Le coût dépend de votre compte et des tarifs de Cloudflare.
Où se trouve quoi
src/
config/ vos contenus : identité, navigation, et selon le thème tarifs, FAQ, mentions
data/ la graine en fichiers, selon le thème : articles, produits, projets
components/
Sections/ les blocs de page que vous réagencez
ui/ les primitives d'interface (boutons, dialogues...)
pages/ un fichier par route
styles/ tokens.css = tout le design system
moteur/ le back office EmDash : réglages, menus, barre d'édition
docs/ administrer.md, le guide du back office pour votre client ; moteur.md, sa mise en ligne
migrations/ un fichier SQL par version, pour mettre à jour une base en ligne
scripts/ rebrand.mjs, og.mjs, moteur-import.mjs, base-3.4.0.mjs, deployer-frontal.sh
seed/ la graine du back office : collections, menus, contenus
wiki/ la documentation technique du thème
socle.lock.json la liste des fichiers communs aux sept thèmesRebrander en une commande
Donnez au thème la couleur de votre marque et toute la palette se régénère : les composants, le thème sombre, et même les images sociales générées suivent. Moteur allumé, votre client choisit aussi la couleur de la marque dans le back office, parmi cinq couleurs (« Réglages par langue »), sans commande.
pnpm rebrand "#7a59ff" # votre couleur d'accent
pnpm rebrand "#7a59ff" --dark "#140a2e"
pnpm rebrand --restore # retour à la palette Aloha d'origine
pnpm og # régénère les images OG assorties
pnpm favicon # régénère les favicons assortisPublier le site statique gratuitement
Moteur éteint, le build ne produit que des fichiers statiques : l'offre gratuite de n'importe quel hébergeur moderne le porte. Cloudflare : créez un projet, pointez-le sur votre dépôt, commande de build pnpm build, dossier de sortie dist. Netlify et Vercel : les deux mêmes valeurs. Renseignez site dans astro.config.mjs avec votre vrai domaine, pour que les URLs canoniques, le sitemap et les liens OG soient justes. Le site avec back office, lui, se publie sur Cloudflare : c'est la section suivante.
Mettre le back office en ligne
Une seule fois, depuis le dossier du thème, avec votre compte Cloudflare. Remplacez site.example.com par votre domaine : la base et le stockage des médias se créent au premier déploiement.
# 1. Installer, puis se connecter à Cloudflare
pnpm install
pnpm wrangler login
# 2. Construire le site avec son back office, puis le déployer
pnpm build:moteur
pnpm wrangler deploy
# 3. Le mettre sur votre domaine. D'abord, copiez l'identifiant de la base
# (pnpm wrangler d1 list) dans wrangler.frontal.jsonc
DOMAINE=site.example.com bash scripts/deployer-frontal.sh --a-sec # essai à blanc
DOMAINE=site.example.com bash scripts/deployer-frontal.sh
# 4. Ouvrir https://site.example.com/_emdash/admin et créer le premier
# administrateur (une clé d'accès, aucun mot de passe), en laissant
# cochée la case « Include sample content »
# 5. Créer un jeton d'API dans le back office (content:write et
# schema:write), puis verser le contenu du thème, une fois
EMDASH_TOKEN=... node scripts/moteur-import.mjs --url https://site.example.com
# 6. Vérifier : la version et l'heure du build réellement en ligne
curl -s https://site.example.com/version.jsonLes déploiements suivants passent par la même commande, DOMAINE=site.example.com bash scripts/deployer-frontal.sh, après pnpm build:moteur : elle s'arrête à la première étape qui échoue, et la version précédente reste en ligne. Sans Cloudflare Images sur le compte, construisez avec ALOHA_IMAGES=origine pnpm build:moteur et retirez la ligne "images" de wrangler.moteur.jsonc. Ensuite, un contenu publié depuis le back office est en ligne sans reconstruire le site. Le pas à pas complet, avec les noms propres au thème et le branchement du bouton « Mettre le site à jour », est dans son docs/moteur.md.
Vous préférez qu'on le mette en ligne pour vous ? L'installation clé en main se commande sur alohapixel.com.
Brancher la vente
Trois thèmes vendent, chacun à sa façon.
Kai : la boutique complète, avec votre compte Stripe
Moteur allumé, Kai encaisse par Stripe Checkout et gère commandes, stock, remboursements et factures dans le back office. Deux secrets à poser une fois, puis une adresse de webhook à déclarer chez Stripe, avec trois événements : checkout.session.completed, checkout.session.async_payment_succeeded et charge.refunded. L'écran « Brancher Stripe » du back office redonne les commandes exactes. Sans ces deux secrets, le panier reste celui de démonstration et personne ne peut payer.
Kona : la vitrine de votre boutique Shopify
Le catalogue, les prix, les taxes et le paiement restent chez Shopify. Une seule valeur : l'adresse de votre vitrine dans .env (SHOPIFY_STORE_URL). Aucune clé d'API, aucune application à installer : Kona lit le catalogue public de la boutique. pnpm shopify:check vérifie ce qu'elle répond avant tout build.
Nalu : la vitrine de votre boutique WooCommerce
Même principe : WOO_STORE_URL dans .env, aucune clé d'API, et l'extension WordPress wordpress/nalu-headless.php à installer sur votre WordPress, pour que le panier y soit accepté. pnpm woo:check vérifie la connexion.
# Kai : les deux secrets Stripe, une fois
pnpm wrangler secret put STRIPE_SECRET_KEY --config wrangler.moteur.jsonc
pnpm wrangler secret put STRIPE_WEBHOOK_SECRET --config wrangler.moteur.jsonc
# l'adresse du webhook à déclarer chez Stripe :
# https://site.example.com/_commerce/stripe/webhook
# Kona et Nalu : vérifier la boutique avant de construire
pnpm shopify:check
pnpm woo:checkLe thème pilote ces services, il ne les remplace pas : l'ouverture du compte, les frais, les délais de versement et de remboursement restent ceux de Stripe, de Shopify ou de WooCommerce.
Administrer votre site
Moteur allumé, tout ce que voient vos visiteurs se change depuis le back office EmDash, sans toucher à un fichier : textes, photos, vidéos, boutons et leurs adresses, blocs à masquer, menus, pied de page, logo, couleur de marque, pages ajoutées, référencement, redirections. La barre « Edit » modifie la page sous vos yeux. Selon le thème s'y ajoutent la lettre d'information de Reef, d'Aloha et de Swell (inscription confirmée par courriel, désinscription par une page de confirmation), les étiquettes des articles, l'auteur ou la rubrique choisis par leur nom, et pour Kai toute la boutique : produits, stock par option, commandes, remboursements et factures, avec votre propre compte Stripe. Le bandeau de cookies redemande un choix au bout de 182 jours. Chaque thème livre le guide pas à pas de votre client : docs/administrer.md (et docs/administer.md en anglais).
Piloter le site avec Claude
Moteur allumé, chaque thème embarque le serveur MCP d'EmDash : Claude, ou tout assistant compatible, lit et modifie les contenus du site, les publie, gère les médias et les menus, avec les droits du jeton que vous lui donnez.
Adresse du serveur : https://site.example.com/_emdash/api/mcp
En-tête : Authorization: Bearer <votre jeton>Créez le jeton dans le back office, avec les seules permissions dont l'assistant a besoin. Dans Claude, ajoutez un connecteur personnalisé : un nom (le domaine du site), l'adresse ci-dessus et l'en-tête Authorization. Vous écrivez ensuite « change le titre de la page d'accueil » ou « traduis la FAQ en anglais et publie-la », et l'assistant le fait dans le back office, en brouillon ou publié selon ce que vous demandez.
Le jeton est un secret : il ne se colle ni dans un document, ni dans une conversation.
En faire une application native
Les sept thèmes livrent une configuration Capacitor (capacitor.config.ts) et la commande pnpm app, qui construit le site statique pour l'application. L'application n'embarque que ce site statique : ni back office, ni caisse Stripe de Kai (elle vit sur le serveur), et la caisse Shopify ou WooCommerce de Kona et de Nalu s'ouvre hors de l'application. La scène vidéo d'Aloha utilise des médias distants : remplacez-les par des fichiers embarqués pour un usage hors ligne. La compilation native, la signature et la publication restent à votre charge.
pnpm app
pnpm add @capacitor/core @capacitor/ios @capacitor/android
pnpm add -D @capacitor/cli
# Personnalisez capacitor.config.ts avant la suite
npx cap add ios && npx cap open ios
npx cap add android && npx cap open androidAprès chaque changement de contenu : pnpm app && npx cap sync.
Travailler avec un agent IA
Ouvrez le dossier dans n'importe quel agent de code qui lit AGENTS.md, le mode d'emploi du dépôt. Il renvoie aux conventions du thème (Astro, Tailwind, TypeScript, animation, référencement), à sa doctrine de design et à sa documentation technique. Demandez une nouvelle section et l'agent la construit dans le design system au lieu d'inventer le sien.
Si quelque chose coince
Le build s'arrête sur une photo
Les thèmes qui ont des photos de démonstration les téléchargent au build, et s'arrêtent plutôt que de publier une image floue ou manquante. Vérifiez la connexion et relancez, ou remplacez la photo par la vôtre : le fichier PHOTOS.md du thème dit d'où vient chacune.
Kona affiche encore le catalogue de démonstration
SHOPIFY_STORE_URL est vide, ou la boutique est protégée par un mot de passe, ce qui est le réglage d'une boutique de développement : elle ne publie alors pas son catalogue (Boutique en ligne, Préférences, Protection par mot de passe). pnpm shopify:check dit lequel des deux.
Un changement fait dans Shopify ou WooCommerce ne se voit pas
Les produits, les prix et les rayons de Kona et de Nalu sont lus au build : cliquez « Mettre le site à jour » dans le back office. Seule la disponibilité est relue à chaque visite.
Personne ne peut payer sur Kai
Les deux secrets Stripe manquent, ou le webhook n'est pas déclaré chez Stripe avec ses trois événements : voir « Brancher la vente ». L'écran « Brancher Stripe » du back office dit ce qui manque.
Les courriels du site ne partent pas
Le domaine d'envoi n'est pas encore inscrit chez Cloudflare Email Sending. L'écran « Brancher les courriels » du back office dit ce qui manque, enregistrements DNS compris.
Choisir la langue du back office
Il s'ouvre en français par défaut. Construit avec ALOHA_BO_LANGUE=en pnpm build:moteur, il s'ouvre en anglais, et chaque éditeur peut toujours changer sa langue dans ses réglages. Quelques mots écrits par EmDash lui-même restent en anglais ; la barre d'édition du site, elle, suit la langue du back office (« Modifier », « Publier »).
Un déploiement a échoué
Le script s'arrête à la première étape qui échoue et laisse la version précédente en ligne : vos visiteurs ne voient jamais un site cassé. Corrigez ce que le message indique, puis relancez la même commande.
Mises à jour et support
Chaque version jusqu'à la prochaine version majeure est incluse dans votre licence : vous recevez un email avec un lien de téléchargement frais, et la page des nouveautés raconte ce qui a changé, en français clair. Le support se fait par email, à contact@alohapixel.com, et c'est celui qui a écrit le code qui répond.
Prêt à construire sur du solide ?
Vous achetez une fois, c'est à vous, et vous livrez autant de produits finaux que vous voulez.
Remboursé sous 14 jours, sans justification.