Comment formater du JSON en JavaScript (Pretty Print)

La façon la plus rapide de formater du JSON en JavaScript est JSON.stringify(value, null, 2). Le troisième argument, le paramètre space, indique au moteur d'indenter chaque niveau imbriqué, transformant une ligne dense en une sortie lisible et bien formatée. Cette ligne unique couvre la plupart des cas, mais elle échoue sur les références circulaires, supprime silencieusement les fonctions et undefined, et ne vous donne aucun contrôle sur les champs à inclure. Ce guide parcourt le chemin complet du code et les angles morts que chaque tutoriel omet.

Si vous avez juste besoin d'une sortie propre une fois et ne voulez pas écrire un script jetable, vous pouvez coller le texte brut dans un formateur JSON en ligne gratuit et copier le résultat. Pour tout ce qui doit se produire dans votre code, les sections ci-dessous couvrent les arguments, les pièges et les modèles qui comptent vraiment en production.

How to Format JSON in JavaScript With JSON.stringify#

JSON.stringify() takes three arguments: the value to serialize, an optional replacer, and an optional space. To pretty-print, you skip the replacer with null and pass a number or string as space.

const user = { name: "Ada", roles: ["admin", "editor"], active: true };

// Compact (default), everything on one line
JSON.stringify(user);
// {"name":"Ada","roles":["admin","editor"],"active":true}

// Pretty-printed with 2-space indentation
JSON.stringify(user, null, 2);
// {
//   "name": "Ada",
//   "roles": [
//     "admin",
//     "editor"
//   ],
//   "active": true
// }

The space argument is what does the work. Pass a number from 1 to 10 for that many spaces of indent per level, or pass a string (like "\t") to indent with that string instead.

Numbers above 10 are clamped to 10. JSON.stringify(obj, null, 50) behaves exactly like JSON.stringify(obj, null, 10), so do not expect deeper indentation by passing a bigger number.

The space parameter: numbers vs strings#

The space argument accepts two types, and the type changes the output style:

space value	Result	Common use
2	Two spaces per level	JavaScript, JSON config, most web ecosystems
4	Four spaces per level	Python tooling, some Java/.NET outputs
"\t"	One tab per level	Repos that enforce tab indentation
0, null, or omitted	No formatting, single line	API payloads, storage, network transfer

A string space lets you do things a number cannot. Pass " " (two spaces) for the same effect as 2, or pass something visual like "--" to debug nesting depth. Only the first 10 characters of a string space are used.

Why 2 vs 4 spaces actually matters#

This is not bikeshedding. Indentation width is an ecosystem convention, and matching it keeps your output consistent with the tools that will read it next.

• 2 spaces is the de facto standard in the JavaScript and Node world. Prettier defaults to 2, npm's package.json uses 2, and most JSON config files you will touch (tsconfig.json, .eslintrc.json) follow suit.
• 4 spaces shows up where the surrounding language uses 4, most notably Python's json.dumps(obj, indent=4). If a JSON file lives next to Python code or is generated by a Python service, 4 keeps it visually aligned.
• Tabs appear in repos with a tab-based style guide. The win is that each developer can set their own tab display width.

If your project runs Prettier or a formatter on commit, match its setting so you are not fighting the auto-formatter. When in doubt, use 2.

Utiliser une fonction de remplacement pour contrôler la sortie#

Le deuxième argument, replacer, est la fonctionnalité la plus sous-estimée de JSON.stringify. Il contrôle quelles propriétés sont sérialisées et comment leurs valeurs sont transformées. Il accepte soit un tableau, soit une fonction.

Replacer comme tableau de liste blanche#

Passez un tableau de chaînes de noms de propriétés et seules ces clés survivent. C'est la façon la plus propre de supprimer les champs sensibles ou bruyants avant de journaliser ou d'envoyer des données.

const account = {
  id: 42,
  email: "[email protected]",
  passwordHash: "$2b$10$...",
  sessionToken: "abc123",
};

// Seuls id et email apparaissent dans la sortie
JSON.stringify(account, ["id", "email"], 2);
// {
//   "id": 42,
//   "email": "[email protected]"
// }

