Démarrage local

Prérequis#

node -v     # v20.x ou plus
npm -v

Trois façons de commencer#

1. Créer le site#

npm create inline@latest boulangerie-martin -- \
  --nom "Boulangerie Martin" \
  --courriel contact@boulangerie-martin.fr \
  --langue fr

cd boulangerie-martin
npm install

La commande refuse d'écrire dans un dossier existant et non vide. Elle produit :

boulangerie-martin/
  astro.config.mjs          intégration inline, sortie statique, i18n
  package.json              dev, build, serve:functions, mock:git, make:key, check
  wrangler.toml             configuration de l'hébergeur (fonctions)
  .gitignore                node_modules, dist, .astro, .dev.vars…
  .env.example              le SEUL fichier d'environnement versionné
  .dev.vars                 accès d'essai local — ignoré par Git
  functions/api/*.ts        quatre adaptateurs de routes
  scripts/                  check-html, check-locales, check-logs, check-secrets,
                            make-key, mock-git-api
  src/
    content/config.ts       déclaration de la collection
    content/site.json       navigation, coordonnées, pied de page
    content/pages/fr/home.json
    components/Testimonial.astro
    layouts/Base.astro
    lib/locales.ts          les langues de CE site
    pages/[lang]/[...slug].astro
    styles/theme.css        la charte — le fichier à reprendre
  .github/workflows/ci.yml  contrôles automatiques

La clé, affichée une seule fois

À la fin, la commande affiche la clé du site. Elle est déjà écrite dans .dev.vars pour l'essai local, mais elle n'est stockée nulle part sous forme lisible côté serveur : seule son empreinte argon2id existe. Une clé perdue se régénère, elle ne se retrouve pas.

2. Lancer les trois processus#

Trois terminaux, à la racine du projet :

1. Le faux dépôt Git

   npm run mock:git

   Écoute sur http://127.0.0.1:8787 et imite les deux routes de l'API Contents de GitHub réellement utilisées. Les publications écrivent directement dans les fichiers du projet, comme le ferait un commit. Aide au développement uniquement.

2. Le build

   npm run build

   Construit dist/. Le build échoue si le contenu ne passe pas le schéma, ou si un data-cms pointe vers une clé absente — c'est voulu.

3. Le site et les fonctions

   npm run serve:functions

   Sert dist/ et /functions sur http://127.0.0.1:8788. C'est ici qu'on édite.

3. Première modification#

1. Ouvrir http://127.0.0.1:8788/admin.
2. Coller la clé affichée à la création, valider.
3. Vous arrivez sur le site, avec une barre en bas de l'écran.
4. Cliquer sur un titre : il devient modifiable, une barre de variantes apparaît.
5. Modifier le texte, puis cliquer sur Publier.

Avec le faux dépôt, la publication écrit dans src/content/pages/fr/home.json. Relancez npm run build pour voir la modification figée dans le HTML — en production, l'hébergeur le fait tout seul.

Les ports utilisés#

Le fichier .dev.vars#

C'est le fichier d'environnement local, ignoré par Git, jamais déployé. Il est écrit par la commande de création, et ressemble à ceci :

# Essai local uniquement. Ignoré par Git, jamais déployé.
EDITOR_KEY_HASH=$argon2id$v=19$m=19456,t=2,p=1$<sel>$<empreinte>
SESSION_SECRET=<32 caractères au moins>
EDITOR_NAME=Éditeur du site
EDITOR_EMAIL=contact@boulangerie-martin.fr
GIT_PROVIDER=github
GIT_REPO=agence/boulangerie-martin
GIT_BRANCH=main
GIT_TOKEN=essai-local
GIT_API_BASE=http://127.0.0.1:8787

GIT_API_BASE est la ligne qui bascule vers le faux dépôt. La retirer fait parler la fonction au vrai GitHub — avec un GIT_REPO et un GIT_TOKEN réels. Le détail de chaque variable : Référence.

Régénérer les accès#

Depuis le site — clé perdue, clé à changer

La clé n'est stockée nulle part sous forme lisible : seule son empreinte argon2id vit en variable d'environnement. Elle ne se retrouve donc pas, elle se régénère — et c'est voulu.

npm run make:key

La commande affiche la nouvelle clé, son empreinte et un secret de session. Rien n'est écrit sur disque : ce qui n'est pas copié à ce moment-là est perdu. La suite — remplacer les variables, redéployer, transmettre — est dans Sécurité et authentification.

Depuis le dépôt de référence — préparer un site

# Accès complets d'un site : clé, empreinte, secret de session, variables, aide-mémoire
npm run create:site -- --nom "Boulangerie Martin" --depot agence/boulangerie-martin

# Idem, plus l'écriture d'un .dev.vars local prêt à l'emploi
npm run create:site -- --nom "Essai local" --ecrire

create:site affiche deux blocs qui ne voyagent pas ensemble : ce qui part chez le client (une clé, une adresse) et ce qui part chez l'hébergeur (l'empreinte, les secrets, le jeton), plus la liste de vérification d'avant livraison. Voir Exploitation.

Dans un projet Astro qui existe déjà#

1. Installer le paquet

   npm install inline-core

2. Déclarer l'intégration

   import { defineConfig } from 'astro/config';
   import inline from 'inline-core/astro';
   
   export default defineConfig({
     output: 'static',
     integrations: [
       inline({
         locales: ['fr'],                            // la référence en premier
         support: { email: 'contact@agence.fr' },    // affichée au client
         // theme: 'src/styles/theme.css',           // défaut
         // pages: { admin: true, help: true },      // false pour fournir les vôtres
       }),
     ],
   });

   L'intégration pose /admin et /aide, construit l'overlay, injecte l'amorce d'édition, crée src/media/library.ts s'il manque, et refuse de démarrer si la sortie n'est pas statique.

3. Écrire les quatre adaptateurs de routes

   L'hébergeur découvre les routes par l'arborescence de /functions, hors du build Astro : une intégration ne peut pas les injecter. Vingt lignes, écrites une fois.

   import { createSaveRoute } from 'inline-core/server';
   import { LOCALES } from '../../src/lib/locales';
   
   const route = createSaveRoute({ locales: LOCALES });
   
   export const onRequest = route.onRequest;
   export const onRequestPost = route.onRequestPost;

   Les trois autres sont identiques avec createAuthRoute(), createContentRoute({ locales }) et createUploadRoute(). Le détail : Référence des routes.

4. Déclarer le schéma et la charte

   import { defineCollection } from 'astro:content';
   import { glob } from 'astro/loaders';
   import { pageSchema } from 'inline-core/schema';
   
   const pages = defineCollection({
     loader: glob({ pattern: '**/*.json', base: './src/content/pages' }),
     schema: pageSchema,
   });
   
   export const collections = { pages };

   ---
   import 'inline-core/styles/tokens.css';
   import '../styles/theme.css';
   ---

5. Générer une clé

   Sans EDITOR_KEY_HASH, l'édition est impossible — c'est l'état par défaut. Voir Sécurité.

Travailler sur inline-core lui-même#

Le dépôt de référence est un espace de travail npm : packages/inline-core et packages/create-inline y sont installés par lien, et le site à la racine les consomme directement.

git clone <depot> inline && cd inline
npm install

npm run create:site -- --nom "Essai local" --ecrire   # écrit .dev.vars, affiche la clé
npm run build
npm run serve:functions

npm test          # toute la suite : git, auth, durcissement, amorçage, assainissement, médias…
npm run check     # HTML brut, parité des langues, journaux, secrets

Pour éprouver les paquets tels qu'ils partiraient au registre, voir Exploitation (test:scaffold et test:pack).

Si ça ne démarre pas#

Liste complète : Dépannage et pièges connus.