Installation

Ce guide vous accompagne dans l'installation complète et la mise en route du projet Djust Front Partners Starter, une application e-commerce B2B basée sur Nuxt 3.

Prérequis Système

1. Version Node.js

# Version requise (voir .nvmrc)
Node.js v20.18.1 ou supérieur

Vérification :

node --version
# Doit afficher : v20.18.1 ou plus récent

2. Gestionnaire de Paquets

Le projet utilise Yarn v4.9.1 (recommandé) :

# Vérification Yarn
yarn --version
# Doit afficher : 4.9.1

# Si Yarn n'est pas installé
npm install -g yarn

Gestionnaires supportés :

✅ Yarn 4.9.1 (recommandé)
✅ npm (compatible)
✅ pnpm (compatible)
✅ bun (compatible)

3. Git

# Vérification Git
git --version
# Exemple : git version 2.39.0

4. Éditeur de Code (Recommandé)

Visual Studio Code avec extensions :

Vue Language Features (Volar)
TypeScript Vue Plugin (Volar)
Tailwind CSS IntelliSense
ESLint
Prettier

Installation Pas à Pas

Étape 1 : Clonage du Projet

# Cloner le repository
git clone https://your-repo-url.git djust-front-partners-starter

# Naviguer dans le projet
cd djust-front-partners-starter

# Vérifier la branche
git branch
# Devrait afficher : * preprod ou main

Étape 2 : Configuration Node.js (avec NVM)

# Installer la bonne version Node.js (optionnel avec NVM)
nvm install
nvm use

# Vérification
node --version
# Doit afficher : v20.18.1

Étape 3 : Installation des Dépendances

Option A : Yarn (Recommandé)

# Activer Corepack pour Yarn
corepack enable

# Installer les dépendances
yarn install

# Vérification de l'installation
yarn --version
# Doit afficher : 4.9.1

Option B : Autres Gestionnaires

# npm
npm install

# pnpm
pnpm install

# bun
bun install

Étape 4 : Configuration Environnement

Création du fichier .env

# Copier le template d'environnement
cp env.preprod .env

# Ou pour développement local
cp env.dev .env

Configuration des Variables

Éditez le fichier .env créé :

# Ouverture avec votre éditeur préféré
code .env
# ou
nano .env
# ou
vim .env

Variables d'Environnement Obligatoires

# === API DJUST (OBLIGATOIRE) === #
VITE_API_BASE_URL=https://djust-api.test.djust-app.com
VITE_DJ_API_KEY=GT3BatopsDjGIE0DXHE5GHnsCFI4lT8f
VITE_DJ_API_CLIENT=ACCOUNT

# === MAGASIN (À CONFIGURER) === #
STORE_ID=your-store-id
STORE_VIEW_ID=your-store-view-id

# === LOCALISATION === #
LOCALE=fr-FR
DEFAULTCURRENCY=EUR
CURRENCIES=EUR,USD,JPY

# === STORYBLOK CMS (OPTIONNEL) === #
STORYBLOK_VERSION=draft
STORYBLOK_ACCESS_TOKEN=F6kfqYyrG3upENipwgJ0lAtt
STORYBLOK_STORIES_LIST=header,footer,logo,faq,homepage

# === APPLICATION === #
DEFAULT_PAGINATION_SIZE=20
FRONT_MODE=private
MULTI_STORES=false
APPLICATION_ENV=development
CLIENT_NAME=YOUR-CLIENT-NAME

# === MONITORING (OPTIONNEL) === #
SENTRY_DSN=your-sentry-dsn-url

Configuration par Environnement

Environnement	Fichier Base	Description
Développement	`env.dev`	Configuration locale
Pré-production	`env.preprod`	Tests avant production
QA Multi-stores	`env.qa-multistores`	Tests multi-magasins
Production	`env.prod`	Environnement live

Étape 5 : Vérification de l'Installation

Test de Démarrage

# Démarrer le serveur de développement
yarn dev

# Avec autres gestionnaires
npm run dev
pnpm run dev
bun run dev

Sortie attendue :

Nuxt 3.16.2 with Nitro 2.x.x

  ➜ Local:    http://localhost:3000/
  ➜ Network:  use --host to expose

ℹ Using Nitro development server.
✔ Nuxt DevTools is enabled v1.x.x

Vérification dans le Navigateur

Ouvrir : http://localhost:3000
Vérifier : Page d'accueil se charge
Console : Aucune erreur critique
Network : Appels API fonctionnels

