Passer au contenu principal

Créer une application

Ce guide offre un aperçu de la configuration initiale, en abordant le frontend, la base de données et le service API. Nous allons créer une nouvelle application fullstack de manière rapide et pratique.

Introduction​

Bien que la plateforme soit polyglotte et prenne en charge plusieurs langages de programmation, nous nous concentrerons exclusivement sur l'utilisation de JavaScript dans ce tutoriel. En conséquence, nous créerons une application pratique composée d'un formulaire affiché dans une fenêtre modale (pop-up) avec la fonctionnalité d'exportation de données vers PDF.

Prérequis​

Avant de commencer, assurez-vous de disposer de :

  • La plateforme Netuno préalablement installée sur votre machine. En cas de doute sur cette étape, consultez le guide Installation de la plateforme.

  • Un accès au terminal ou à l'invite de commande de l'environnement de développement.

Créer une nouvelle application​

Suivez les instructions ci-dessous pour initialiser votre nouvelle application :

Ouvrez le terminal et naviguez jusqu'au dossier racine où Netuno a été installé.

Exécutez la commande de création de l'application :

./netuno app

Création avec paramètre​

Il est possible de définir le nom de l'application directement lors de l'exécution de la commande, par exemple :

./netuno app name=mon_application
Bonnes pratiques de nommage

Lors de la définition du nom de votre application, évitez d'utiliser des espaces, des accents ou des caractères spéciaux. Préférez l'utilisation de lettres minuscules séparées par des tirets ou des underscores (exemple : app-ventes ou gestion_rh) pour maintenir la compatibilité avec les URL et les dossiers du système.

Configuration initiale​

L'assistant en ligne de commande posera quelques questions pour configurer votre projet. Indiquez :

  • Nom de l'application : L'identifiant de votre projet.
  • Type de base de données : Le système de gestion de base de données qui sera utilisé.
  • Langue : La langue par défaut de l'interface de votre application.
Conseils et bonnes pratiques

Recommandation de base de données pour les débutants

Pendant le pas-à-pas, lorsqu'il vous sera demandé le type de base de données, nous recommandons de choisir l'option H2 Database.

H2 Database est une base de données embarquée déjà intégrée au serveur Netuno. Le grand avantage est qu'elle ne nécessite ni installation ni configuration de serveurs externes (comme PostgreSQL ou MySQL), ce qui rend les développements initiaux et les tests beaucoup plus pratiques et rapides.

Commande pour démarrer le serveur​

Après avoir créé votre nouvelle application, démarrez le serveur de la plateforme Netuno. Cela rendra votre projet accessible dans le navigateur et prêt pour le développement continu.

Exécutez la commande ci-dessous dans votre terminal et attendez l'initialisation.

./netuno server app=mon_application

En passant le paramètre app=mon_application, le serveur comprend que ce sera l'application par défaut à exécuter dans cette instance. Une fois le serveur en cours d'exécution, vous pouvez déjà commencer à modifier votre projet.

Tous les fichiers et codes source de votre application sont stockés et organisés dans le dossier 📂 apps/monapp.

Identifiants d'accès (Backoffice)

Lors de la première connexion à l'interface d'administration Backoffice de votre application, le système demandera une authentification. Pour les environnements de développement locaux, utilisez les identifiants par défaut suivants :

Utilisateur : dev

Mot de passe : dev

Nous recommandons de modifier ces identifiants lorsque vous déplacez votre application vers un environnement de production.

Éditeur de code​

Pour garantir la meilleure expérience de développement, nous suggérons l'utilisation d'éditeurs de code modernes, légers et disposant d'un bon écosystème d'extensions.

Si vous n'avez pas encore d'éditeur préféré, nous recommandons les options gratuites suivantes, largement utilisées par la communauté :

Remarque : Si vous préférez des outils plus robustes et que cela ne vous dérange pas d'investir dans des licences, WebStorm de JetBrains est une excellente option premium.

Ouvrez le dossier de l'application dans votre éditeur :

  • 📂 apps/mon_application

