Next.js

Ce guide vous guidera dans la création de votre première application Tauri en utilisant le framework React Next.js.

info

Before we continue, make sure you have completed the prerequisites to have a working development environment.

Tauri est un framework pour développer des applications de bureau avec n'importe quel framework frontend et un backend en Rust. Chaque application se compose de deux parties :

1. Le binaire en Rust qui crée les fenêtres et expose les fonctionnalités natives à ces fenêtres
2. Le framework frontend de votre choix qui crée l'interface utilisateur dans la fenêtre

Dans ce qui suit, nous allons d'abord configurer le frontend, puis mettre en place le projet Rust et enfin vous montrer comment communiquer entre les deux.

Voici un aperçu de ce que nous allons construire :

Créer le Frontend

Next.js est un framework React qui est fourni avec les capacités de rendu côté serveur (SSR) et Static-Site Generation (SSG). Pour faire fonctionner Next.js avec Tauri, nous allons utiliser le mode SSG car il ne génère que des fichiers statiques pouvant être inclus dans le binaire final.

Next.js est livré avec un utilitaire d'échafaudage similaire à create-tauri-app qui peut configurer rapidement un nouveau projet à partir de nombreux modèles prédéfinis. For this guide, we will use the suggested default for all questions, including TypeScript support and the new App Router feature stabilized in v13.4. In case you use the the old routes/ directory instead or on top of the app/ directory, you still need to change the config as explained in the Next.js Static Exports section but the way you use Tauri specific JS APIs will be different than described below.

npm

npx create-next-app@latest --use-npm

Yarn

yarn create next-app --use-yarn

pnpm

pnpm create next-app --use-pnpm

1. Project name
   This will be the name of your project. It corresponds to the name of the folder this utility will create but has otherwise no effect on your app. Vous pouvez utiliser n'importe quel nom que vous voulez ici.

Next.js Static Exports

Because Tauri does not have a Node.js runtime you must set Next.js to SSG/SPA mode. This will typically result in faster page loads but also has a few caveats to be aware of, therefore we recommend to carefully read through Next.js' official docs on Static Exports.

These docs also show one required configuration change we will always have to change for a Tauri + Next.js app. To do this, edit the next.config.js file in the project's root directory and add the following:

next.config.js

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'export',
}

module.exports = nextConfig

This will change the behavior of the next build to produce an out/ folder containing the HTML/CSS/JS assets for your application instead of writing them to a .next/ directory specific to Next.js' runtime.

There are a few more possible configuration options, so make sure to read through the Static Exports docs as mentioned above and adapt the configuration file according to the needs of your project.

Créer le projet Rust

Au cœur de chaque application Tauri se trouve un binaire Rust qui gère les fenêtres, la webview et les appels au système d'exploitation par le biais d'une crate Rust appelé tauri. Ce projet est géré par Cargo, le gestionnaire de paquets officiel et l'outil de construction propulsé par Rust.

Notre CLI Tauri utilise Cargo sous le capot, de sorte que vous avez rarement besoin d'interagir directement avec lui. Cargo dispose de nombreuses autres fonctionnalités utiles qui ne sont pas exposées par notre CLI, comme les tests, le linting et le formatage, alors veuillez vous référer à leur documentation officielle pour en savoir plus.

Installer Tauri CLI

Si vous n'avez pas encore installé le CLI Tauri, vous pouvez le faire avec l'une des commandes ci-dessous. Vous n'êtes pas sûr de savoir quoi utiliser ? Consultez la section dédiée dans la FAQ.

npm

npm install --save-dev @tauri-apps/cli@">1.0.0"

For npm to detect Tauri correctly you need to add it to the "scripts" section in your package.json file:

package.json

"scripts": {
  "tauri": "tauri"
}

Yarn

yarn add -D @tauri-apps/cli@^1.0.0

pnpm

pnpm add -D @tauri-apps/cli@1

Bun

bun add -D @tauri-apps/cli@1.0.0

Cargo

cargo install tauri-cli --version "^1.0.0"

Pour échafauder un projet Rust minimal qui est pré-configuré pour utiliser Tauri, ouvrez un terminal et exécutez la commande suivante :

npm

npm run tauri init

Yarn

yarn tauri init

pnpm

pnpm tauri init

Cargo

cargo tauri init

Il vous guidera à travers une série de questions :

1. Quel est le nom de votre application ?
   Ce sera le nom de votre paquet final et le nom du programme dans votre OS. Vous pouvez utiliser n'importe quel nom que vous voulez ici.


2. Quel doit être le nom de la fenêtre ?
   Ce sera le nom de la fenêtre principale par défaut. Vous pouvez utiliser n'importe quel nom que vous voulez ici.


3. Où sont vos ressources web (HTML/CSS/JS) situés par rapport au fichier <current dir>/src-tauri/tauri.conf.json qui sera créé ?
   Ce chemin est celui que Tauri chargera votre resources frontend quand vous compiler en mode production.
   Use ../out for this value.


4. Quelle est l'URL de votre serveur de développement
   Celle - ci peut être soit une URL où est chemin fichier que Tauri chargera pendant le development.
   Use http://localhost:3000 for this value.


5. Quelle est votre commande de développement frontend ?
   Celle ci est la commande utilisée pour démarrer votre serveur de développement frontend.
   Use npm run dev for this value (make sure to adapt this to use the package manager of your choice).


6. Quelle est votre commande de build frontend ?
   Celle ci est la commande utilisée pour construire vos fichiers frontend pour la production.
   Use npm run build for this value (make sure to adapt this to use the package manager of your choice).

info