Tests des Fonctionnalités

# Linter (qualité code)
yarn lint

# Formatage code
yarn format:check

# Analyse du build
yarn analyze

# Informations projet
yarn project-info

Configuration Avancée

1. Configuration IDE (VS Code)

Créer .vscode/settings.json :

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.preferences.importModuleSpecifier": "relative",
  "vue.inlayHints.optionsWrapper": true,
  "tailwindCSS.experimental.classRegex": [
    ["ui:\\s*{([^}]*)}", "[\"'`]([^\"'`]*).*?[\"'`]"]
  ]
}

2. Configuration Git Hooks

# Installation automatique avec Husky
yarn prepare

# Vérification des hooks
ls -la .husky/
# Doit afficher les hooks pre-commit, etc.

3. Configuration Développement Multi-stores

Pour tester le mode multi-magasins :

# Utiliser la configuration QA multi-stores
cp env.qa-multistores .env

# Modifier la variable
MULTI_STORES=true

4. Configuration SSL Local (HTTPS)

# Démarrer avec HTTPS
yarn dev --https

# Ou configurer dans nuxt.config.ts
{
  devServer: {
    https: true
  }
}

Scripts Disponibles

Scripts de Développement

Script	Commande	Description
Développement	`yarn dev`	Serveur dev avec hot-reload
Build	`yarn build`	Compilation production
Preview	`yarn preview`	Test du build local
Start	`yarn start`	Serveur production

Scripts de Qualité

Script	Commande	Description
Lint	`yarn lint`	Vérification ESLint
Lint Fix	`yarn lint:fix`	Correction auto ESLint
Format	`yarn format`	Formatage Prettier
Format Check	`yarn format:check`	Vérification format

Scripts d'Analyse

Script	Commande	Description
Analyze	`yarn analyze`	Analyse bundle Nuxt
Project Info	`yarn project-info`	Infos système/projet
Cleanup	`yarn cleanup`	Nettoyage complet

Script de Nettoyage

# Nettoyage complet (si problèmes)
yarn cleanup

# Équivalent à :
# rm -rf node_modules yarn.lock .nuxt .output
# yarn cache clean
# yarn install
# yarn dev

Variables d'Environnement Détaillées

1. Variables API Djust

# URL de base de l'API Djust
VITE_API_BASE_URL=https://djust-api.test.djust-app.com

# Clé d'authentification API
VITE_DJ_API_KEY=your-api-key

# Type de client (généralement ACCOUNT)
VITE_DJ_API_CLIENT=ACCOUNT

2. Variables Magasin

# Identifiant du magasin
STORE_ID=your-store-id

# Identifiant de la vue magasin
STORE_VIEW_ID=your-store-view-id

Comment obtenir ces IDs :

Se connecter à l'interface Djust
Naviguer vers Configuration > Magasins
Copier les identifiants fournis

3) Variables Localisation

# Langue par défaut
LOCALE=fr-FR

# Devise par défaut
DEFAULTCURRENCY=EUR

# Devises supportées (séparées par virgules)
CURRENCIES=EUR,USD,JPY

4. Variables Storyblok

# Version du contenu (draft/published)
STORYBLOK_VERSION=draft

# Token d'accès Storyblok
STORYBLOK_ACCESS_TOKEN=your-token

# Liste des stories à précharger
STORYBLOK_STORIES_LIST=header,footer,logo,faq,homepage

5. Variables Application

# Taille pagination par défaut
DEFAULT_PAGINATION_SIZE=20

# Mode frontend (private/public)
FRONT_MODE=private

# Support multi-magasins
MULTI_STORES=false

# Environnement application
APPLICATION_ENV=development

# Nom du client
CLIENT_NAME=YOUR-CLIENT

6. Variables Monitoring

# URL Sentry pour monitoring erreurs
SENTRY_DSN=https://your-sentry-dsn-url

Résolution de Problèmes

1. Erreurs d'Installation

Erreur : "Node.js version incompatible"

# Solution : Utiliser la bonne version Node.js
nvm install 20.18.1
nvm use 20.18.1

# Ou mettre à jour Node.js

Erreur : "Yarn command not found"

# Solution : Installer Yarn
npm install -g yarn

# Ou avec Corepack
corepack enable

Erreur : "Permission denied"

# Solution : Utiliser sudo (Linux/Mac)
sudo npm install -g yarn

# Ou changer permissions npm
npm config set prefix ~/.npm-global

