pgr/docs/rules/710-TAURI.md

Profil Tauri 2

Rôle et applicabilité

Ce document possède les règles réutilisables propres à une application utilisant Tauri 2 comme host natif et orchestrateur d'intégration entre un host Rust et un frontend WebView.

Il complète 700-FRAMEWORKS.md et 510-RUST_CARGO.md. Les profils plateforme réellement ciblés, par exemple 610-ANDROID.md, restent applicables et possèdent leurs contraintes de SDK, packaging et smoke de plateforme.

Le profil est volontairement borné à Tauri 2. Une future génération incompatible du framework doit être réévaluée avant d'hériter automatiquement de ces règles.

Héritage Rust du host Tauri

Un host Tauri est un projet Rust/Cargo. Tauri ne crée aucune exception implicite aux règles Rust sélectionnées par le projet.

Pour un projet dont PGR gouverne la baseline, le host Tauri MUST appliquer le profil Rust/Cargo et les conventions Rust locales retenues exactement comme une autre crate ou application Rust du même projet : édition, lints, safety, erreurs, formatage, façade, chemins canoniques, imports, organisation des sources et audits applicables restent possédés par leur owner Rust.

Un exemple généré par create-tauri-app, une documentation de plugin ou une macro Tauri MAY employer un style différent ; il doit être adapté aux règles Rust du projet lorsqu'il est intégré. La présence de Tauri ne justifie donc pas à elle seule unwrap, expect, ?, un use non autorisé, un chemin interne non canonique ou un affaiblissement des lints si le profil Rust sélectionné les interdit.

Un projet Tauri existant ou imposé de l'extérieur MAY conserver d'autres conventions Rust. Ces différences doivent être traitées comme règles project-specific ou overrides explicites, pas comme un relâchement du profil Tauri général.

Composition avec le frontend

Tauri ne détermine pas à lui seul le framework frontend, le bundler, le langage de style ou le package manager du projet.

PGR MUST NOT imposer universellement Vite, TypeScript, Sass, Bootstrap, Tailwind CSS, npm, pnpm, yarn, Bun, WASM ou une arborescence frontend particulière uniquement parce que Tauri est utilisé.

Le frontend possède ses propres règles et peut être sélectionné par une skeleton specification ou par la baseline locale du projet. Le profil Tauri possède seulement le contrat d'intégration entre ce frontend et le host natif.

Pour les projets que l'organisation contrôle entièrement, une skeleton MAY choisir une stack frontend par défaut et un layout stable. Cette décision appartient au skeleton et aux futurs profils Web applicables, pas au présent owner Tauri.

WASM

WASM n'est pas une composante implicite d'un projet Tauri. Un package ou projet WASM SHOULD être traité comme une unité distincte appliquant ses propres profils Rust/Web/WASM, même s'il partage le même dépôt ou certaines crates avec une application Tauri.

Une application Tauri MAY consommer explicitement un artefact WASM lorsqu'un besoin architectural réel le justifie. Cette composition doit alors être documentée comme telle ; elle ne transforme pas les règles WASM en règles Tauri et ne justifie pas de placer systématiquement une chaîne WASM dans les hooks Tauri.

Layout et fichiers possédés par Tauri

PGR MUST NOT imposer universellement un répertoire src-tauri/ ni recopier le layout de create-tauri-app. Le projet peut utiliser le layout standard de Tauri ou une intégration différente lorsque la toolchain la supporte clairement.

Les éléments suivants appartiennent néanmoins au scope Tauri lorsqu'ils existent :

• le manifeste Cargo du host natif ;
• l'intégration build-time Tauri, généralement via tauri-build ;
• la configuration Tauri supportée par la version du framework, par exemple tauri.conf.json ;
• les capability files et permissions Tauri ;
• les icônes, ressources ou métadonnées de bundle référencées par la configuration ;
• les projets ou fichiers de plateforme produits/consommés par la toolchain Tauri.

Leur emplacement exact reste une décision du projet ou du skeleton retenu tant qu'il est supporté par la toolchain.

Convention renforcée pour les projets contrôlés

Le contrat universel ci-dessus reste compatible avec des projets Tauri imposés de l'extérieur. Pour un nouveau projet Tauri contrôlé par l'organisation qui sélectionne le profil strict PGR, les conventions suivantes forment en revanche la baseline recommandée et ne doivent pas être abandonnées sans raison documentée.