Tous les fichiers de l'application sont stockés et organisés dans ce dossier. Tout le développement, la création de routes, les logiques de base de données et les interfaces visuelles se dérouleront dans ce dossier.

Comprendre l'architecture

Pour savoir exactement où créer chaque type de fichier et comment Netuno organise le backend et le frontend, nous recommandons la lecture de la documentation détaillée sur la structure des dossiers de l'application :

Consultez le guide : Dossiers de l'application

Résumé des étapes​

Avec les connaissances initiales de Netuno consolidées, nous appliquerons ces concepts en pratique en créant une fonctionnalité complète, du début à la fin.

L'objectif pratique est d'ajouter deux nouveaux composants interactifs dans l'interface :

  • Un bouton chargé de charger et d'afficher le formulaire de clients dans une fenêtre flottante (Modale).
  • Un bouton dédié à la génération et à l'exportation de la liste des clients enregistrés dans un fichier PDF.

Pour atteindre ce résultat avec organisation et clarté, nous divisons le développement en une séquence logique d'étapes. Nous suivrons ce plan :

  • Cartographie de l'interface : Analyser la structure des dossiers de l'application pour localiser où le HTML principal du tableau de bord est défini.

  • Intégration avec React : Configurer et ajouter la base des deux nouveaux boutons en utilisant le framework React dans le frontend.

  • Logique de la modale : Construire et programmer le comportement du bouton pour ouvrir correctement le formulaire de clients.

  • Interface d'exportation : Construire et positionner le bouton qui déclenchera le téléchargement du fichier PDF dans l'interface.

  • Développement du service (API) : Programmer le backend en créant le service qui effectuera la lecture des données et la génération dynamique du fichier PDF contenant la liste des clients.

Commençons !

Modèle de tableau de bord​

Naviguez jusqu'au dossier server/templates et ouvrez le fichier responsable de fournir le HTML de l'écran du tableau de bord.

server/templates/dashboard.html

En explorant le code du fichier dashboard.html, faites défiler jusqu'à la fin de la page. Vous trouverez un élément <div> isolé. C'est exactement à cet endroit que la plateforme Netuno « injecte » et initialise toute l'interface interactive construite en React.

server/templates/dashboard.html
...
<div id="app-dashboard"></div>

Bien que le squelette HTML se trouve dans le dossier server/templates, le développement réel de l'interface et la logique visuelle ne s'y déroulent pas.

Pour modifier le comportement du tableau de bord ou ajouter de nouveaux composants avec React, vous devrez accéder au dossier dédié au développement du frontend.

C'est dans ce dossier 📂 ui/ que vous trouverez les composants du tableau de bord et pourrez développer les nouvelles fonctionnalités visuelles de votre application.

Créer un formulaire​

Dans cette étape, nous allons créer la structure de base de données nécessaire à ce tutoriel : un formulaire appelé Client contenant un champ texte appelé Nom.

  • Dans le Backoffice, accédez à la zone de développement en cliquant sur le bouton Construire (coin supérieur droit).

  • Dans le menu latéral, naviguez jusqu'à Gestion > Formulaires et créez le nouveau formulaire avec le Titre : Client.

  • Cliquez sur Enregistrer.

Le nom de la table sera automatiquement rempli avec client (conservez en minuscules, comme recommandé pour les bases de données).

Consultez le guide

En cas de doute sur les configurations avancées de cet écran, consultez la documentation complète dans Formulaires.

Créer un champ​

Une fois le formulaire créé, il apparaîtra dans le menu latéral gauche dans la catégorie Champs.

  • Cliquez sur Client pour ajouter une nouvelle colonne :
  • Saisissez le texte « Nom » dans le Titre du champ.
  • Sélectionnez le type de données « text » dans le champ Type.
  • Cochez les options Autoriser le filtre (pour activer la recherche) et Afficher dans le résultat (pour apparaître dans la table).
  • Cliquez sur Enregistrer.
Consultez le guide

Pour comprendre tous les types de données disponibles et leurs propriétés, accédez à la documentation détaillée dans Champs.