La liste blanche s'applique à chaque niveau de l'objet, donc une clé nommée id est conservée partout où elle apparaît dans l'arbre. C'est une fonctionnalité pour les formes uniformes et un piège pour les arbres où le même nom de clé signifie des choses différentes à différentes profondeurs.

Replacer comme fonction de transformation#

Passez une fonction et elle s'exécute pour chaque paire clé/valeur. Renvoyez la valeur que vous souhaitez sérialiser, renvoyez undefined pour supprimer la clé, ou transformez à la volée. La fonction reçoit la clé et la valeur, et this est lié à l'objet contenant la clé.

const order = { total: 19.99, secret: "hide-me", createdAt: new Date() };

const json = JSON.stringify(order, (key, value) => {
  if (key === "secret") return undefined;        // supprime le champ
  if (typeof value === "number") return value.toFixed(2); // formate les nombres
  return value;
}, 2);

Surveillez l'ordre d'appel : le replacer est invoqué d'abord avec une clé vide et l'objet entier, puis pour chaque propriété. Si vous transformez les valeurs aveuglément sans vérifier la clé, vous pouvez accidentellement déformer la racine.

Une alternative plus propre pour un contrôle par objet est la méthode toJSON(). Tout objet avec une méthode toJSON() (comme Date, c'est pourquoi les dates sont sérialisées en chaînes ISO) contrôle sa propre forme sérialisée avant même que le replacer ne la voie.

Correction de l'erreur de référence circulaire TypeError#

Voici l'erreur que tous les tutoriels de base ignorent, et celle qui vous arrêtera net. Si un objet se référence lui-même, directement ou via une chaîne, JSON.stringify génère :

TypeError: Converting circular structure to JSON

Cela arrive constamment avec les nœuds DOM, les entités ORM qui renvoient à leur parent, les objets d'événement et toutes les données en forme de graphe.

const node = { name: "root" };
node.self = node; // circulaire

JSON.stringify(node, null, 2); // TypeError: Converting circular structure to JSON

La solution est un replacer qui suit les objets déjà vus et ignore les répétitions :

function safeStringify(value, space = 2) {
  const seen = new WeakSet();
  return JSON.stringify(value, (key, val) => {
    if (typeof val === "object" && val !== null) {
      if (seen.has(val)) return "[Circulaire]";
      seen.add(val);
    }
    return val;
  }, space);
}

safeStringify(node);
// {
//   "name": "root",
//   "self": "[Circulaire]"
// }

Un WeakSet est l'outil approprié ici car il n'empêche pas le ramasse-miettes de libérer les objets qu'il suit. Si vous utilisez un Node récent ou un navigateur moderne, le structuredClone global générera aussi une erreur sur les données circulaires, donc un replacer avec ensemble de vus reste la solution pratique pour la sérialisation.

Valeurs qui disparaissent silencieusement#

JSON.stringify ne se contente pas de générer une erreur sur les données circulaires. Il supprime ou modifie silencieusement plusieurs types de valeurs, ce qui entraîne des bugs déroutants où un champ "disparaît".

• Les fonctions et undefined sont complètement omises des objets, et deviennent null dans les tableaux.
• NaN et Infinity sont sérialisés en null.
• BigInt génère une TypeError. Vous devez d'abord le convertir en chaîne ou en nombre.
• Les clés et valeurs Symbol sont ignorées.
• Date devient une chaîne ISO (via son toJSON), donc il ne fait pas l'aller-retour vers un objet Date lors de l'analyse.

Si une propriété manque dans votre sortie, c'est presque toujours l'une de ces raisons.

Comment minifier du JSON en JavaScript#

La minification est l'inverse de l'affichage formaté : supprimer tous les espaces pour obtenir la charge utile la plus petite possible. On minifie en appelant JSON.stringify sans argument space (ou avec 0).

const data = { name: "Ada", roles: ["admin", "editor"] };

JSON.stringify(data);
// {"name":"Ada","roles":["admin","editor"]}

Pour passer d'un format formaté à un format minifié, analysez la chaîne formatée en objet et refaites stringify sans space :

const pretty = `{
  "name": "Ada",
  "active": true
}`;

const minified = JSON.stringify(JSON.parse(pretty));
// {"name":"Ada","active":true}

Ce motif JSON.parse puis JSON.stringify est aussi la façon la plus simple de reformater un JSON non fiable ou mal indenté : parse normalise, et stringify le réémet avec l'espacement choisi. L'inconvénient est que JSON.parse est strict, donc les virgules finales, guillemets simples, commentaires ou une réponse HTML accidentelle lèveront une SyntaxError avant même de pouvoir formater quoi que ce soit.

Quand ignorer complètement le code#

Écrire JSON.stringify est la bonne approche lorsque le formatage se fait dans votre application : journalisation, construction de fichiers de configuration à l'exécution, normalisation d'une réponse API. Mais il arrive souvent que vous ayez simplement un bloc de JSON moche dans votre presse-papiers et que vous ayez besoin de le lire immédiatement. Ouvrir un REPL, analyser, stringifier et recopier est plus lent que nécessaire.

Pour cela, un formateur basé sur le navigateur est plus rapide et plus sûr :

• Il valide en formatant, donc un JSON mal formé renvoie une erreur claire avec une ligne et une colonne au lieu d'une exception cryptique.
• Vous basculez entre indentation 2 espaces, 4 espaces, tabulation ou sortie minifiée sans réécrire de code.
• Il gère les gros volumes de données qui encombreraient votre console.
• Les bons s'exécutent entièrement côté client, vos données ne quittent donc jamais le navigateur.

Le formateur et validateur JSON de Molixa fait exactement cela : collez, obtenez une sortie joliment formatée et validée, changez l'indentation et copiez. Si vous voulez en savoir plus sur l'utilité d'en avoir un dans votre boîte à outils quotidienne, notre analyse de pourquoi un formateur JSON est un outil quotidien pour les développeurs détaille le workflow. Et lorsque la sortie que vous formatez doit devenir du code typé, le guide JSON vers interface TypeScript montre comment transformer une charge utile propre en interfaces réelles.

Comment créer une fonction de formatage JSON réutilisable#

Si vous formatez du JSON à plusieurs endroits, encapsulez le motif sécurisé une fois et réutilisez-le au lieu de disperser JSON.stringify(obj, null, 2) dans le code. Suivez ces étapes pour créer une fonction utilitaire qui affiche joliment, minifie, gère les tabulations et ne lève jamais d'exception.

Étape 1 : Configurer un ensemble de suivi pour détecter les références circulaires#

Commencez par un WeakSet pour suivre les objets déjà sérialisés. Un WeakSet est le bon choix car il conserve des références faibles et ne bloque pas le ramasse-miettes de ces objets.

function formatJSON(value, { indent = 2, safe = true } = {}) {
  const seen = new WeakSet();
  // le replacer vient ensuite
}

L'objet d'options avec des valeurs par défaut (indent = 2, safe = true) signifie qu'un appel simple formatJSON(data) fait ce qu'il faut : sortie à 2 espaces et sécurisée contre les références circulaires.

Étape 2 : Écrire un replacer qui gère les types non pris en charge#

Ajoutez un replacer qui renvoie un espace réservé pour les objets répétés et convertit BigInt en chaîne pour éviter une exception. C'est la même correction de référence circulaire qu'avant, avec la protection BigInt.

const replacer = safe
  ? (key, val) => {
      if (typeof val === "object" && val !== null) {
        if (seen.has(val)) return "[Circulaire]";
        seen.add(val);
      }
      if (typeof val === "bigint") return val.toString();
      return val;
    }
  : null;

Quand safe est false, le replacer est null, vous obtenez donc le comportement standard de JSON.stringify pour les cas où les données sont propres et que la vitesse est primordiale.

Étape 3 : Sérialiser dans un try/catch pour ne jamais lever d'exception#

Encapsulez l'appel JSON.stringify pour que toute erreur de sérialisation restante renvoie un message lisible au lieu de faire planter votre journalisation ou votre rendu.

  try {
    return JSON.stringify(value, replacer, indent);
  } catch (err) {
    return `// Impossible de formater : ${err.message}`;
  }
}