Le host SHOULD être une crate Cargo mixte directement lisible, sans couche src-tauri/ ajoutée uniquement pour reproduire create-tauri-app. Le layout recommandé est :

<tauri-crate>/
├── Cargo.toml
├── build.rs
├── package.json
├── tsconfig.json
├── tauri.conf.json
├── capabilities/
├── src/
└── frontend/

Un fichier comme vite.config.ts appartient également à la racine lorsque Vite est le bundler sélectionné. Un projet externe MAY conserver src-tauri/ ou une autre organisation lorsque cette structure est imposée ou qu'une migration n'apporte pas de valeur suffisante.

Dans le host Rust, le package mixte lib + bin constitue l'exception framework explicite à la séparation générale définie par 510-RUST_CARGO.md. Pour une nouvelle baseline Tauri contrôlée :

• le package SHOULD déclarer explicitement une cible bibliothèque et une cible binaire ;
• leurs noms MUST être distincts même après la normalisation Cargo usuelle des tirets en underscores ; un modèle valide est package/bin project-feature-desk et lib project_feature_desk_lib ;
• src/lib.rs SHOULD rester une façade de modules/réexports et porter l'accès à la fonctionnalité applicative réutilisable ;
• src/main.rs SHOULD rester un launcher mince vers une fonction publique de la bibliothèque applicative ; il MAY posséder le verrou/single-instance, les arguments strictement process et le bootstrap exécutable qui ne peut pas appartenir à la bibliothèque ;
• src/tauri.rs SHOULD posséder l'assemblage Tauri et les wrappers #[tauri::command], qui délèguent aux modules propriétaires plutôt que porter la logique métier ;
• une fenêtre ou responsabilité UI non triviale SHOULD posséder un module cohérent, avec sous-modules si nécessaire ; les helpers réellement partagés entre plusieurs fenêtres/responsabilités SHOULD être déplacés dans des modules communs dédiés ;
• un préfixe local comme tw_ MAY être utilisé pour identifier les modules de fenêtres, mais PGR n'impose pas ce préfixe à tous les projets.

Lorsque le workspace possède une crate de logging/tracing commune, le host Tauri l'utilise pour initialiser le runtime de diagnostics. Un plugin Tauri de tracing sert alors d'adapter à la frontière desktop/mobile ; il ne remplace pas l'owner Rust de tracing-subscriber, des sinks ou du lifecycle de logging.

Lorsque le frontend sélectionné est TypeScript, les structures, énumérations et DTO Rust possédés par le host et partagés avec le frontend MUST utiliser TS-RS comme source de génération dans le profil strict, sauf incompatibilité technique explicitement documentée. Le contrat Rust reste la source de vérité ; les bindings générés ne sont pas modifiés manuellement et SHOULD rester hors Git lorsqu'ils sont entièrement reproductibles. Le skeleton MAY normaliser leur sortie sous frontend/ts/bindings/.

Pour les projets contrôlés, frontend/ est le répertoire recommandé pour les sources Web versionnées. Vite + TypeScript + Sass constitue la stack candidate par défaut et Bootstrap est la baseline de présentation privilégiée lorsque le projet a besoin d'un framework CSS généraliste. Tailwind CSS n'est pas interdit par le profil Tauri, mais il n'est pas le choix PGR par défaut et son adoption demande une décision explicite du projet. Ces choix restent possédés par le futur skeleton et les profils Web correspondants.

L'intégration d'un plugin SHOULD préférer les étapes explicites décrites par sa documentation — dépendance Cargo, initialisation Rust, package frontend et capabilities nécessaires — afin que chaque modification reste visible et revue. cargo tauri add MAY être utilisé lorsque ce raccourci apporte une vraie valeur, mais il n'est pas la voie canonique imposée aux projets contrôlés.

WASM reste normalement une unité séparée de la crate Tauri. Une adaptation WASM réutilisable SHOULD donc posséder sa propre crate/package et ses propres profils ; elle n'est intégrée au host Tauri que lorsqu'une composition architecturale explicite l'exige.

Ownership du build et hooks frontend

Lorsqu'une validation concerne l'intégration Tauri complète, le CLI Tauri est l'owner de l'orchestration.

