@jsarc/initiator

@jsarc/initiator est un plugin d'initialisation intelligent pour les applications React avec TypeScript/Javascript. Il génère automatiquement les fichiers de configuration, de routage, d'internationalisation et de providers basés sur la structure de votre projet.

✨ Fonctionnalités Principales

🗺️ Génération Automatique

• Génération automatique des routes à partir de la structure du système de fichiers
• Configuration modulaire avec détection automatique des modules
• Internationalisation automatisée avec extraction des clés de traduction
• Providers React organisés par module et priorité
• Fichiers de configuration générés dynamiquement

⚙️ Initialisation Intelligente

• Détection automatique des fichiers de pages, modules et providers
• Génération de fichiers TypeScript typesafe
• Support des layouts hiérarchiques avec héritage automatique
• Organisation automatique des providers (Context, Redux, Router, etc.)
• Configuration minimale requise

📁 Structure de Projet

• Organisation modulaire naturelle
• Support des pages spéciales (layout, error, 404)
• Routes dynamiques avec paramètres
• Modules indépendants avec leur propre configuration et providers
• Providers globaux et par module hiérarchisés

📦 Installation

Installation globale (recommandée)

npm install -g @jsarc/initiator
# ou
yarn global add @jsarc/initiator
# ou
pnpm add -g @jsarc/initiator

Installation locale

npm install @jsarc/initiator
# ou
yarn add @jsarc/initiator
# ou
pnpm add @jsarc/initiator

🚀 Utilisation Rapide

Commande de base

# Depuis la racine de votre projet
arc-init
# ou
npx @jsarc/initiator

Options disponibles

# Initialiser avec un répertoire spécifique
arc-init --dir ./mon-projet

# Forcer la régénération des fichiers
arc-init --force

# Mode silencieux (moins de logs)
arc-init --quiet

# Afficher l'aide
arc-init --help

Structure de projet générée

src/
├── auto-config.ts      # Configuration générée
├── auto-intl.ts        # Internationalisation générée
├── auto-routes.tsx     # Routes générées
├── auto-provider.tsx   # Providers organisés
├── config.json         # Configuration racine
├── locales/
│   ├── en.json         # Traductions anglais
│   └── fr.json         # Traductions français
├── providers/          # Providers globaux
│   ├── RouterProvider.tsx
│   ├── ReduxProvider.tsx
│   ├── ThemeProvider.tsx
│   └── AuthProvider.tsx
├── pages/
│   ├── _layout.tsx     # Layout racine
│   ├── _error.tsx      # Page d'erreur
│   ├── _404.tsx        # Page 404
│   └── index.tsx       # Page d'accueil
└── modules/
    └── example/
        ├── config.json # Configuration du module
        ├── locales/
        │   ├── en.json # Traductions module
        │   └── fr.json # Traductions module
        ├── providers/  # Providers du module
        │   ├── ReduxProvider.tsx
        │   └── AuthProvider.tsx
        └── pages/
            └── index.tsx # Page du module

🔧 Fonctionnalités Détaillées

1. Génération de Routes

Le plugin scanne automatiquement vos dossiers pages/ et modules/*/pages/ pour :

• Créer des routes React Router automatiquement
• Gérer les layouts hiérarchiques
• Supporter les pages d'erreur spécifiques
• Générer des composants lazy-loaded

2. Internationalisation

Extraction automatique des clés de traduction :

• Scan des fichiers source pour les appels t()
• Détection des modules avec fichiers de traduction
• Génération des imports dynamiques
• Support multi-langue

3. Configuration

Génération centralisée de configuration :

• Configuration racine depuis config.json
• Configuration des modules depuis modules/*/config.json
• Fichier TypeScript avec imports dynamiques

4. Génération de Providers

Organisation automatique des providers React :

• Détection automatique des fichiers provider (Provider.tsx)
• Hiérarchisation intelligente par priorité
• Organisation par module avec encapsulation automatique
• Chargement lazy avec Suspense intégré
• Typage TypeScript complet

📚 API du Plugin

Fonction principale

import init from '@jsarc/initiator';

// Initialisation par défaut (utilise __dirname)
init();

// Avec répertoire personnalisé
init('/chemin/vers/mon/projet');

Classes exportées

import { 
  TranslationGenerator, 
  RouteGenerator, 
  ConfigGenerator,
  ProviderGenerator 
} from '@jsarc/initiator';

