@absolu/assets-toolkit

Toolkit Vite pour les pipelines d'assets front-end. Fournit une factory de configuration Vite et deux plugins Vite (iconfont & svgstore), pensés pour les projets utilisant Vite avec SCSS (typiquement des thèmes Drupal ou CMS).

Prérequis : Node.js >= 22

Installation

pnpm add -D @absolu/assets-toolkit

Toutes les dépendances nécessaires (Sass, Vite, plugins d'optimisation) sont incluses — aucune peer dependency à installer manuellement.

Peer dependency : vite >= 5.0.0 est requis uniquement si vous utilisez les plugins de manière standalone (voir Utilisation standalone) ou si vous importez directement depuis vite dans votre config.

Utilisation rapide

1. Scripts package.json

La toolkit expose un binaire assets-toolkit qui encapsule Vite — pas besoin d'installer Vite en dépendance directe :

{
    "scripts": {
        "dev": "assets-toolkit -c ./vite.config.ts",
        "build": "assets-toolkit build -c ./vite.config.ts"
    }
}

2. vite.config.ts

import { createViteConfig } from '@absolu/assets-toolkit'
import localConfig from './config.json' with { type: 'json' }

export default createViteConfig({
    base: '/themes/custom/mon-theme/assets',
    localConfig,
})

C'est tout. Tous les plugins (iconfont, svgstore, optimisation images, live reload) sont activés par défaut avec des valeurs sensibles.

Le fichier config.json (non versionné) contient la configuration locale, propre à chaque machine :

{
    "server": {
        "https": {
            "key": "/chemin/vers/localhost-key.pem",
            "cert": "/chemin/vers/localhost.pem"
        }
    }
}

API

createViteConfig(options)

Factory qui produit une configuration Vite complète.

| Option | Type | Défaut | Description | |---|---|---|---| | base | string | — | Requis. Chemin de base pour le serveur de dev | | localConfig | LocalConfig | — | Configuration locale non versionnée (certificats HTTPS) | | iconfont | IconfontOptions \| false | {} (activé) | Options du plugin iconfont. false pour désactiver | | svgstore | SvgstoreOptions \| false | {} (activé) | Options du plugin svgstore. false pour désactiver | | imagemin | boolean | true | Activer l'optimisation des images raster (png, jpg, webp…) | | liveReload | string[] \| false | ['../templates/**/*.twig'] | Glob patterns pour le live reload. false pour désactiver | | entries | string[] | voir ci-dessous | Glob patterns des fichiers d'entrée | | entriesIgnore | string[] | voir ci-dessous | Patterns à exclure | | manualChunks | (id: string) => string \| undefined | — | Définition des manual chunks | | plugins | Plugin[] | — | Plugins Vite supplémentaires |

Valeurs par défaut

Entrées :

• src/scss/*.scss
• src/scripts/*.{js,ts}
• src/iconfonts/*.{woff2,woff}
• src/images/**/*.{png,jpeg,jpg,gif,svg,webp}

Exclusions : src/images/icons/**/*.svg, src/images/icons-sprite/**/*.svg

Alias : @ → src/, @images → src/images/, @fonts → src/fonts/

Sortie : dist/ avec organisation automatique (css, scripts, images, iconfonts, fonts)

Désactiver des plugins

export default createViteConfig({
    base: '/themes/custom/mon-theme/assets',
    iconfont: false,
    svgstore: false,
    liveReload: false,
    imagemin: false,
})

Personnaliser des plugins

export default createViteConfig({
    base: '/themes/custom/mon-theme/assets',
    localConfig,
    iconfont: {
        svgs: 'src/images/icons/**/*.svg',
        fontName: 'iconfont',
        scssDir: 'src/scss/base/iconfonts',
        iconClassName: 'icon',
        fontPath: '@/iconfonts/',
    },
    svgstore: {
        srcDir: 'src/images/icons-sprite',
        targetFile: 'src/images/sprite.svg',
        symbolId: '[name]',
    },
    liveReload: ['../templates/**/*.twig'],
    entries: [
        'src/scss/*.scss',
        'src/scripts/*.js',
        'src/scripts/*.ts',
        'src/iconfonts/*.{woff2,woff}',
        'src/images/**/*.{png,jpeg,jpg,gif,svg,webp}',
    ],
    entriesIgnore: [
        'src/images/icons/**/*.svg',
        'src/images/icons-sprite/**/*.svg',
    ],
})

VitePluginIconfont(options)

Plugin Vite qui convertit des icônes SVG en font (SVG → TTF → WOFF/WOFF2) et génère les fichiers SCSS correspondants via des templates Nunjucks. Inclut un cache basé sur le hash des fichiers sources pour éviter les rebuilds inutiles.

| Option | Type | Défaut | Description | |---|---|---|---| | svgs | string | src/images/icons/**/*.svg | Glob pattern des fichiers SVG sources | | fontName | string | iconfont | Nom de la font générée | | scssDir | string | src/scss/base/iconfonts | Dossier de sortie des fichiers SCSS | | iconClassName | string | icon | Nom de la classe CSS de base | | fontPath | string | @/iconfonts/ | Chemin relatif vers la font dans le CSS |

VitePluginSvgstore(options)

Plugin Vite qui fusionne des fichiers SVG en un sprite SVG unique, optimisé avec SVGO.

| Option | Type | Défaut | Description | |---|---|---|---| | srcDir | string | src/images/icons-sprite | Dossier source des SVG | | targetFile | string | src/images/sprite.svg | Fichier de sortie du sprite | | symbolId | string | [name] | Pattern pour l'id des symboles |

Utilisation standalone des plugins

Les plugins peuvent être utilisés indépendamment de la factory. Dans ce cas, vite doit être installé en devDependency directe :

pnpm add -D vite

import { VitePluginIconfont, VitePluginSvgstore } from '@absolu/assets-toolkit'
import { defineConfig } from 'vite'

export default defineConfig({
    plugins: [
        VitePluginIconfont({ fontName: 'my-icons' }),
        VitePluginSvgstore({ srcDir: 'src/sprites' }),
    ],
})

Développement local (test avec pnpm link)

Pour tester la toolkit dans un projet consommateur avant publication :

# 1. Builder la lib
cd /chemin/vers/assets-toolkit
pnpm run build

# 2. Lier dans le projet consommateur
cd /chemin/vers/projet-conso
pnpm link /chemin/vers/assets-toolkit

Les scripts du conso utilisent assets-toolkit — Vite est résolu depuis les node_modules de la toolkit, pas besoin de l'installer dans le conso :

{
    "scripts": {
        "dev": "assets-toolkit -c ./vite.config.ts",
        "build": "assets-toolkit build -c ./vite.config.ts"
    }
}

Après chaque modification de la lib, rebuilder avant de relancer le conso :

cd /chemin/vers/assets-toolkit && pnpm run build

Note : En mode pnpm link, l'optimisation des images raster est désactivée (vite-plugin-image-optimizer ne trouve pas sharp à cause de l'isolation pnpm). Pour l'activer en dev, ajouter sharp en devDependency du conso (pnpm add -D sharp). Ce problème n'existe pas en installation réelle depuis npm.

Licence

MIT