🖥 Anatomie de l'interface

Barre d'outils (haut)

▶ Preview	Lance / rafraîchit la prévisualisation
💾 Sauvegarder	Enregistre le projet dans les options du widget Grist
📦 Installer	Transforme le widget courant en widget autonome (consomme l'installation)
📚 Templates	Ouvre la bibliothèque de templates prêts à l'emploi
📦 Packages	Ajoute des bibliothèques externes (Chart.js, D3, etc.) via CDN
⬇ Export	Télécharge ton projet en ZIP
⬆ Import	Charge un projet depuis un fichier ZIP/JSON
🔌 Proxy	Configure l'URL de ton proxy CORS (pour les appels API externes)
☀️/🌙	Bascule dark / light mode

Sidebar gauche

• EXPLORER — Arborescence de tes fichiers (+ pour en ajouter)
• API COLLECTIONS — Sauvegarde tes requêtes API récurrentes
• GRIST TABLES — Explore les tables du document (clique pour inspecter)

Panneau droit (preview + outils)

• 👁 Preview — Ton widget en live, avec choix de taille (Desktop/Tablet/Mobile)
• 🌐 API — Testeur de requêtes API avec Headers/Auth/Body/Params
• 🐛 Console — Les console.log de ton widget, avec filtres par niveau
• 📡 Network — Historique de toutes les requêtes API avec timing

🚀 Créer ton premier widget en 5 minutes

🌐 API Grist - Cheat Sheet

Initialisation

// En lecture seule
grist.ready({ requiredAccess: 'read table' });

// En lecture/écriture (pour modifier des records)
grist.ready({ requiredAccess: 'full' });

Lire les données

// Écouter le record sélectionné
grist.onRecord(record => {
  console.log('Record:', record);
});

// Écouter tous les records de la table liée
grist.onRecords(records => {
  console.log('Records:', records);
});

// Récupérer toute une table (format colonnaire)
const data = await grist.docApi.fetchTable('MaTable');
// → { id: [1,2,3], Name: ['A','B','C'], ... }

// Liste des tables du document
const tables = await grist.docApi.listTables();

Modifier les données

// Ajouter un record
await grist.docApi.applyUserActions([
  ['AddRecord', 'MaTable', null, { Name: 'Alice', Age: 30 }]
]);

// Modifier un record
await grist.docApi.applyUserActions([
  ['UpdateRecord', 'MaTable', rowId, { Status: 'Done' }]
]);

// Supprimer un record
await grist.docApi.applyUserActions([
  ['RemoveRecord', 'MaTable', rowId]
]);

// Ajouts/mises à jour en masse
await grist.docApi.applyUserActions([
  ['BulkAddRecord', 'MaTable', [null, null],
    { Name: ['Bob', 'Carol'], Age: [25, 35] }]
]);

Créer des tables/colonnes

await grist.docApi.applyUserActions([
  ['AddTable', 'NouvelleTable', [
    { id: 'Name', type: 'Text' },
    { id: 'Count', type: 'Int' }
  ]]
]);

Options du widget (persistance)

// Sauvegarder
await grist.setOptions({ myConfig: { ... } });

// Lire
const options = await grist.getOptions();

📡 Testeur d'API (type Postman)

L'onglet 🌐 API dans le panneau droit te permet de tester des APIs externes avant de les intégrer dans ton widget.

Workflow typique

1. Choisis la méthode (GET, POST, PUT, PATCH, DELETE)
2. Entre l'URL
3. Configure :
   • Headers — paires clé/valeur
   • Auth — Aucune / Bearer Token / Basic Auth / API Key
   • Body — JSON / Form Data / Raw Text (pour POST/PUT/PATCH)
   • Params — query string params
4. Coche CORS Proxy si l'API bloque les requêtes cross-origin
5. Clique Send
6. Réponse affichée avec status/temps/taille

🎁 Génération de code automatique

Clique sur → Utiliser dans le code pour générer un snippet fetch() complet et l'insérer directement dans script.js. Le snippet utilise automatiquement ton proxy configuré.

Exemples d'APIs publiques pour tester

• https://api.github.com/users/octocat — API GitHub
• https://jsonplaceholder.typicode.com/posts — Données test
• https://api.openweathermap.org/data/2.5/weather?q=Paris&appid=YOUR_KEY — Météo
• https://restcountries.com/v3.1/name/france — Données pays

🔌 Proxy CORS - Pourquoi et comment

Pourquoi un proxy ?

Beaucoup d'APIs refusent les requêtes venant d'autres domaines (CORS = Cross-Origin Resource Sharing). Le navigateur bloque alors la requête depuis ton widget.

Un proxy CORS est un petit serveur qui relaie ta requête : l'API parle au serveur (pas de problème CORS), et le serveur te répond en autorisant ton domaine.

🎯 Pourquoi ton propre proxy ?

Plutôt que d'utiliser un proxy public partagé (risqué, limité, instable), déploie le tien en 2 minutes sur la plateforme de ton choix. Tu gardes le contrôle total : coûts, sécurité, quotas, logs.

🚀 Plateformes supportées

⚡ Cloudflare Workers	100k req/jour gratuites	⭐ Recommandé (ultra rapide, edge)
▲ Vercel	100 Go-h/mois	Simple, populaire
🦕 Deno Deploy	1M req/mois	Le plus généreux
🟢 Netlify	125k req/mois	Alternative à Vercel
🟩 Node.js/Docker	Selon ton infra	Self-hosted (VPS, RPi)

📝 Configuration

1. Clique sur 🔌 Proxy dans la barre d'outils
2. Choisis une plateforme → tu verras les instructions exactes
3. Déploie ton proxy (en général 1 commande terminal)
4. Copie l'URL publique du proxy
5. Colle-la dans le champ URL du proxy
6. Clique Tester pour valider
7. Optionnel : ajoute un PROXY_TOKEN pour sécuriser l'accès
8. Sauvegarder

🔒 Sécurité intégrée

Tous les proxies incluent automatiquement :

• Blocage des IPs privées (localhost, 192.168.*, 10.*, .local)
• Timeout 25s, max 1 MB par réponse
• Auth optionnelle par token (X-Proxy-Token)
• Whitelist/blacklist configurables (ALLOWED_HOSTS, BLOCKED_HOSTS)

📖 Voir la doc complète du proxy sur GitHub.

⌨️ Raccourcis clavier

Globaux

Ctrl+S	Sauvegarder le projet dans Grist
Ctrl+Enter	Lancer / rafraîchir le preview
Esc	Fermer un modal

Éditeur Monaco

Ctrl+F	Rechercher
Ctrl+H	Rechercher et remplacer
Ctrl+D	Sélectionner l'occurrence suivante
Ctrl+/	Commenter / décommenter
Alt+↑/↓	Déplacer la ligne
Ctrl+Shift+K	Supprimer la ligne
F2	Renommer le symbole
Ctrl+Space	Forcer l'auto-complétion
Ctrl+Shift+P	Palette de commandes Monaco

Système (Mac)

Sur Mac, remplace Ctrl par Cmd (⌘).

💡 FAQ - Questions fréquentes