Leçons tirées du déploiement d’un SaaS Next.js et de la création d’une CLI de squelette

Livrer un véritable produit SaaS avec React et Next.js ne consiste pas tant à choisir une bibliothèque à la mode qu’à prendre correctement des dizaines de décisions mineures et peu spectaculaires avant même d’approcher un tableau de bord. La même discipline qui permet à l’architecture d’un produit de résister aux exigences des clients réels se retrouve dans des tâches aussi routinières que la création d’un nouveau projet Next.js — c’est pourquoi un outil CLI développé en interne pour générer du code de base enseigne la même leçon que la construction du SaaS lui-même : c’est le travail fastidieux de configuration qui détermine réellement si un projet réussit ou échoue.

Choisir une stack qui ne ralentira pas vos projets

Après avoir lancé plus d’un produit SaaS, une stack finit généralement par adopter une structure prévisible :

1. Next.js en tant que framework unique pour le routage, le rendu du côté serveur et les routes API, afin d’éviter de devoir gérer des outils distincts pour chaque fonctionnalité.

TypeScript, c’est indispensable, surtout là où se trouve la logique de facturation — ce ne sont pas les types d’erreurs que l’on souhaite voir apparaître en temps de exécution.

Tailwind CSS pour le stylisme, principalement parce qu’il évite la lutte constante contre la spécificité CSS.

Redux Toolkit ou Zustand, réservés exclusivement aux états qui nécessitent réellement d’être partagés à l’échelle globale.

Aucun de ces choix n’est fait par simple curiosité. Ensemble, ils permettent à une petite équipe de travailler rapidement sans accumuler silencieusement une dette technique qu’elle n’aura jamais le temps de rembourser.

Construisez d’abord les fondations discrètes

Il est tentant pour les fondateurs de se lancer directement dans la création de tableaux de bord. Résistez à cette envie. Avant toute interface utilisateur, assurez-vous d’avoir mis en place ces trois éléments :

1. Authentification — mise en œuvre via des sessions réelles, et non seulement des tokens stockés dans localStorage.
2. Multilocataire — même si vous n’avez qu’un seul client pour l’instant, concevez le système pour en accueillir plusieurs dès le départ.
3. Hooks de facturation — l’intégration précoce des webhooks Stripe évite une réécriture fastidieuse une fois le produit vraiment lancé.

Voici un modèle à adopter pour effectuer des appels API ciblant différents locataires sans devoir répéter du code :

// hooks/useTenantFetch.ts
import { useCallback } from "react";
import { useSession } from "next-auth/react";

export function useTenantFetch() {
  const { data: session } = useSession();

  const fetchScoped = useCallback(
    async (endpoint: string, options: RequestInit = {}) => {
      if (!session?.tenantId) throw new Error("No active tenant");

      const res = await fetch(`/api/${session.tenantId}${endpoint}`, {
        ...options,
        headers: {
          ...options.headers,
          "Content-Type": "application/json",
        },
      });

      if (!res.ok) throw new Error(`Request failed: ${res.status}`);
      return res.json();
    },
    [session]
  );

  return { fetchScoped };
}

C’est une petite utilité, mais elle vous épargne de devoir disperser des vérifications d’ID de locataire dans des dizaines de composants par la suite.

Savoir ce qui doit figurer dans l’état global

Chaque donnée ne mérite pas une place dans Redux. Un ingénieur travaillant chez une startup soutenue par Y Combinator l’a bien exprimé : l’état global est une dette qui génère des intérêts avec le temps. Réservez Redux (ou votre stockage global de choix) exclusivement aux éléments vraiment pertinents pour toute l’interface utilisateur — modaux, paramètres fonctionnels, préférences de l’utilisateur — et laissez React Query ou SWR gérer tout le reste, qui n’est en réalité que des données serveur déguisées.

Quelques points clés résument les aspects liés à la création de logiciels SaaS :

• Faites fonctionner l’authentification et la facturation avant d’investir dans une interface utilisateur soignée.
• Le TypeScript cesse d’être optionnel dès qu’il s’agit d’argent.
• Évitez une centralisation excessive de l’état ; la plupart des fonctionnalités relèvent plutôt d’outils de gestion de l’état serveur que d’un stockage global.

Rien de tout cela ne provient de la quête de la bibliothèque la plus récente. Cela vient des principes fondamentaux : il faut mettre en place rapidement l’authentification, la gestion des abonnements et le système de facturation, ce qui rend ensuite bien plus facile l’ajout de fonctionnalités supplémentaires, comme la croissance ou de nouvelles capacités d’échelle.

