Déployer SPFx dans le catalogue d'applications

1Étape 1 : Vérifier la chaîne d'outils du projet

Depuis SPFx 1.22, les nouveaux projets utilisent Heft à la place de gulp. Avec SPFx 1.24, sorti le 28 octobre 2026, la chaîne gulp n'est plus prise en charge.

Ouvrez package.json et lisez les scripts. Un projet 1.24 standard définit build comme heft test --clean --production && heft package-solution --production.

Un projet resté en 1.21 ou avant utilise encore gulp bundle --ship puis gulp package-solution --ship. Avec Heft, l'option --ship devient --production.

# Affiche les scripts npm définis dans le projet
npm pkg get scripts

Vérification : Le script build appelle heft et non gulp.

2Étape 2 : Configurer package-solution.json

Le fichier config/package-solution.json décrit le paquet. Le champ solution.version suit le format à quatre nombres 1.0.0.0.

includeClientSideAssets: true embarque le JavaScript et le CSS dans le .sppkg. SharePoint les sert ensuite depuis le catalogue ou le CDN Office 365 s'il est activé.

skipFeatureDeployment: true autorise le déploiement à l'échelle du tenant. L'administrateur peut alors cocher « Activer cette application et l'ajouter à tous les sites ». Dans ce cas, les définitions du Feature Framework (listes, champs) sont ignorées.

{
  "$schema": "https://developer.microsoft.com/json-schemas/spfx-build/package-solution.schema.json",
  "solution": {
    "name": "mon-webpart-client-side-solution",
    "id": "<GUID de la solution>",
    "version": "1.0.0.0",
    "includeClientSideAssets": true,
    "skipFeatureDeployment": true,
    "isDomainIsolated": false
  },
  "paths": {
    "zippedPackage": "solution/mon-webpart.sppkg"
  }
}

Vérification : Le fichier contient un id stable, une version et la valeur voulue pour skipFeatureDeployment.

3Étape 3 : Déclarer les autorisations d'API

Si la solution appelle Microsoft Graph ou une API protégée par Entra ID, ajoutez webApiPermissionRequests dans l'objet solution.

Une entrée par couple ressource / étendue. La valeur de resource est le nom d'affichage de l'application Entra ID, pas son objectId : un objectId provoque une erreur à l'approbation.

Le déploiement crée des demandes en attente. Approuvées ou non, la solution reste déployable : le code ne doit jamais supposer que l'accès est accordé.

"webApiPermissionRequests": [
  { "resource": "Microsoft Graph", "scope": "Calendars.Read" },
  { "resource": "Microsoft Graph", "scope": "User.ReadBasic.All" }
]

Vérification : Chaque étendue nécessaire figure dans une entrée distincte.

4Étape 4 : Construire le paquet de production

Arrêtez le serveur local (heft start) puis lancez le build. Le script exécute les tests, compile en mode production et empaquette la solution.

Le .sppkg est écrit dans sharepoint/solution, au nom défini par paths.zippedPackage. Le contenu brut est visible dans sharepoint/solution/debug.

npm run build

# Équivalent explicite décrit dans le tutoriel Microsoft
npx heft build --production
npx heft package-solution --production

ls sharepoint/solution/*.sppkg

Vérification : Un fichier .sppkg daté de l'instant présent existe dans sharepoint/solution.

5Étape 5 : Choisir le catalogue : tenant ou site

Le catalogue du tenant rend la solution installable dans toutes les collections de sites. On l'ouvre depuis le centre d'administration SharePoint : Plus de fonctionnalités, puis Ouvrir sous Applications.

Le catalogue de collection de sites limite la solution à ce seul site. Un administrateur l'active avec Add-SPOSiteCollectionAppCatalog, Add-PnPSiteCollectionAppCatalog ou m365 spo site appcatalog add. Un catalogue du tenant doit déjà exister.

Dans un catalogue de site, la case « ajouter à tous les sites » ne rend la solution disponible que dans cette collection de sites.

Connect-SPOService -Url https://contoso-admin.sharepoint.com
Add-SPOSiteCollectionAppCatalog -Site https://contoso.sharepoint.com/sites/marketing

Vérification : La bibliothèque « Apps for SharePoint » apparaît dans le site visé, ou la page Gérer les applications s'ouvre pour le tenant.

6Étape 6 : Déposer et activer la solution

Sur la page Gérer les applications, cliquez sur Charger et choisissez le .sppkg. Le panneau « Activer l'application » s'affiche.

Si skipFeatureDeployment vaut true, cochez « Activer cette application et l'ajouter à tous les sites » pour un déploiement global. Sinon, chaque propriétaire de site l'ajoute via Ajouter une application.

En ligne de commande, la CLI for Microsoft 365 sépare l'ajout et le déploiement. PnP PowerShell fait les deux avec Add-PnPApp -Publish.

m365 login
m365 spo app add --filePath ./sharepoint/solution/mon-webpart.sppkg --overwrite
m365 spo app deploy --name mon-webpart.sppkg --skipFeatureDeployment

# Équivalent PnP PowerShell
# Add-PnPApp -Path ./sharepoint/solution/mon-webpart.sppkg -Overwrite -Publish -SkipFeatureDeployment

Vérification : La colonne « App Package Error Message » est vide et le composant apparaît dans la boîte à outils d'une page.

7Étape 7 : Approuver les autorisations d'API

Ouvrez la page API access du centre d'administration SharePoint. Sélectionnez chaque demande en attente, puis Approuver.

Les autorisations déléguées sont accordées au principal « SharePoint Online Client Extensibility Web Application Principal ». Elles valent pour toutes les solutions SPFx du tenant, pas seulement pour celle qui les a demandées.

Pour Microsoft Graph, il faut un Administrateur général. Pour une API tierce inscrite dans le tenant, le rôle Administrateur d'applications suffit.

m365 spo serviceprincipal permissionrequest list
m365 spo serviceprincipal permissionrequest approve --id <id-de-la-demande>
m365 spo serviceprincipal grant list

Vérification : La demande passe dans la liste des demandes approuvées et l'appel à l'API répond sans erreur 403.

8Étape 8 : Publier une nouvelle version

Incrémentez solution.version dans package-solution.json (par exemple 1.0.0.0 vers 1.1.0.0), gardez le même id, reconstruisez puis redéposez le .sppkg en remplaçant l'existant.

Pour une solution déployée sur tout le tenant, le nouveau paquet met à jour toutes les instances. Pour une solution installée site par site, appliquez la mise à jour avec m365 spo app upgrade ou Update-PnPApp.

Si la solution provisionne des éléments via le Feature Framework, incrémentez aussi la version de la feature et déclarez des upgradeActions.

npm run build
m365 spo app add --filePath ./sharepoint/solution/mon-webpart.sppkg --overwrite
m365 spo app deploy --name mon-webpart.sppkg
m365 spo app upgrade --id <id-de-l-app> --siteUrl https://contoso.sharepoint.com/sites/marketing

Vérification : Le catalogue affiche le nouveau numéro de version et la page charge les nouveaux fichiers.