Supabase Edge Functions en pratique : runtime Deno et guide TypeScript

Le téléphone vibre sans arrêt. Les webhooks Stripe renvoient des 500 en production — le paiement est passé, la commande n’a pas été créée.

En creusant les logs, le coupable : l’ancienne fonction serverless — cold start trop long, Stripe timeout avant la réponse. Et en plus, il fallait encore monter une passerelle API pour les signatures et le CORS…

Cette nuit-là, j’ai sérieusement creusé Supabase Edge Functions. Au début, « runtime Deno » m’a un peu freiné — des années de Node.js, changer de runtime, c’est réapprendre des API. Mais en pratique, la logique est différente : ce n’est pas une « migration », c’est une option plus légère pour les scénarios sans dépendances lourdes.

Cet article partage les pièges et ce que j’ai appris : architecture d’Edge Functions, différences Deno/Node.js, flux de dev local, et comment écrire une API proprement avec Hono.

Qu’est-ce qu’Edge Functions — architecture et choix techniques

Commençons par ce que c’est, et pourquoi Supabase a choisi Deno plutôt que Node.js.

Exécution edge, pas hébergement cloud centralisé

Edge Functions, ce sont des fonctions TypeScript sur des nœuds edge. Contrairement à Lambda ou Vercel Functions, ce n’est pas déployé dans quelques grandes régions : c’est réparti sur des centaines de points edge dans le monde.

Conséquence : un utilisateur à Shanghai peut exécuter la fonction à Tokyo — la latence passe de centaines de millisecondes à quelques dizaines.

Mais l’edge a un prix — la fonction ne doit pas être trop lourde. Chaque fonction tourne dans un isolate V8, avec son propre tas mémoire et son thread d’exécution ; démarrage en millisecondes, mais mémoire et durée limitées. Idéal pour les opérations courtes : webhooks, images OG, appels API tiers, envoi d’e-mails.

Moins adapté : tâches longues, bibliothèques Node.js natives lourdes, accès au système de fichiers.

Pourquoi Deno

J’ai longtemps parcouru les GitHub Discussions Supabase. L’explication officielle, en gros :

1. Démarrage rapide : Deno emballe le code en ESZip, cold start 0-5 ms ; Lambda Node.js plutôt 100-500 ms.
2. Modèle de sécurité : accès fichiers et réseau désactivés par défaut, autorisation explicite. Important en multi-tenant edge — vous ne voulez pas qu’une fonction lise les données d’un autre tenant.
3. TypeScript natif : pas de tsconfig ni ts-node, un fichier .ts suffit. Pour ceux qui font déjà du backend en TypeScript, moins de config.
4. Portabilité : Deno s’intègre dans d’autres apps. Supabase utilise sa branche deno_core, optimisée pour l’embarqué.

Contrepartie : l’écosystème est plus petit que Node.js ; certains paquets npm ne passent pas. Deno supporte désormais les npm specifiers (import { xxx } from 'npm:lodash'), la compatibilité s’améliore.

Aperçu de l’architecture

Flux approximatif d’une requête :

Client → CDN/passerelle edge → validation JWT → isolate V8 exécute la fonction → réponse

Point clé : la validation JWT — Edge Functions vérifie par défaut l’en-tête Authorization. Pour un accès public, déployez avec --no-verify-jwt.

Vultr - Serveur cloud NVMe haute performance, 32 emplacements mondiaux, déploiement Docker en un clic

Voir les tarifs →Pub

Environnement de développement et commandes CLI

Concepts posés, passons à la pratique.

Installer Supabase CLI

Sous macOS, Homebrew :

brew install supabase/tap/supabase

Linux et Windows ont leurs méthodes ; la doc officielle est claire, je ne les répète pas.

Puis connexion :

supabase login

Le navigateur s’ouvre pour autoriser le CLI sur votre compte Supabase.

Initialiser le projet

Dans le répertoire du projet :

supabase init

Cela crée supabase/ avec config.toml et le sous-répertoire functions/ si besoin.

Créer sa première Edge Function

supabase functions new hello-world

La commande crée supabase/functions/hello-world/ avec un index.ts :