Étape 4 : Appeler la fonction avec l'indentation souhaitée#

La même fonction utilitaire couvre désormais tous les modes de formatage via l'option indent.

formatJSON(someApiResponse);             // 2 espaces, sécurisé
formatJSON(config, { indent: "\t" });    // indenté par tabulation
formatJSON(payload, { indent: 0 });      // minifié

Placez-la dans un fichier d'utilitaires et vous aurez l'affichage joli, la minification, l'indentation par tabulation, ainsi que les problèmes de références circulaires et de BigInt résolus en un seul endroit.

Formater du JSON en JavaScript : la version courte#

Pour formater du JSON en JavaScript, utilisez d'abord JSON.stringify(value, null, 2). C'est le bon outil neuf fois sur dix. Souvenez-vous des trois choses que les tutoriels oublient : un tableau replacer est une liste blanche propre pour supprimer les champs sensibles, un replacer avec ensemble de références corrige l'erreur TypeError de références circulaires, et plusieurs types de valeurs (fonctions, undefined, BigInt, NaN) sont ignorés ou génèrent une erreur plutôt que d'être sérialisés.

Lorsque le JSON se trouve dans votre presse-papiers plutôt que dans votre code, évitez d'écrire un script et collez-le dans un formateur et validateur JSON pour un affichage instantané, une validation et une minification en un clic. Adaptez votre indentation (généralement 2 espaces) à votre écosystème, gardez l'outil réutilisable à portée de main, et vous ne lutterez plus jamais contre du JSON illisible.