Si vous êtes familier avec Rust, vous remarquerez que tauri init ressemble beaucoup à init cargo. Vous pouvez simplement utiliser cargo init et ajouter les dépendances Tauri nécessaires si vous préférez une installation entièrement manuelle.

La commande tauri init génère un dossier appelé src-tauri. C'est une convention pour les applications Tauri de placer tous les fichiers liés au cœur de l'application dans ce dossier. Passons rapidement à travers le contenu de ce dossier :

• cargo.toml
  Fichier manifeste de Cargo. Vous pouvez déclarer les crates Rust dont votre application dépend, les métadonnées de votre application, et bien plus encore. Pour la référence complète, voir Format de manifeste de Cargo.

• tauri.conf.json
  Ce fichier vous permet de configurer et de personnaliser des aspects de votre application Tauri du nom de votre application à la liste des API autorisées. Voir la configuration de l'API de Tauri pour la liste complète des options supportées et des explications approfondies pour chacune d'entre elles.

• src/main.rs
  C'est le point d'entrée de votre programme Rust et l'endroit où nous démarrons Tauri. Vous y trouverez deux sections :

  src/main.rs

   #![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
  
  fn main() {
  tauri::Builder::default()
     .run(tauri::generate_context!())
     .expect("error while running tauri application");
  }

  The line beginning with the cfg! ayant qu'un seul but : elle désactive la fenêtre d'invite de commande qui s'afficherait normalement sur Windows si vous exécutez une application groupée. Si vous êtes sous Windows, essayez de le commenter et de voir ce qui se passe.

  La fonction main est le point d'entrée et la première fonction qui est appelée lorsque votre programme s'exécute.

• icônes
  Il y a de fortes chances que vous souhaitiez une icône élégante pour votre application ! Pour vous permettre de démarrer rapidement, nous avons inclus un ensemble d'icônes par défaut. Vous devez les changer avant de publier votre application. Pour en savoir plus sur les différents formats d'icônes, consultez le tutoriels sur les icônes de Tauri.

Maintenant que nous avons préparé notre Frontend et initialisé le projet Rust, vous êtes presque prêt à lancé votre application. Votre fichier tauri.conf.json devrait ressembler à ceci :

src-tauri/tauri.conf.json

{
  "build": {
    "beforeBuildCommand": "npm run build",
    "beforeDevCommand": "npm run dev",
    "devPath": "http://localhost:3000",
    "distDir": "../out"
  },

Et c'est tout! Maintenant, vous pouvez exécuter la commande suivante dans votre terminal pour lancer de votre application en mode développement:

npm

npm run tauri dev

Yarn

yarn tauri dev

pnpm

pnpm tauri dev

bun

bunx tauri dev

Cargo

cargo tauri dev

Invoquer des commandes

Tauri vous permet d'améliorer votre frontend avec des capacités natives. Nous appelons ces Commandes, essentiellement des fonctions Rust que vous pouvez appeler depuis votre JavaScript en frontend. Cela vous permet de gérer des traitements ou des appels plus lourds via l'OS dans un code Rust beaucoup plus performant.

Faisons un exemple simple :

src-tauri/src/main.rs

#[tauri::command]
fn greet(name: &str) -> String {
   format!("Hello, {}!", name)
}

Une commande est comme n'importe quelle fonction Rust normale, avec l'ajout de la macro d'attribut #[tauri::command] qui permet à votre fonction de communiquer avec le contexte JavaScript.

Enfin, nous devons également parler à Tauri de notre commande nouvellement créée afin qu'elle puisse effectuer les appels en conséquence. Ceci est fait avec la combinaison de la fonction .invoke_handler() et de la macro generate_handler![] que vous pouvez voir ci-dessous :

src-tauri/src/main.rs

fn main() {
  tauri::Builder::default()
    .invoke_handler(tauri::generate_handler![greet])
    .run(tauri::generate_context!())
    .expect("error while running tauri application");
}

Maintenant vous êtes prêt à appeler votre commande depuis le frontend !

Pour appeler notre commande nouvellement créée, nous utiliserons la bibliothèque JavaScript @tauri-apps/api. Il offre des moyens d'accéder à des fonctionnalités natives telles que le système de fenêtrage, de fichiers, etc., à travers des abstractions JavaScript. Vous pourrez l'installer à l'aide du gestionnaire de paquets de votre choix:

npm

npm install @tauri-apps/api@">1.0.0"

Yarn

yarn add @tauri-apps/api@^1.0.0

pnpm

pnpm add @tauri-apps/api@1

Bun

bun add @tauri-apps/api@1.0.0

One important thing to note is that all of Tauri's JS APIs require access to browser-only APIs which means they can only be used in Client Components. If you don't need Server Components you can add 'use client' at the very top of the app/page.tsx file, in this guide however, we will create a separate component so that we don't have to convert the whole app.

app/greet.tsx

'use client'

import { useEffect } from 'react'
import { invoke } from '@tauri-apps/api/tauri'

export default function Greet() {
  useEffect(() => {
    invoke<string>('greet', { name: 'Next.js' })
      .then(console.log)
      .catch(console.error)
  }, [])

  // Necessary because we will have to use Greet as a component later.
  return <></>
}

Now we will use this component in the default Home component in app/page.tsx. Note that it must be in the actual component tree and can't be a simple function call as long as the parent (in this case the Home component) is a Server Component.

app/page.tsx

// ...
import Greet from './greet'

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <Greet />
      ...
    </main>
  )
}

:::astuce

Si vous voulez en savoir plus sur la communication entre Rust et JavaScript, veuillez lire le Tauri Inter-Process Communication guide.

:::