Deno.serve(async (req: Request) => {
  const { name } = await req.json()
  const data = {
    message: `Hello ${name}!`,
  }

  return new Response(JSON.stringify(data), {
    headers: {
      'Content-Type': 'application/json',
      'Connection': 'keep-alive',
    },
  })
})

Voilà. Deno.serve() est l’API native Deno ; Request et Response sont les Web API standard, comme fetch dans le navigateur.

Serveur de développement local

supabase functions serve --env-file supabase/.env.local

Serveur local sur http://localhost:54321 ; la fonction est à http://localhost:54321/functions/v1/hello-world.

Premier piège que j’ai eu : oublier de lancer la stack Supabase locale (PostgreSQL inclus). Ordre correct :

# D'abord la stack locale
supabase start

# Puis les fonctions
supabase functions serve

Requête de test

Avec curl ou HTTPie :

curl -i --location --request POST 'http://localhost:54321/functions/v1/hello-world' \
  --header 'Authorization: Bearer <your-anon-key>' \
  --header 'Content-Type: application/json' \
  --data '{"name":"World"}'

Réponse :

{
  "message": "Hello World!"
}

Ça marche.

Le rechargement à chaud est automatique : modifier le code suffit, pas besoin de redémarrer.

Variables d’environnement

Ne mettez pas les secrets dans le code. Supabase gère les variables via .env :

# Créer le fichier .env
echo "MY_SECRET=super_secret_value" > supabase/.env.local

# Lire dans la fonction
const mySecret = Deno.env.get('MY_SECRET')

En production, supabase secrets set :

supabase secrets set MY_SECRET=super_secret_value

En pratique : API RESTful avec Hono

Deno.serve() suffit pour du simple ; avec routage, middlewares et validation, à la main c’est pénible.

Railway - Plateforme de déploiement moderne, sans opérations complexes, en ligne en quelques minutes

Commencer →Pub

Entre Hono.

Qu’est-ce que Hono

Hono est un framework web ultra-léger pour runtimes edge. Deno, Cloudflare Workers, Bun… routage performant, TypeScript au premier plan.

Officiellement « small, simple, and ultrafast » — mon expérience va dans ce sens.

Intégration dans Edge Functions

Nouvelle fonction :

supabase functions new user-api

Puis modifier index.ts :

import { Hono } from 'jsr:@hono/hono'
import { cors } from 'jsr:@hono/hono/cors'
import { logger } from 'jsr:@hono/hono/logger'

const app = new Hono().basePath('/api')

// Middlewares
app.use('*', cors())
app.use('*', logger())

// Routes
app.get('/users/:id', (c) => {
  const id = c.req.param('id')
  return c.json({ user: { id, name: 'Demo User', email: '[email protected]' } })
})

app.post('/users', async (c) => {
  const body = await c.req.json<{ name: string; email: string }>()
  // Ici : branchement base Supabase
  return c.json({ created: body }, 201)
})

app.put('/users/:id', async (c) => {
  const id = c.req.param('id')
  const body = await c.req.json<{ name?: string; email?: string }>()
  return c.json({ updated: { id, ...body } })
})

app.delete('/users/:id', (c) => {
  const id = c.req.param('id')
  return c.json({ deleted: id })
})

// Démarrage
Deno.serve(app.fetch)

Points importants :

1. jsr:@hono/hono est le format JSR Deno, pas npm. JSR est le registre officiel Deno.
2. basePath('/api') préfixe les routes par /api.
3. c est le contexte Hono : requête, réponse, utilitaires.
4. c.json() définit Content-Type et gère null/undefined.

Connexion à la base Supabase

Hono est le framework web ; pour la base, le client Supabase. Exemple complet :

import { Hono } from 'jsr:@hono/hono'
import { createClient } from 'jsr:@supabase/supabase-js@2'

const app = new Hono().basePath('/api')

// Client Supabase
const supabaseUrl = Deno.env.get('SUPABASE_URL')!
const supabaseKey = Deno.env.get('SUPABASE_SERVICE_ROLE_KEY')!

const supabase = createClient(supabaseUrl, supabaseKey, {
  auth: {
    autoRefreshToken: false,
    persistSession: false,
  },
})

// GET /api/users — liste
app.get('/users', async (c) => {
  const { data, error } = await supabase
    .from('users')
    .select('id, name, email, created_at')

  if (error) {
    return c.json({ error: error.message }, 500)
  }
  return c.json({ users: data })
})

