Bibliothèques tierces

Les bibliothèques tierces nécessitent un forfait Enterprise. Contactez votre gestionnaire de compte pour les activer sur votre site.

Utilisez des composants issus de paquets npm, tels que des graphiques ou votre propre design system, dans vos pages MDX. Lors du déploiement, Mintlify installe les paquets de votre lockfile, rend chaque composant en HTML et charge son JavaScript dans le navigateur.

N’installez que des paquets de confiance. Le code des paquets s’exécute avec le même accès que la page, y compris le contenu de la page et tout ce que le navigateur du lecteur stocke pour votre site. Il peut effectuer des requêtes réseau vers n’importe quel serveur. Supprimer un paquet ou annuler un déploiement n’arrête pas le code déjà chargé dans le navigateur d’un lecteur.

Les bibliothèques tierces ne sont pas disponibles sur les sites qui utilisent l’authentification ou la personnalisation. Les déploiements qui incluent packages dans docs.json échouent sur ces sites.

Ajouter un paquet

Listez vos dépendances

Créez un fichier package.json dans le même dossier que votre fichier docs.json. Listez chaque paquet que vous importez sous dependencies, y compris react et react-dom.

package.json

{
  "private": true,
  "dependencies": {
    "@acme/charts": "^2.0.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1"
  }
}

Mintlify installe uniquement les dependencies. Les paquets listés uniquement dans devDependencies ou peerDependencies ne sont pas disponibles pour vos pages.

Commitez un lockfile

Installez vos dépendances et commitez le lockfile à côté de package.json.

pnpm install

npm install

Mintlify installe les versions exactes de votre lockfile. Il prend en charge pnpm-lock.yaml version 9 de pnpm et package-lock.json de npm. Les lockfiles Yarn et Bun ne sont pas pris en charge.

Activez les paquets

Ajoutez la clé packages à votre docs.json. Un objet vide active les paquets avec les paramètres par défaut.

docs.json

{
  "packages": {}
}

Importez un composant

Créez un composant dans votre dossier snippets qui importe depuis le paquet.

snippets/requests-chart.jsx

import { LineChart } from "@acme/charts";

const data = [
  { day: "Mon", requests: 120 },
  { day: "Tue", requests: 180 },
  { day: "Wed", requests: 150 },
];

export const RequestsChart = () => (
  <LineChart data={data} x="day" y="requests" height={240} />
);

Importez-le ensuite dans une page :

import { RequestsChart } from "/snippets/requests-chart.jsx";

<RequestsChart />

Déployez

Poussez vos modifications. Si un paquet ne peut pas être installé ou compilé, le déploiement échoue avec une erreur qui indique le paquet et le problème.

Pour prévisualiser en local, installez vos dépendances puis exécutez mint dev depuis le dossier contenant votre fichier docs.json.

Utiliser des composants de paquets

Vous pouvez également importer des composants directement depuis un paquet dans une page MDX :

import { Tooltip } from "@acme/ui";

<Tooltip content="Requests per day">Usage</Tooltip>

Placez les composants de paquets sur leurs propres lignes. Ils ne fonctionnent pas à l’intérieur d’un paragraphe, d’une cellule de tableau ou de texte en ligne.
Passez directement les chaînes, nombres et booléens comme props. Pour les fonctions, tableaux, objets ou props JSX, écrivez un composant wrapper dans votre dossier snippets, comme le graphique dans Ajouter un paquet, et passez-y les valeurs.
Le Markdown à l’intérieur d’un composant de paquet est rendu en HTML brut. Les composants Mintlify, tels que les callouts et les cartes, ne sont pas rendus à l’intérieur d’un composant de paquet.

Charger les styles des paquets

Les composants peuvent importer leur propre CSS. Pour charger une feuille de style qu’un paquet fournit séparément, ajoutez son chemin dans le paquet installé à packages.css :

docs.json

{
  "packages": {
    "css": ["@acme/ui/dist/styles.css"]
  }
}

Les paquets doivent fournir du CSS compilé. Mintlify n’exécute pas d’outils de build ni de plugins CSS sur le code des paquets, et ne prend pas en charge les modules CSS. Les feuilles de style des paquets ne peuvent pas charger de polices ni d’images depuis des URL distantes. Chargez plutôt les polices avec les paramètres de polices de votre site.

Envelopper les composants dans un provider

Si vos composants ont besoin d’un provider de thème ou de contexte, exportez un composant Provider depuis un snippet et définissez packages.provider sur son chemin :

docs.json

{
  "packages": {
    "provider": "/snippets/provider.jsx"
  }
}

snippets/provider.jsx

import { ThemeProvider } from "@acme/ui";

export const Provider = ({ children }) => <ThemeProvider>{children}</ThemeProvider>;

Le provider enveloppe chaque composant de paquet séparément. Les composants ne partagent pas d’état par son intermédiaire.

Installer depuis un autre registre

Les paquets sans scope s’installent depuis le registre npm public. Pour installer un scope depuis un registre différent, associez le scope à l’URL du registre dans packages.registries :

docs.json

{
  "packages": {
    "registries": {
      "@acme": "https://npm.acme.com/"
    }
  }
}

Le registre doit utiliser HTTPS sur le port par défaut et être accessible depuis l’internet public sans identifiants.

Limitations

Sources des dépendances : Les dépendances doivent être des versions du registre, des plages de versions ou des tags. Les URL Git, les chemins locaux et les alias file:, link:, workspace: et npm: ne sont pas pris en charge.
Scripts d’installation : Les paquets s’installent sans exécuter de scripts d’installation tels que postinstall. Les paquets qui en ont besoin, ou qui nécessitent des binaires natifs, ne fonctionnent pas.
Taille : La sortie des paquets d’un déploiement peut inclure jusqu’à 1 000 fichiers, 8 Mo par fichier, 40 Mo au total et 5 Mo compressés avec gzip. Les paquets qui chargent de grands ensembles de modules à l’exécution, comme les maps d’icônes dynamiques, peuvent dépasser la limite de fichiers.
Rendu côté serveur : Chaque composant doit être rendu en moins de trois secondes sur le serveur. Un composant qui échoue ou expire n’est rendu que dans le navigateur, il est donc absent du HTML de la page.
Recherche et IA : La recherche, l’assistant et les exports Markdown utilisent votre source MDX, et non le contenu rendu par un composant. Conservez le contenu de référence important dans le texte de votre MDX.
Éditeur web : L’aperçu de l’éditeur web n’affiche pas les composants de paquets.

Pour ne plus utiliser de paquets, supprimez packages de votre fichier docs.json et redéployez.

Prise en main

Créer du contenu

Gérer votre site

Agent

Assistant

Contenu adapté aux agents

Recherche et SEO

Documenter des API

Intégrations

Référence

Bibliothèques tierces

Ajouter un paquet

Utiliser des composants de paquets

Charger les styles des paquets

Envelopper les composants dans un provider

Installer depuis un autre registre

Limitations

​Ajouter un paquet

​Utiliser des composants de paquets

​Charger les styles des paquets

​Envelopper les composants dans un provider

​Installer depuis un autre registre

​Limitations

Ajouter un paquet

Utiliser des composants de paquets

Charger les styles des paquets

Envelopper les composants dans un provider

Installer depuis un autre registre

Limitations