Comment fonctionne l'Aperçu d'une application en marche

Le tunnel vers localhost, les ports autorisés, les cibles nommées, et quoi faire quand l'Aperçu montre une vieille version de la page.

8 minutes Mis à jour 2026-09-13

L'Aperçu ouvre sur le téléphone l'application qui tourne sur votre ordinateur en localhost. Pas une copie, pas une capture — cette application en train de tourner. L'Agent change quelque chose, vous touchez rafraîchir et vous le voyez.

Comment les données arrivent là

Le navigateur de l'application parle au localhost du téléphone, et le Serveur de l'autre côté ouvre une connexion TCP vers localhost:port chez lui. Entre les deux se trouve le même canal chiffré par lequel passe tout le reste.

Dans le tunnel rien n'est réécrit — ni les en-têtes ni le contenu. Grâce à ça les WebSockets fonctionnent aussi, si bien qu'un serveur de développement avec rechargement à chaud se comporte comme sur l'ordinateur.

Rien n'est publié où que ce soit. Une application sur localhost reste sur localhost ; le tunnel n'existe que pendant que l'Aperçu est ouvert.

Ports autorisés

Le Serveur ne laisse passer que les ports des plages autorisées. Par défaut ce sont :

3000–3999, 4000–4999, 5173, 8000–8999

Les serveurs de développement habituels y tiennent, les bases de données et SSH non. Cela se change dans la configuration du Serveur :

{
  "allowed_ports": [{ "from": 3000, "to": 3999 }, { "from": 9000, "to": 9000 }]
}

Une tentative sur un port hors plage est écrite dans le journal du Serveur. C'est la seule trace que le téléphone a essayé d'aller là où il ne doit pas.

Cibles nommées — et pourquoi elles valent le coup

Dans la configuration du Serveur on peut nommer des applications entières, c'est-à-dire non pas un port mais un groupe :

{
  "preview_targets": [
    { "name": "jobino", "port": 3000, "extra_ports": [8000] }
  ]
}

Dans l'Aperçu elles apparaissent alors comme un bouton sous « De la configuration du Serveur » et s'ouvrent tous leurs ports d'un coup.

C'est la solution la plus fréquente d'un problème qui ressemble à une application cassée : la page charge, mais la connexion ou le chargement des données échoue. Le frontend tourne sur 3000, l'API sur 8000 — et quand seul 3000 est ouvert, les requêtes vers l'API ne mènent nulle part depuis le téléphone. Une cible nommée ouvre les deux.

Une cible avec un port hors des plages autorisées est refusée par le Serveur dès le démarrage. S'il la laissait passer, l'Aperçu s'ouvrirait et seule la requête vers l'API échouerait — et on la chercherait dans l'application, pas dans le fichier où elle se trouve vraiment.

Une vieille version de la page

La confusion la plus fréquente : l'Agent annonce que c'est fini, mais dans l'Aperçu c'est toujours l'ancien. En général l'une de ces trois choses est en cause — dans cet ordre :

Le navigateur garde la page chargée: Touchez rafraîchir dans la barre de l'Aperçu. Ce n'est pas un reload ordinaire — c'est une nouvelle fenêtre qui se charge, si bien que rien de ce que le navigateur a mis de côté n'est utilisé. C'est précisément pour ça que c'est fait comme ça : vous appuyez au moment où vous avez changé le code, et vous voulez voir le nouveau.
Le serveur de développement de l'ordinateur n'a pas rechargé: Si l'Agent a changé quelque chose qui n'est pas repris à chaud — configuration, dépendances, build — rafraîchir sur le téléphone n'aidera pas, car sur l'ordinateur c'est toujours l'ancien processus qui tourne. Faites redémarrer ce serveur par l'Agent.
Le tunnel est bloqué sur une vieille connexion: Fermez l'Aperçu et rouvrez-le. Une nouvelle connexion vers localhost naît — c'est l'étape qui aide quand le serveur de développement a redémarré entre-temps et que l'ancienne connexion est restée pendue.

Quand même ça n'aide pas, c'est presque toujours du côté de l'ordinateur, pas du téléphone. La vérification la plus rapide est d'ouvrir cette adresse dans le navigateur de l'ordinateur.

D'autres choses qu'on confond

Rien n'écoute sur le port: L'application sur l'ordinateur ne tourne pas, ou elle tourne sur un autre port. L'erreur, l'Aperçu la montre comme un message avec la possibilité de réessayer, pas comme une page d'erreur du navigateur.
Il écoute, mais seulement en IPv6: Vite se lie par défaut à [::1]. Le Serveur essaie les deux familles d'adresses, donc cela fonctionne — et si cela échoue quand même, le message montre quelle adresse a refusé.
Un écran blanc sans erreur: Le plus souvent une requête vers un autre port, qui depuis le téléphone ne mène nulle part. L'Aperçu attrape ces requêtes et vous en informe — mais la solution est une cible nommée avec tous les ports, voir plus haut.
L'application enregistre un service worker: Le navigateur du téléphone ne prend pas en charge les service workers en HTTP. L'Aperçu glisse à leur place un substitut inerte pour que l'application ne tombe pas — mais le mode hors ligne ne fonctionne pas dans l'Aperçu et n'est pas censé fonctionner.
Une mise en page cassée: Basculez la largeur sur « Ordinateur ». Une application écrite pour le bureau se comporte autrement à la largeur d'un téléphone, et ce n'est pas la faute de l'Aperçu.

Ça a coincé ailleurs que ce qui est ici ? Écrivez à support@coden-app.com.