// POST /api/users — création
app.post('/users', async (c) => {
  const body = await c.req.json<{ name: string; email: string }>()

  const { data, error } = await supabase
    .from('users')
    .insert(body)
    .select()
    .single()

  if (error) {
    return c.json({ error: error.message }, 400)
  }
  return c.json({ user: data }, 201)
})

Deno.serve(app.fetch)

J’utilise SUPABASE_SERVICE_ROLE_KEY : permissions complètes, contourne le RLS. À manier avec prudence en production.

Gestion d’erreurs et validation

Hono n’a pas de validateur intégré, mais Zod fonctionne bien :

import { z } from 'npm:zod'
import { zValidator } from 'jsr:@hono/zod-validator'

const userSchema = z.object({
  name: z.string().min(1).max(100),
  email: z.string().email(),
})

app.post(
  '/users',
  zValidator('json', userSchema),
  async (c) => {
    const validated = c.req.valid('json')
    // validated est typé de façon sûre
    return c.json({ received: validated })
  }
)

En cas d’échec de validation : 400 avec le détail des erreurs.

Déploiement et bonnes pratiques en production

Ça tourne en local, place à la prod.

Commande de déploiement

supabase functions deploy user-api

Au premier déploiement, le CLI demande le projet Supabase à lier. Ensuite : upload, build, déploiement automatiques.

URL de la fonction :

https://[PROJECT_ID].supabase.co/functions/v1/user-api

Variables d’environnement et Secrets

En production, variables à configurer séparément :

supabase secrets set SUPABASE_URL=https://xxx.supabase.co
supabase secrets set SUPABASE_SERVICE_ROLE_KEY=eyJxxx...

Secrets chiffrés ; lecture via Deno.env.get() à l’exécution.

Stratégie de validation JWT

Edge Functions valide le JWT par défaut :

• Seules les requêtes avec Authorization: Bearer <token> valide passent
• Les infos utilisateur du token sont dans les en-têtes de req

Pour une API publique (webhook tiers), --no-verify-jwt :

Alibaba Cloud - Choix n°1 des développeurs, 15 % de réduction exclusive sur Lighthouse

Obtenir -15 % →Pub

supabase functions deploy user-api --no-verify-jwt

Tout le monde peut alors appeler la fonction — à vous de valider dans le code.

Réduire la latence de cold start

Deno démarre vite, mais on peut aller plus loin :

1. Réduire le volume des dépendances : privilégier Deno/JSR, moins de paquets npm
2. Chargement différé : gros modules via import() à la demande
3. Fonctions légères : une fonction, une responsabilité — pas tout le backend dedans

Supabase recommande moins de 2 secondes d’exécution et un cold start de 0-5 ms. Ces conseils accélèrent la réponse :

Monitoring et logs

Le Dashboard affiche logs d’appel et erreurs. Intégration possible avec Sentry ou autre.

L’API EdgeRuntime.waitUntil() permet de continuer en arrière-plan après la réponse :

EdgeRuntime.waitUntil(
  fetch('https://analytics.example.com/track', { method: 'POST', body: '...' })
)

return new Response('OK')

Le client reçoit la réponse sans attendre la tâche de fond.

Conclusion

Edge Functions, pour quels cas ?

Adapté :

• Webhooks (Stripe, GitHub, Slack)
• Génération d’images OG
• Inférence IA (appels API LLM)
• E-mails et notifications
• Traitements de données à courte durée

Moins adapté :

• Tâches longues (transcodage vidéo)
• Bibliothèques Node.js natives lourdes
• Accès au système de fichiers

Si vous utilisez déjà la base et l’auth Supabase, Edge Functions prolonge naturellement la stack — pas de serveur à monter, pas d’ops lourds, vous écrivez la logique métier.

Face à Cloudflare Workers ou Vercel Functions ? Chacun a ses forces. Workers est plus mature, Vercel s’intègre à Next.js. Mais avec Supabase, Edge Functions offre la meilleure intégration — client base, auth, stockage prêts.

Pour commencer : github.com/supabase/supabase/tree/master/examples/edge-functions

Questions en commentaire, ou sur le Discord Supabase.