Foire Aux Questions#

Comment afficher joliment du JSON en JavaScript ? Utilisez JSON.stringify(valeur, null, 2). Le troisième argument est le paramètre space : passer 2 indente chaque niveau imbriqué avec deux espaces, produisant une sortie lisible. Passez 4 pour quatre espaces ou "\t" pour une indentation par tabulation.

Que fait le troisième argument de JSON.stringify ? Le troisième argument est space, qui contrôle l'indentation. Un nombre de 1 à 10 indente d'autant d'espaces par niveau, et une chaîne utilise cette chaîne comme indentation (seuls les 10 premiers caractères comptent). L'omettre, ou passer 0 ou null, produit une sortie compacte sur une seule ligne sans mise en forme.

Pourquoi JSON.stringify lève-t-il "Converting circular structure to JSON" ? Parce qu'un objet se référence lui-même directement ou via une chaîne, et JSON n'a aucun moyen de représenter cette boucle. Corrigez-le avec une fonction de remplacement qui suit les objets déjà vus dans un WeakSet et renvoie un espace réservé comme "[Circular]" pour les répétitions, au lieu de laisser le moteur récurser indéfiniment.

Comment minifier du JSON en JavaScript ? Appelez JSON.stringify(valeur) sans argument space, ou passez 0. Pour minifier une chaîne formatée existante, exécutez JSON.stringify(JSON.parse(chaîneFormatée)), qui la parse en objet et la réémet sans espace blanc.

Pourquoi certaines propriétés disparaissent-elles quand je stringifie un objet ? JSON.stringify supprime silencieusement les fonctions, les valeurs undefined et les clés Symbol des objets, et convertit NaN et Infinity en null. Les valeurs BigInt lèvent carrément une TypeError. Si un champ manque dans votre sortie, c'est presque toujours l'un de ces types non pris en charge.

Dois-je utiliser 2 ou 4 espaces pour formater du JSON ? Adaptez-vous à votre écosystème. JavaScript et Node utilisent par défaut 2 espaces (Prettier, npm, tsconfig.json), tandis que les outils Python utilisent souvent 4. Si votre projet exécute un formateur lors du commit, utilisez ce qu'il impose pour ne pas lutter contre l'auto-formateur. En cas de doute, 2 espaces est la valeur par défaut la plus sûre.