Importer du JSON dans les modules ES (sans Fetch, sans Bundler)

Si vous avez déjà essayé import config from './config.json' dans un projet de modules ES classique et que vous vous êtes heurté à un mur, vous n’êtes pas seul. Pendant des années, importer du JSON sans bundler signifiait se rabattre sur fetch() ou convertir vos données en fichier JavaScript. Cette ère de contournements est révolue.

Depuis 2025, les attributs d’import sont disponibles de base dans les navigateurs modernes. Vous pouvez désormais effectuer un import natif de module JSON en JavaScript sans aucun outillage de build requis.

La syntaxe moderne : les attributs d’import

La syntaxe actuelle utilise le mot-clé with pour déclarer le type de module :

// Static import
import config from './config.json' with { type: 'json' }

console.log(config.apiUrl)

Pour le chargement dynamique :

// Dynamic import
const { default: config } = await import('./config.json', {
  with: { type: 'json' }
})

Remarque : L’ancienne syntaxe assert { type: 'json' } (prise en charge dans Chrome 91–122) est désormais dépréciée. Utilisez toujours with.

Pourquoi l’attribut type: 'json' est-il requis

L’attribut with { type: 'json' } n’est pas une décoration optionnelle. Il remplit un objectif de sécurité précis : il oblige le navigateur ou le runtime à valider le type MIME de la réponse comme application/json avant de traiter quoi que ce soit.

Sans cela, un serveur pourrait renvoyer du JavaScript déguisé en fichier JSON, et le moteur n’aurait aucun moyen d’imposer la distinction. L’attribut type empêche cela.

Les modules JSON n’ont qu’un export par défaut

Un point qui déroute les développeurs : les modules JSON ne prennent pas en charge les exports nommés. L’objet JSON entier arrive en tant qu’export par défaut.

import data from './data.json' with { type: 'json' }

// ✅ Correct
const { users, settings } = data

// ❌ Ceci ne fonctionnera pas
import { users } from './data.json' with { type: 'json' }

Déstructurez depuis l’export par défaut après l’import.

Support navigateurs et Node.js

Environnement	Version minimale
Chrome	123+
Firefox	138+
Safari	17.2+
Node.js	LTS actuelle et plus

Tous ces environnements sont désormais largement déployés. Si vous ciblez des navigateurs modernes et les versions actuelles de Node.js, vous n’avez pas besoin d’un bundler ou d’un appel fetch() pour charger du JSON.

Remarque : Les versions antérieures de Node.js fournissaient les modules JSON derrière des flags expérimentaux. Le support des modules JSON avec les attributs d’import est désormais stable dans les versions actuelles de Node.js. Consultez la documentation ESM de Node.js pour les détails exacts de version.

Contraintes pratiques à connaître avant de déployer

Vous avez besoin d’un serveur HTTP. Les imports de modules — y compris les modules JSON — ne fonctionnent généralement pas lors du chargement de pages directement via file://. Les navigateurs appliquent des règles de sécurité strictes au chargement de modules. Utilisez un serveur de développement local comme Vite, serve, ou n’importe quel serveur de fichiers statiques.

Votre fichier JSON doit être servi avec le type MIME correct. Le serveur doit renvoyer Content-Type: application/json. La plupart des serveurs statiques gèrent cela automatiquement pour les fichiers .json, mais vérifiez si vous utilisez un serveur personnalisé ou une configuration CDN.

Le JSON doit être valide. Il n’y a pas de récupération d’erreur au niveau de l’import. Une erreur de syntaxe dans votre fichier JSON entraînera l’échec complet du chargement du module. Validez votre JSON avant de déployer.

Un exemple concret

// config.json
{
  "apiUrl": "https://api.example.com",
  "timeout": 5000,
  "features": {
    "darkMode": true
  }
}

// app.js
import config from './config.json' with { type: 'json' }

const { apiUrl, timeout, features } = config

if (!apiUrl || typeof timeout !== 'number') {
  throw new Error('Invalid configuration')
}

Ce pattern fonctionne parfaitement pour les fichiers de configuration, les feature flags, les chaînes d’internationalisation, ou toute donnée structurée statique dont votre application a besoin au démarrage.

Conclusion

Les attributs d’import vous offrent une manière propre et native d’importer du JSON dans les modules ES sans fetch(), sans bundler et sans contournements. La syntaxe with { type: 'json' } est désormais largement prise en charge dans les navigateurs modernes et les versions actuelles de Node.js. Assurez-vous simplement que vos fichiers sont servis via HTTP avec le bon type MIME, et vous êtes prêt.

FAQ

Puis-je utiliser les attributs d'import pour charger d'autres types de fichiers que JSON ?

Oui. La proposition d'attributs d'import est conçue pour être extensible. Les scripts de modules CSS, par exemple, utilisent with type css dans les navigateurs compatibles. Cependant, JSON est le type le plus largement pris en charge aujourd'hui. Les autres types dépendent du runtime et peuvent ne pas encore être disponibles partout.

Que se passe-t-il si mon fichier JSON contient une erreur de syntaxe ?

L'import échouera complètement et lèvera une SyntaxError. Contrairement à fetch où vous pouvez intercepter et inspecter la réponse brute, un import de module JSON n'offre aucune récupération partielle. Validez vos fichiers JSON avec un linter ou un contrôle CI avant de déployer pour éviter une défaillance silencieuse au chargement.

Ai-je encore besoin d'un bundler si j'utilise les imports JSON natifs ?

Pas pour l'import JSON lui-même. Les navigateurs modernes et Node.js le gèrent nativement. Cependant, vous pouvez toujours vouloir un bundler pour d'autres raisons comme le code splitting, le tree shaking, ou la transpilation de syntaxe pour des cibles plus anciennes. Le point important est que le chargement JSON seul n'en nécessite plus.

Pourquoi l'import de JSON via une URL file échoue-t-il dans le navigateur ?

Les navigateurs appliquent des règles de sécurité strictes sur le chargement de modules. Le protocole file ne prend pas en charge les mécanismes requis pour les requêtes de modules, donc le navigateur bloque l'import. Vous devez servir vos fichiers via un serveur HTTP, même localement. Des outils comme Vite ou le package npm serve gèrent cela avec une configuration minimale.