// Utilisation avancée
const translationGen = new TranslationGenerator(config);
const routeGen = new RouteGenerator(config);
const configGen = new ConfigGenerator(config);
const providerGen = new ProviderGenerator(config);

Interfaces TypeScript

import type {
  TranslationConfig,
  RouteConfig,
  ConfigGeneratorOptions,
  ProviderConfig,
  TranslationKey,
  RouteFile,
  ProviderInfo
} from '@jsarc/initiator';

🎯 Exemples d'Utilisation

Exemple 1 : Script d'initialisation

// scripts/init.js
import init from '@jsarc/initiator';

// Initialiser avec le répertoire du projet
init(process.cwd());

console.log('✅ Initialisation terminée !');

Exemple 2 : Personnalisation avancée

// scripts/custom-init.ts
import { ProviderGenerator } from '@jsarc/initiator';

const customConfig = {
  srcDir: './src',
  modulesDir: './src/modules',
  providersDir: './src/providers',
  globalProvidersDir: './src/global-providers', // Dossier personnalisé
  outputFile: './src/generated/provider.tsx'
};

const generator = new ProviderGenerator(customConfig);
await generator.generate();

Exemple 3 : Intégration avec un build personnalisé

{
  "scripts": {
    "dev": "vite",
    "build": "npm run generate && vite build",
    "generate": "node scripts/generate-all.js",
    "generate:routes": "node scripts/generate-routes.js",
    "generate:intl": "node scripts/generate-intl.js",
    "generate:config": "node scripts/generate-config.js",
    "generate:providers": "node scripts/generate-providers.js"
  }
}

🔧 Configuration Avancée

Configuration de la traduction

const translationConfig = {
  srcDir: './src',
  supportedLocales: ['en', 'fr', 'es'], // Langues supportées
  outputFile: './src/auto-intl.ts',
  modulesDir: './src/modules',
  localesDir: './src/locales'
};

Configuration du routage

const routeConfig = {
  srcDir: './src',
  modulesDir: './src/modules',
  pagesDir: './src/pages', // Ou 'views', 'screens', etc.
  outputFile: './src/auto-routes.tsx',
  layoutFileName: '_layout', // Fichier de layout
  errorFileName: '_error',   // Fichier d'erreur
  notFoundFileName: '_404'   // Fichier 404
};

Configuration des providers

const providerConfig = {
  srcDir: './src',
  modulesDir: './src/modules',
  providersDir: './src/providers',
  outputFile: './src/auto-provider.tsx',
  globalProvidersDir: './src/providers' // Dossier des providers globaux
};

Fichier config.json racine

{
  "name": "Mon Application",
  "version": "1.0.0",
  "description": "Description de l'application",
  "author": "Votre Nom",
  "defaultLocale": "fr",
  "supportedLocales": ["fr", "en"],
  "apiUrl": "https://api.example.com",
  "features": {
    "auth": true,
    "analytics": false,
    "pwa": true
  }
}

Fichier config.json de module

{
  "name": "Module Admin",
  "description": "Module d'administration",
  "author": "Équipe Admin",
  "version": "1.0.0",
  "routePrefix": "/admin",
  "isEnabled": true,
  "dependencies": ["auth"],
  "permissions": ["admin", "superuser"]
}

📁 Conventions de Fichiers

Pages spéciales

| Fichier | Description | Route générée | |---------|-------------|---------------| | _layout.tsx | Layout du dossier | Non accessible directement | | _error.tsx | Page d'erreur | Utilisée comme errorElement | | _404.tsx | Page non trouvée | Route catch-all | | [param].tsx | Route paramétrée | /:param | | [...slug].tsx | Route catch-all | /* | | index.tsx | Page d'index | / ou /dossier/ |

Providers détectés automatiquement

| Pattern | Type détecté | Priorité | |---------|-------------|----------| | *Router*.tsx | Provider Router | Haute | | *Redux*.tsx | Provider Redux | Haute | | *Theme*.tsx | Provider Theme | Moyenne | | *Context*.tsx | Provider Context | Moyenne | | *Provider.tsx | Provider générique | Basse | | *Error*.tsx | Error Boundary | Très basse |

Structure de module