Si beforeDevCommand, beforeBuildCommand ou un hook Tauri équivalent est configuré, la gate d'intégration SHOULD invoquer le CLI Tauri afin que ce hook soit exécuté dans le contexte prévu.

Ainsi :

cargo check / cargo clippy
→ preuve Rust ciblée

frontend build/test direct
→ preuve frontend ciblée

Tauri CLI dev/build
→ preuve d'orchestration Tauri + hooks correspondants

Un projet MUST NOT considérer npm run build, cargo build ou une autre sous-commande isolée comme équivalente à un build Tauri lorsque la propriété à valider dépend des hooks, de frontendDist, des capabilities, du contexte Tauri ou du bundling.

Le CLI MAY être invoqué via cargo tauri, un script du package manager frontend ou une autre forme officiellement supportée. PGR n'impose pas le package manager qui sert de lanceur.

devUrl, frontendDist et sorties frontend

devUrl et frontendDist doivent pointer vers les entrées/sorties réellement possédées par la chaîne frontend du projet.

PGR ne fixe ni port, ni nom de répertoire de distribution, ni profondeur relative universelle.

Le répertoire produit par le frontend est un artefact de build lorsqu'il est reproductible ; il SHOULD rester hors du source control sauf besoin explicite contraire. La configuration Tauri qui le référence reste, elle, source durable.

Version produit

Lorsque l'application Tauri appartient au même release train que le projet, VERSION reste la version canonique exacte de cette unité de release. Les champs de version de Tauri et du frontend ne sont toutefois pas obligés de suivre chaque prerelease ou fix : ils sont classés selon 200-GOVERNANCE.md.

Tauri 2 accepte une version applicative explicite dans tauri.conf.json et l'utilise pour les métadonnées/bundles. Si ce champ est absent, Tauri peut utiliser la version du package Cargo du host. PGR MUST NOT imposer l'une de ces deux formes uniquement pour réduire le nombre de fichiers modifiés.

Pour un projet contrôlé qui conserve une version explicite dans tauri.conf.json, la politique recommandée lorsque les prereleases ne sont pas distribuées comme produits installables distincts est MIRROR-STABLE : le champ porte la cible X.Y.Z de la version en cours de développement, est fixé ou vérifié à l'ouverture de cette cible et reste stable pendant ses alpha.*, beta.*, rc.* et fixes. La promotion stable vérifie la cohérence sans provoquer de réécriture cérémonielle si la valeur est déjà correcte.

Si le projet distribue réellement des bundles prerelease qui doivent être identifiables séparément, tauri.conf.json > version MAY devenir MIRROR-EXACT ou suivre des jalons de packaging explicitement documentés. Le choix dépend du contrat de distribution, pas d'une préférence PGR pour l'omission du champ.

Pour un package.json frontend privé appartenant à la même application, une propriété version conservée SHOULD de même être classée MIRROR-STABLE par défaut : elle peut porter X.Y.Z pendant tout le développement de cette release sans suivre chaque tranche. Si le package frontend est publié ou versionné indépendamment, il possède alors sa propre unité/version et cette règle ne s'applique plus.

La chaîne de version d'un projet contrôlé peut donc être, par exemple :

VERSION                         = X.Y.Z-alpha.N.fix.M   # CANONICAL
workspace.package.version       = X.Y.Z-alpha.N.fix.M   # MIRROR-EXACT si le workspace l'a choisi
tauri.conf.json version         = X.Y.Z                 # MIRROR-STABLE
package.json version            = X.Y.Z                 # MIRROR-STABLE si conservée

Cette classification évite de réécrire package.json et tauri.conf.json à chaque delta tout en conservant des champs de version utiles et lisibles. Elle remplace explicitement les conventions historiques KSP/Games qui préféraient omettre la version Tauri comme solution générale au churn.

Les numéros propres aux plateformes, par exemple Android versionCode, restent possédés par le profil plateforme concerné et ne sont pas assimilés au SemVer produit.

Capabilities, permissions et frontière WebView/native

Les capability files et permissions Tauri sont du source de sécurité et SHOULD être versionnés lorsqu'ils définissent intentionnellement la surface exposée au frontend.

Le projet SHOULD accorder uniquement les permissions nécessaires aux fenêtres/webviews concernées. Ajouter un plugin ou une commande native ne justifie pas automatiquement une capability globale plus large.