Insérer des données de test​

Pour que nous puissions tester l'exportation PDF dans les prochaines étapes, nous avons besoin de données réelles dans le système.

  • Cliquez sur le bouton Visualiser (coin supérieur droit) pour revenir au Backoffice d'utilisation de l'application.
  • Accédez au menu Client récemment créé dans la barre latérale.
  • Utilisez le bouton + Ajouter pour enregistrer quelques clients de test dans le système.
  • Cliquez sur Enregistrer.

Consulter la base de données​

Netuno propose un outil intégré qui permet d'exécuter des commandes SQL directement dans la base de données de votre application. Il devient essentiel pour effectuer des requêtes rapides, valider des informations ou manipuler les données du système de manière agile.

Pour accéder à l'interface de requêtes et exécuter vos commandes, suivez les étapes ci-dessous :

  • Dans l'interface principale, accédez à la zone de développement en cliquant sur le bouton Construire.
  • Dans le menu latéral de navigation, localisez la section Gestion.
  • Cliquez sur l'option Query pour ouvrir la console de base de données.
  • Dans l'éditeur de texte qui apparaîtra à l'écran, saisissez la commande SQL que vous souhaitez exécuter.
  • Confirmez l'exécution de la commande.

Exécutez la commande ci-dessous pour consulter les clients enregistrés :

SELECT * FROM client

Lorsque vous avez terminé les requêtes et souhaitez revenir à l'interface utilisateur du système (backoffice), il vous suffit de cliquer sur le bouton Visualiser.

Ajouter des boutons avec React​

Dans cette étape, nous allons configurer le fichier principal du panneau tableau de bord pour afficher deux nouveaux boutons.

Dans l'architecture d'interface, nous utilisons le concept de Containers pour définir des zones étendues du système, qui englobent des fonctionnalités plus importantes et regroupent plusieurs composants plus petits.

  • Dans votre éditeur de code, naviguez jusqu'au dossier des containers dans 📂 ui/src/containers.

  • Localisez et ouvrez le fichier principal du tableau de bord : 📂 DashboardContainer/index.jsx.

  • Insérez le code d'importation et de rendu des composants comme dans l'exemple ci-dessous.

ui/src/containers/DashboardContainer/index.jsx
import { Space } from 'antd';

import BoutonClientModal from '../../components/BoutonClientModal';
import BoutonPDF from '../../components/BoutonPDF';

import "./index.less";

function DashboardContainer() {
    return (
        <div className="mon-tableau-de-bord">
            <Space>
                <BoutonClientModal />
                <BoutonPDF />
            </Space>
        </div>
    );
}

export default DashboardContainer;

Notez que ces fichiers de boutons n'existent pas encore physiquement dans votre projet. Comme il s'agit de composants plus petits et réutilisables, nous les créerons dans le dossier des composants dédiés.

Organisation de l'architecture

