@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).

Installation

npm install @absolu/assets-toolkit@latest

Peer dependencies

| Paquet | Requis | |---|---| | vite >= 5.0.0 | oui | | sass >= 1.0.0 | oui | | vite-plugin-imagemin >= 0.6.0 | optionnel | | vite-plugin-live-reload >= 3.0.0 | optionnel |

Utilisation rapide

Créez un fichier vite.config.ts à la racine de votre projet :

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, live reload) sont activés par défaut avec des valeurs sensibles. Vous pouvez les personnaliser ou les désactiver individuellement (voir API ci-dessous).

Le fichier config.json (non versionné) contient uniquement 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 avec des valeurs par défaut sensibles (globs d'entrée, chemins de sortie, alias, plugins).

| Option | Type | Défaut | Description | |---|---|---|---| | base | string | — | Requis. Chemin de base pour le serveur de dev (ex. /themes/custom/mon-theme/assets) | | 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 le plugin imagemin | | 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 |

localConfig

Configuration locale, typiquement chargée depuis un config.json non versionné.

| Propriété | Type | Description | |---|---|---| | server.https.key | string | Chemin vers le fichier clé privée du certificat SSL | | server.https.cert | string | Chemin vers le fichier certificat SSL |

Valeurs par défaut

Entrées :

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

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,    // désactive la génération d'iconfont
    svgstore: false,    // désactive la génération du sprite SVG
    liveReload: false,  // désactive le live reload
    imagemin: false,    // désactive l'optimisation d'images
})

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'],
    imagemin: true,
    entries: [
        'src/scss/*.scss',
        'src/scripts/*.js',
        'src/scripts/*.ts',
        'src/iconfonts/*.{woff2,woff}',
        'src/images/**/*.{png,jpeg,jpg,gif,svg}',
    ],
    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 ([name] sera remplacé) |

Utilisation standalone des plugins

Les plugins peuvent être utilisés indépendamment de la factory :

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

export default defineConfig({
    plugins: [
        VitePluginIconfont({
            fontName: 'my-icons',
            scssDir: 'src/scss/icons',
            iconClassName: 'icon',
        }),
        VitePluginSvgstore({
            srcDir: 'src/sprites',
            symbolId: 'icon-[name]',
        }),
    ],
})

Licence

MIT