Les schémas générés référencés par les capability files servent à l'outillage et à la validation de configuration ; ils ne deviennent pas pour autant la source normative de la politique de permissions.

Toute permission distante, origine distante ou extension de scope sensible doit être explicitement justifiée et validée comme frontière de sécurité.

Plugins

PGR ne définit aucun catalogue de plugins Tauri obligatoires et ne rend pas cargo tauri add obligatoire.

Les pages officielles des plugins peuvent décrire à la fois une commande d'ajout automatique et les étapes explicites correspondantes côté Cargo, initialisation Rust et bindings frontend. Un projet MAY préférer appliquer manuellement ces étapes afin que les modifications de Cargo.toml, du manifeste frontend et du code d'initialisation restent directement contrôlées et revues.

Si une commande de commodité telle que tauri add est utilisée, les fichiers qu'elle modifie MUST être relus comme toute autre génération avant validation. Le projet ne doit installer que les côtés réellement nécessaires du plugin : dépendance Rust, bindings frontend, capabilities/permissions ou configuration associée selon le cas.

CSP, fenêtres et bundles

CSP, nombre de fenêtres, labels, tailles, ports, bundle.active, targets de bundle, icônes et ressources restent des décisions du produit ou de la plateforme tant qu'aucun invariant plus général ne les impose.

Une règle locale MAY renforcer ces choix. Elle ne doit pas être remontée dans le profil Tauri uniquement parce qu'elle apparaît dans plusieurs applications d'un même projet.

Artefacts générés et projets mobiles

Les dépendances frontend téléchargées et sorties de build reproductibles, telles que node_modules/ ou le frontendDist, SHOULD rester hors Git.

PGR MUST NOT appliquer en revanche une exclusion universelle de tout répertoire gen/. Tauri peut générer des projets de plateforme qui deviennent ensuite le lieu de personnalisations Android/iOS intentionnelles. Le projet doit classifier chaque sous-arbre : reproductible/transitoire, configuration durable ou généré modifié volontairement.

Un POC Tauri mobile non concluant pour un produit particulier ne constitue pas une preuve que Tauri Android/iOS est inadapté à tous les autres projets. Le support mobile doit être jugé selon le besoin, les ABI, plugins, intégrations natives et gates plateforme du projet concerné.

Les secrets de signature, keystores, credentials et fichiers locaux restent hors Git conformément aux règles générales et aux profils plateforme applicables.

Validation proportionnée

Scope modifié	Preuve Tauri normalement pertinente	Ce que cette preuve ne remplace pas
backend Rust uniquement	gates Rust/Cargo sélectionnées	frontend, hooks, WebView ou packaging
frontend uniquement	build/tests/smoke du frontend selon son owner	host natif ou packaging Tauri
hooks, config, capabilities, IPC ou intégration	tauri dev ou équivalent + smoke ciblé	package release de plateforme
bundling, ressources ou version packagée	tauri build ou équivalent + inspection/smoke de l'artefact	exigences d'un store ou d'une plateforme non exercée
Android/iOS	commande mobile Tauri applicable + gates du profil plateforme concerné	autres plateformes

La syntaxe exacte de la commande dépend du lanceur choisi (cargo, npm, pnpm, etc.) et de la plateforme. Le delta/plan du projet doit fournir la commande concrète.

Un cargo check direct MAY rester utile pour une modification Rust ciblée, mais il ne constitue pas un smoke Tauri complet. Inversement, un full tauri build n'est pas requis lorsqu'aucune propriété d'intégration ou de packaging n'a été invalidée.

Ce que le profil n'impose pas

Ce profil ne crée pas :

• de tauri.conf.json universel ;
• de port de développement par défaut PGR ;
• de frontend Vite/TypeScript/Sass/Bootstrap obligatoire ;
• de frontend WASM implicite ;
• de plugin obligatoire ;
• de nombre ou taille de fenêtres ;
• de politique de bundle unique ;
• de layout universel imposé aux projets externes ; la convention stricte des projets contrôlés est définie séparément ci-dessus ;
• de version exacte de Tauri, tauri-build ou du CLI.

Ces décisions appartiennent au projet, à un profil plus spécifique ou à une skeleton specification seulement lorsqu'une valeur réutilisable est réellement démontrée.