Maintenez toujours la séparation entre Containers (zones de portée étendue, comme des pages entières ou des tableaux de bord) et Components (éléments d'interface isolés, comme des boutons et des modales). Cela rend votre code dans Netuno beaucoup plus propre, facile à maintenir et évolutif.

Bouton pour formulaire​

Accédez au dossier ui/src/components/ et créez un nouveau dossier appelé BoutonClientModal.

Dans le dossier BoutonClientModal, créez le fichier principal du composant nommé index.jsx.

📂 ui/src/components/BoutonClientModal/index.jsx

Ouvrez le fichier et insérez le code ci-dessous :

ui/src/components/BoutonClientModal/index.jsx
import { Button } from 'antd';

function BoutonClientModal() {
    const onClick = () => {
        netuno.modal.create({
            name: 'client',
            callback: function (modal) {
                let form = modal.find('[netuno-form]');

                form.on('netuno:new', () => {
                    console.log("Création d'un nouveau client.");
                });

                form.on('netuno:save', () => {
                    netuno.modal.hide(modal)
                    console.log("Sauvegarde d'un client.");
                });

                form.on('netuno:delete', () => {
                    netuno.modal.hide(modal)
                    console.log("Suppression d'un client");
                });

                form.on('netuno:back', () => {
                    console.log("Clic sur retour");
                });

                netuno.loadForm(form);
                netuno.modal.show(modal);
            }
        });
    };
    return (
        <div>
            <Button type="primary" onClick={ onClick }>
                Ouvrir le formulaire client
            </Button>
        </div>
    );
}

export default BoutonClientModal;

Comprendre le code​

La magie de ce composant se produit à l'intérieur de la fonction onClick, qui utilise les outils globaux d'interface de Netuno :

  • netuno.modal.create() : Cette méthode est responsable de l'instanciation de la fenêtre modale à l'écran et de la liaison du formulaire souhaité à celle-ci (dans ce cas, le formulaire appelé client).

  • Événements de formulaire (form.on) : Le bloc callback nous permet d'« écouter » (listen) les actions de l'utilisateur. Nous pouvons déclencher des actions personnalisées lorsque l'utilisateur crée un enregistrement (netuno:new), enregistre (netuno:save), supprime (netuno:delete) ou clique sur retour (netuno:back).

  • netuno.modal.hide() / show() : Méthodes utilisées pour masquer la modale après une action réussie ou l'afficher dès que le formulaire est chargé.

Intégration terminée

Maintenant que le composant BoutonClientModal a été créé avec succès, l'importation que nous avons faite précédemment dans votre DashboardContainer fonctionnera sans erreur, et le bouton devrait déjà être rendu à l'écran !

Bouton pour exporter en PDF​

Dans cette étape, nous créerons le deuxième bouton du tableau de bord : le bouton pour exporter en PDF.

La fonction principale de ce composant dans l'interface est d'agir comme un déclencheur, c'est-à-dire qu'au clic, il effectuera une requête vers un service backend, responsable du traitement des données du système et de la génération du fichier PDF contenant la liste des clients enregistrés.

  • Accédez au dossier ui/src/components/ et créez un nouveau dossier appelé BoutonPDF.

  • Créez un fichier appelé index.jsx dans le dossier.

ui/src/components/BoutonPDF/index.jsx

Ouvrez le fichier et insérez le code ci-dessous :

ui/src/components/BoutonPDF/index.jsx
import { Button } from 'antd';

function BoutonPDF() {
    return (
        <div>
            <Button
                type="primary"
                href="/services/client/exporte-pdf"
                target="blank">
                Exporter en PDF
            </Button>
        </div>
    );
}

export default BoutonPDF;

Avec la création du composant BoutonPDF, les deux boutons déclarés dans votre DashboardContainer sont prêts.

Prochaines étapes

La structure visuelle et les composants sont terminés. Compilez le frontend pour tester le rendu de l'interface.

La construction du service backend qui générera effectivement le PDF sera abordée dans la prochaine étape.

Compiler le frontend​

Les navigateurs web ne comprennent pas nativement les codes écrits en React, les fichiers .jsx ou .tsx et les préprocesseurs CSS comme .less. Pour que votre interface fonctionne correctement, il est nécessaire de passer par un processus de compilation (build). Ce processus traduit, empaquette et optimise tout votre code en fichiers statiques finaux (JavaScript et CSS standard) que le navigateur peut traiter avec une efficacité maximale.

Prérequis​

Avant de commencer la compilation, assurez-vous que :

  • Vous avez le terminal ou l'invite de commande ouvert dans votre environnement de développement.

  • Le gestionnaire de paquets Bun est correctement installé sur votre système.

Exemples de compilation​

Netuno met à disposition différentes commandes selon l'étape de votre développement. À partir du dossier racine de Netuno, naviguez jusqu'au dossier ui de votre application.

Exécutez les commandes dans le dossier de l'interface de votre application : 📂 apps/monapp/ui

Compilation de production​

Effectue la compilation complète et optimisée des fichiers. C'est la commande idéale lorsque vous terminez le développement d'un écran ou d'un composant et souhaitez générer les fichiers finaux légers et avec de meilleures performances.

bun run build

Compilation de développement​

La commande watch effectue une compilation rapide et surveille le dossier. Chaque fois que vous enregistrez un fichier dans votre éditeur, le terminal exécute automatiquement la compilation.

bun run watch

Indépendamment de la commande utilisée build ou watch, les modifications n'apparaissent pas instantanément à l'écran de l'utilisateur. Actualisez la page du backoffice dans votre navigateur pour charger les nouveaux fichiers générés.

Surveillance des erreurs et débogage

Pendant le développement, des erreurs peuvent survenir à deux étapes différentes. Sachez où les chercher :

  • Erreurs de compilation : Les erreurs de syntaxe dans le code React ou les variables non déclarées seront présentées directement dans votre terminal, où la commande bun est en cours d'exécution.

  • Erreurs d'exécution : Les erreurs qui se produisent pendant l'utilisation de l'application seront présentées dans la console du navigateur. Rappelez-vous toujours d'inspecter la page pour vérifier s'il y a une alerte ou une erreur.

Compilation intégrée​

La fonctionnalité de compilation intégrée permet d'exécuter automatiquement des commandes de terminal en même temps que l'initialisation du serveur. Cela optimise le flux de travail en consolidant tous les logs et surveillances dans un seul terminal central.

Pour activer la compilation intégrée, il est nécessaire de modifier les configurations de développement de votre application :

  • Accédez au dossier racine de votre application.

  • Ouvrez le fichier de configuration de développement : _development.json.

  • Localisez le bloc de code relatif à « commands ».

  • Modifiez la valeur de la propriété « enabled » de false à true.

  • Enregistrez le fichier.

Votre fichier _development.json devra avoir une structure similaire à celle-ci :

config/_development.json
  ...
  "commands": [{
    "command": "bun run watch",
    "enabled": true,
    "install": "bun install",
    "path": "ui"
  }],
  ...

Pour que Netuno lise le fichier mis à jour et applique la nouvelle configuration, il est nécessaire de redémarrer le serveur :

  • Allez jusqu'au terminal où le serveur Netuno est en cours d'exécution.

  • Arrêtez le processus en appuyant simultanément sur les touches CTRL + C.

  • Redémarrez le serveur en indiquant le nom de votre application :

./netuno server app=monapp
Terminal unique

Après avoir redémarré le serveur, observez les logs dans le terminal. Vous remarquerez que Netuno exécute maintenant automatiquement les commandes de compilation du frontend bun run watch en arrière-plan. Désormais, tout fonctionne intégré dans la même fenêtre.

Service API pour générer un PDF​

Dans l'étape précédente, nous avons configuré le bouton Exporter en PDF dans le frontend avec l'attribut « href » pointant vers l'adresse services/client/exporte-pdf. Cependant, si vous cliquez dessus maintenant, rien ne se passera. Cela se produit parce que le service API responsable de la génération du fichier n'existe pas encore.

Tout le développement de l'API se déroule dans le dossier 📂 server. Dans cette section, nous créerons le script qui récupère les enregistrements dans la base de données et construit visuellement le document PDF.

Prérequis​

  • Avoir créé le composant BoutonPDF dans le frontend pointant vers l'URL correcte.
  • Avoir le serveur Netuno en cours d'exécution.

Netuno route automatiquement les URL de votre API en fonction de la structure des dossiers dans server/services/. Pour créer le service, suivez les étapes :

  • Naviguez jusqu'au dossier des services du backend : server/services/. Créez un dossier appelé client.

  • Dans ce dossier, créez un fichier appelé exporte-pdf.js.

Netuno est polyglotte. Nous utiliserons JavaScript dans cet exemple, utilisez l'extension correspondant au langage de votre choix.

Ouvrez le fichier et insérez le code ci-dessous pour générer la structure de votre PDF :

  • server/services/client/exporte-pdf.js
server/services/client/exporte-pdf.js
_header.contentType("pdf")

const pdfDocument = _pdf.newDocument(_pdf.pageSize("A5"))

pdfDocument.add(
    _pdf.paragraph("Liste des clients :")
        .setFontSize(16)
        .setFontColor(_pdf.color("#1abc9c"))
)

const dbClients = _db.form("client").all()

for (const dbClient of dbClients) {
    pdfDocument.add(
        _pdf.paragraph(dbClient.getString("nom"))
            .setFontSize(12)
            .setFontColor(_pdf.color("#748dae"))
    )
}

pdfDocument.close()

Comprendre le code​

  • _header.contentType("pdf") : Informe au navigateur que la réponse de cette requête n'est pas un texte ou du JSON ordinaire, mais un fichier PDF.

  • _pdf : C'est la ressource native de Netuno pour la manipulation de PDF. Avec elle, nous définissons la taille de la page (A5), créons des paragraphes, ajustons les tailles de police (setFontSize) et les couleurs (setFontColor).

  • _db.form("client").all() : Interroge la base de données et retourne tous les enregistrements enregistrés dans le formulaire « client ». La boucle de répétition (for) parcourt chacun de ces clients et extrait l'information du champ « nom » pour l'imprimer dans le document.

  • pdfDocument.close() : Finalise la construction du document et l'envoie comme réponse.

Validation et tests​

Il n'est pas nécessaire de cliquer sur le bouton du tableau de bord chaque fois que vous souhaitez tester votre service. Comme il s'agit d'une requête simple (GET), vous pourrez valider l'exécution en accédant directement à l'URL de l'API depuis le navigateur.

Pour cet exemple, accédez à l'adresse suivante : http://localhost:9000/services/client/exporte-pdf

Si le fichier PDF est généré et affiché à l'écran contenant la liste des clients, le service fonctionne parfaitement ! Par conséquent, le bouton Exporter en PDF dans votre tableau de bord fonctionnera automatiquement.

Traçage des erreurs dans le backend

Si la page reste blanche ou renvoie un message d'erreur lors de l'accès à l'URL, vérifiez immédiatement le terminal où le serveur Netuno est en cours d'exécution. Contrairement au frontend, dont les erreurs apparaissent dans la console du navigateur, toute erreur d'exécution dans les scripts du dossier server sera affichée en détail dans le terminal du serveur backend.

Conclusion​

Dans ce tutoriel, vous avez suivi un parcours pratique de développement fullstack avec Netuno.

L'objectif principal était de démontrer comment la plateforme intègre la construction d'interfaces visuelles avec la robustesse du serveur, en se concentrant toujours sur une haute productivité.

Récapitulons les étapes terminées :

  • Développement frontend : vous avez personnalisé le tableau de bord en React, en créant des composants d'interface et des boutons interactifs de manière modulaire.

  • Gestion et structure de données : vous avez vu à quel point il est rapide de créer des formulaires et des champs dans le panneau pour enregistrer et manipuler des informations sans avoir à écrire de routines complexes de persistance.

  • Requêtes directes : Vous avez utilisé la fonctionnalité Query pour exécuter des commandes SQL de manière agile, en testant la base de données.

  • Création d'API dans le backend : Vous avez développé un service pour la génération de PDF et observé l'un des grands avantages de Netuno : la mise à jour à chaud (hot-reload). Vous n'avez pas besoin de redémarrer le serveur à chaque modification du code backend, ce qui accélère immensément la programmation.

  • Environnement optimisé : Vous avez configuré la compilation intégrée, en centralisant les processus du frontend et du backend dans un seul terminal pour maintenir la concentration et éviter les distractions.

La plateforme a été conçue dès son essence pour optimiser et accélérer le développement logiciel. Maintenant que vous comprenez le flux de base d'intégration entre low-code et code personnalisé, vous êtes prêt à construire des applications beaucoup plus complexes et évolutives.

Continuez à explorer les prochaines sections de la documentation pour maîtriser de nouvelles fonctionnalités.

Le développement devient beaucoup plus facile lorsque vous faites partie d'une communauté active. Accédez aux liens des réseaux sociaux dans le pied de page de cette page.