Lorsque l’installation elle-même devient un goulot d’étranglement

C’est ce même instinct de supprimer les tâches d’installation répétitives et sujettes aux erreurs qui conduit finalement à l’automatisation de ces étapes standard. Chaque développeur frontend connaît cette routine : on crée un nouveau projet avec create-next-app, puis commence le travail fastidieux. Il faut créer un dossier components, séparer ui de features, configurer les hooks, organiser les types partagés, écrire des outils d’aide, configurer les alias de chemins et structurer la hiérarchie des dossiers — et une heure peut s’écouler avant même d’avoir écrit la moindre ligne de logique métier réelle.

Après avoir effectué ce rituel trop de fois, la prochaine étape naturelle a été de l’automatiser, ce qui a conduit à la première version publiée d’un paquet npm open source : nexarch-cli.

Le problème de base

Les modèles de démarrage standard de Next.js offrent une toile blanche, et non une architecture prête pour la production. Les applications modernes ont généralement besoin de :

• Une séparation claire entre la logique de présentation et la logique métier
• Un regroupement modulaire basé sur les fonctionnalités
• Des définitions de types et des enveloppes utilitaires scalables
• Des conventions cohérentes que toute l’équipe peut suivre

Récréer tout cela manuellement pour chaque prototype ou projet client est lent, peu cohérent et sujette aux erreurs.

Ce que fait réellement nexarch-cli

nexarch-cli est un outil en ligne de commande interactif conçu pour mettre en place en quelques secondes une architecture Next.js propre et modulaire. Au lieu de créer manuellement des dossiers imbriqués et des fichiers de remplacement, vous répondez à quelques questions dans votre terminal, et l’outil configure pour vous la structure de base.

Ses principales fonctionnalités incluent :

• Création de squelette interactive grâce à des questions simples dans le terminal adaptées à vos besoins.
• Architecture modulaire avec des conventions prédéfinies permettant une évolution à mesure que l’application grandit.
• Aucune installation globale requise — il s’exécute sur demande via npx.
• Conformité aux conventions actuelles de Next.js et React, assurant que les structures de dossiers suivent les pratiques modernes.

L’exécuter

Il n’est pas nécessaire d’installer quoi que ce soit de manière globale. Vous pouvez l’exécuter directement :

npx nexarch-cli

Lorsque vous avez répondu aux questions, la structure de votre projet est générée et prête pour le développement réel.

Leçons tirées de la création d’une première CLI

Créer et publier cet outil en tant que première tool de développement a nécessité une forte courbe d’apprentissage. Voici quelques-unes des leçons les plus importantes :

• L’expérience utilisateur en terminal est aussi importante que le code sous-jacent. Gérer correctement les sorties de processus, afficher des prompts lisible et présenter des messages d’erreur clairs sont autant d’aspects aussi importants que la logique qui génère les fichiers.
• Les opérations sur le système de fichiers cachent de nombreux cas limites. Écrire des outils de création de dossiers récursifs et des modèles de fichiers qui fonctionnent de manière cohérente sur différents systèmes d’exploitation exige des tests minutieux et répétés.

L’emballage pour npm présente sa propre courbe d’apprentissage. Configurer correctement les binaires de package.json (bin), gérer les permissions des fichiers avec chmod, et maintenir la charge liée aux dépendances à presque zéro révèlent tous le fonctionnement interne des outils CLI basés sur Node.

Où en est le projet actuellement

Cet outil reste une initiative en phase initiale et open source, qui bénéficie des contributions extérieures tout en se développant. Le code est disponible sur github.com/CaffeineLogs/nexarch-cli, et le package publié peut être trouvé dans le registre npm sous le nom nexarch-cli.

Tout utilisateur ayant un layout de projet préféré différent, ou qui rencontre une situation que l’outil de scaffolding ne gère pas encore correctement, est invité à en faire part en tant que problème dans le répertoire de code. Les suggestions concernant des améliorations futures — telles que des configurations de style intégrées ou des préréglages de gestion d’état prêts à l’emploi — sont tout aussi les bienvenues en tant que points de discussion ou commentaires.

Que vous décidiez de ce qui doit figurer dans Redux ou de la manière dont un projet Next.js vierge doit être structuré, le principe reste le même : les aspects d’un projet qui semblent les plus fastidieux — l’authentification, la gestion des abonnements, la facturation, la structure des dossiers — sont précisément ceux qu’il convient de bien mettre en place, et souvent d’automatiser, avant toute autre chose.

Lectures complémentaires