modules/
└── nom-du-module/
    ├── config.json         # Configuration du module
    ├── locales/            # Traductions du module
    │   ├── en.json
    │   └── fr.json
    ├── providers/          # Providers du module
    │   ├── ReduxProvider.tsx
    │   ├── AuthProvider.tsx
    │   └── ThemeProvider.tsx
    ├── pages/              # Pages du module
    │   ├── _layout.tsx     # Layout du module
    │   ├── _error.tsx      # Erreur du module
    │   ├── _404.tsx        # 404 du module
    │   └── index.tsx       # Page d'accueil du module
    └── components/         # Composants du module (optionnel)

🔄 Workflow de Développement

1. Initialisation du projet

# Créer un nouveau projet
npm create vite@latest mon-app -- --template react-ts
cd mon-app

# Installer l'initiator
npm install @jsarc/initiator

# Générer la structure initiale
npx @jsarc/initiator

2. Ajout d'un nouveau module

# Créer la structure du module
mkdir -p src/modules/admin/{locales,providers,pages,components}

# Ajouter les fichiers de base
touch src/modules/admin/config.json
touch src/modules/admin/pages/index.tsx
touch src/modules/admin/locales/fr.json
touch src/modules/admin/providers/ReduxProvider.tsx

# Régénérer les fichiers
npx @jsarc/initiator

3. Ajout d'un provider global

# Créer un provider global
mkdir -p src/providers
touch src/providers/ThemeProvider.tsx

# Régénérer le fichier auto-provider.tsx
npx @jsarc/initiator

4. Développement avec hot-reload

# Démarrer le serveur de développement
npm run dev

# Dans un autre terminal, surveiller les changements
npx @jsarc/initiator --watch

🛠️ Intégration avec d'autres outils

Avec Vite

// vite.config.js
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  build: {
    rollupOptions: {
      external: ['@jsarc/initiator']
    }
  }
});

Utilisation du AppProvider généré

// main.tsx
import React from 'react';
import ReactDOM from 'react-dom/client';
import App from './App';
import { AppProvider } from './auto-provider';
import './index.css';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <React.StrictMode>
    <AppProvider>
      <App />
    </AppProvider>
  </React.StrictMode>
);

Avec Next.js (Adaptation)

// next.config.js
const { generateRoutes } = require('@jsarc/initiator/adapters/next');

module.exports = {
  async rewrites() {
    const routes = await generateRoutes();
    return routes.map(route => ({
      source: route.path,
      destination: route.filePath
    }));
  }
};

Avec Webpack

// webpack.config.js
const { GenerateRoutesPlugin } = require('@jsarc/initiator/webpack');

module.exports = {
  plugins: [
    new GenerateRoutesPlugin({
      watch: process.env.NODE_ENV === 'development'
    })
  ]
};

🐛 Dépannage

Problèmes courants

1. "Cannot find module"

   # Réinstaller le plugin
   npm install @jsarc/initiator

2. Fichiers non générés

   # Forcer la régénération
   npx @jsarc/initiator --force
      
   # Vérifier les permissions
   chmod +x node_modules/.bin/arc-init

3. Erreurs TypeScript

   # Vérifier les types
   npm run type-check
      
   # Régénérer les fichiers
   npx @jsarc/initiator

4. Providers non détectés

   # Vérifier que le fichier contient "Provider" dans le nom
   # Ou utilise createContext / Context.Provider
   mv src/my-context.tsx src/MyContextProvider.tsx

Logs de débogage

# Activer les logs détaillés
DEBUG=jsarc:* npx @jsarc/initiator

# Sauvegarder les logs dans un fichier
npx @jsarc/initiator 2>&1 | tee init.log

📄 Licence

MIT License - Voir le fichier LICENSE pour plus de détails.

🤝 Contribution

Les contributions sont les bienvenues ! Pour contribuer :

1. Fork le projet
2. Créer une branche (git checkout -b feature/amazing-feature)
3. Commit vos changements (git commit -m 'Add amazing feature')
4. Push vers la branche (git push origin feature/amazing-feature)
5. Ouvrir une Pull Request

🐛 Signaler un Bug

Envoyez nous un mail à l'adresse [email protected] pour :

• Signaler un bug
• Proposer une amélioration
• Poser une question

@jsarc/initiator - Le plugin d'initialisation intelligent pour React et TypeScript.

Développé par l'équipe INICODE