2. Erreurs de Configuration

Erreur : "API_BASE_URL not configured"

# Solution : Vérifier .env
cat .env | grep VITE_API_BASE_URL

# Doit afficher la variable configurée

Erreur : "Store ID missing"

# Solution : Configurer STORE_ID et STORE_VIEW_ID
# Dans .env :
STORE_ID=your-store-id
STORE_VIEW_ID=your-store-view-id

3. Erreurs de Démarrage

Erreur : "Port 3000 already in use"

# Solution 1 : Utiliser un autre port
yarn dev --port 3001

# Solution 2 : Tuer le processus existant
lsof -ti:3000 | xargs kill -9

Erreur : "Module not found"

# Solution : Réinstaller les dépendances
rm -rf node_modules
yarn install

4. Erreurs de Build

Erreur : "Build failed"

# Solution : Vérifier les variables d'environnement
yarn build --verbose

# Nettoyer et reconstruire
yarn cleanup

Erreur : "TypeScript errors"

# Solution : Vérifier les types
yarn lint:fix

# Mettre à jour TypeScript
yarn add -D typescript@latest

5. Erreurs SSL/HTTPS

Erreur : "SSL certificate problem"

# Solution temporaire (développement seulement)
export NODE_TLS_REJECT_UNAUTHORIZED=0

# Solution permanente : Configurer certificats SSL

Optimisations de Performance

1. Cache Yarn

# Nettoyer le cache Yarn
yarn cache clean

# Vérifier la taille du cache
yarn cache dir

2. Variables NODE_OPTIONS

# Augmenter la mémoire heap (si nécessaire)
export NODE_OPTIONS="--max-old-space-size=4096"

# Ajouter dans .bashrc/.zshrc pour permanence
echo 'export NODE_OPTIONS="--max-old-space-size=4096"' >> ~/.bashrc

3. Configuration Vite

Dans nuxt.config.ts, optimiser Vite :

export default defineNuxtConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ["vue", "nuxt"],
            utils: ["@djust-b2b/djust-front-sdk"],
          },
        },
      },
    },
  },
});

Déploiement

1. Build Local

# Build pour production
yarn build

# Test du build
yarn preview

# Serveur de production
yarn start

2. Docker

# Build de l'image Docker
docker build -t djust-front-partners-starter .

# Démarrer le conteneur
docker run -p 3000:3000 djust-front-partners-starter

3. Variables de Build Docker

# Build avec fichier env spécifique
docker build --build-arg ENV_FILE=env.prod -t djust-app .

Maintenance

1. Mise à Jour des Dépendances

# Vérifier les mises à jour
yarn outdated

# Mettre à jour les dépendances mineures
yarn upgrade

# Mettre à jour une dépendance spécifique
yarn upgrade nuxt@latest

2. Audit de Sécurité

# Audit des vulnérabilités
yarn audit

# Correction automatique
yarn audit fix

3. Nettoyage Régulier

# Nettoyage complet périodique
yarn cleanup

# Suppression des fichiers temporaires
rm -rf .nuxt .output

Liste de Vérification Post-Installation

✅ Installation Réussie

Node.js v20.18.1+ installé
Yarn v4.9.1 configuré
Dépendances installées sans erreur
Fichier .env créé et configuré
Serveur dev démarre sur http://localhost:3000
Page d'accueil s'affiche correctement
Console sans erreurs critiques
Linter passe sans erreur (yarn lint)
Build réussit (yarn build)

✅ Configuration Avancée

VS Code configuré avec extensions
Git hooks installés (yarn prepare)
Variables API testées et fonctionnelles
Storyblok configuré (si utilisé)
Multi-stores testé (si applicable)
HTTPS local configuré (si nécessaire)

✅ Tests Fonctionnels

Support et Ressources

Documentation Officielle

Nuxt 3 : Framework principal
Nuxt UI : Composants UI
Vue 3 : Framework JavaScript
Tailwind CSS : Framework CSS
Pinia : State management

Outils de Développement

Vue DevTools : Debug Vue
Nuxt DevTools : Debug Nuxt
Vite DevTools : Debug Vite

Ressources Djust

Documentation SDK : Voir /docs/sdk/
Documentation API : Voir /docs/
Support technique : Équipe développement Djust

🎉 Félicitations ! Votre environnement Djust Front Partners Starter est maintenant configuré et prêt pour le développement !

Pour aller plus loin, consultez la documentation des différentes fonctionnalités dans le dossier /docs/.