Capsules Codes - Créer un package Node sur son environnement local

TL;DR: Comment configurer un environnement de développement local pour tester vos classes ou utilitaires de package Node dans un projet Laravel local.

Vous trouverez un lien vers une Demo CodeSandbox ou le code source via ce Github Repository. Découvrez en plus sur Capsules ou X.

Il ne devrait toujours pas vous surprendre d'apprendre que nous utilisons des centaines de packages lors du développement d'outils web. Pour les obtenir, il suffit de faire ses emplettes auprès d'un gestionnaire de packages, tel que NPM, qui en compte 2 633 573 en janvier 2024.

Si vous souhaitez développer votre propre package, il est tout à fait légitime de vous demander comment le tester dans des conditions réelles. Publier le package sur NPM en plein développement n'est pas une bonne option. Une autre approche serait de l'intégrer dans un projet vierge sans utiliser NPM. la méthode de cet article se rapproche beaucoup plus d'une situation réelle, mais nécessite une préparation de l'environnement.

Créer un dossier qui servira de base pour votre package.

mkdir package

Création d’un fichier package.json, qui constitue la base essentielle du package.

package/package.json

{
    "name": "capsulescodes-package",
    "description": "Capsules Codes Package",
    "type": "module",
}

name : Le nom devrait être structuré avec l'entité à gauche et le nom du package à droite. Il est fortement recommandé d'utiliser un nom de package descriptif pour faciliter la recherche par les utilisateurs.
description : La description du package doit être claire et concise.
type : Indiquer module comme type permet de charger les fichiers Javascript comme étants des modules ES au lieu de modules CommonJS.

En outre, éxecuter npm init dans un dossier qui ne contient pas de fichier package.json lancera un assistant qui vous guidera tout au long du processus de création de votre fichier package.json.

Créer un dossier src à l'intérieur du dossier du package.

cd package 
mkdir src

La disposition des dossiers n'a pas de réelle importance, mis à part leur proximité, tant pour vous que pour cet article.

Créer une classe Javascript nommée Greeter contenant une fonction greet renvoyant la phrase Hello world!.

package/src/Greeter.js

export default class Greeter
{
    static greet()
    {
        return 'Hello world!';
    }
}

Il faut alors indiquer vers quel fichier le package doit renvoyer, dans ce cas-ci src/Greeter.js par défaut.

package/package.json

{
    ...
    "main" : "src/Greeter.js"
    ...
}

Il est maintenant possible de tester ce package. Pour cela il faut créer un environnement de test à l’aide d’un projet Laravel modèle.

Retour au dossier parent du package et création d’un projet Laravel faisant office de template de test. Un projet Laravel Vue Inertia Tailwind est utilisé au préalable pour cet article.

cd ..
mkdir template
cd template

Le package est prêt à être installé.

Lancer la commande npm install ../package à la racine du projet template ou indiquer la nouvelle dépendance locale dans le fichier package.json.

template/package.json

{
    "dependencies": {
        "capsulescodes-package" : "file:../package"
    }
}

L’annotation file: indique qu’il s’agit d’un chemin vers un dossier local. Les modifications faites dans le dossier package feront effet dans le dossier node_modules du dossier template.
npm uninstall capsulescodes-package permet de désinstaller le package local.

Tester via le terminal :

> node -e "import( 'capsulescodes-package' ).then( module => console.log( module.default.greet() ) );"

Hello world!

Il n’est pas courant de lancer du code directement via node mais -e ou --eval permet d’évaluer l’argument donné.

ou modification du fichier Welcome.vue pour tester la classe statique Greeter.

template/resources/js/pages/Welcome.vue

<script setup>

import Greeter from 'capsulescodes-package';

import logotype from '/public/assets/capsules-logotype.svg';

</script>

<template>

    <div class="w-screen h-screen flex flex-col items-center justify-center text-center">

        <img class="w-24 h-24" v-bind:src="logotype" v-bind:alt="'Capsules Codes Logotype'">

        <h1 class="mt-4 text-6xl font-bold select-none header-mode" v-text="Greeter.greet()" />

    </div>

</template>

L’environnement de travail est en place.

Il serait intéressant d’ajouter la méthode supplémentaire say() prenant un string en paramètre pour tester l’outil en temps réel.

package/src/Greeter.js

export default class Greeter
{
		...

    static say( something )
    {
        return something;
    }
}

Tester via le terminal :

> node -e "import( 'capsulescodes-package' ).then( module => console.log( module.default.say( 'That\'s a quick way to develop and test a package!' ) ) );"

That's a quick way to develop and test a package!

ou modifier le fichier Welcome.vue pour tester la classe statique Greeter.

template/resources/js/pages/Welcome.vue

<script setup>

import logotype from '/public/assets/capsules-logotype.svg';

import Greeter from 'capsulescodes-package';

</script>

<template>

    <div class="w-screen h-screen flex flex-col items-center justify-center text-center">

        <img class="w-24 h-24" v-bind:src="logotype" v-bind:alt="'Capsules Codes Logotype'">

        <h1 class="mt-4 text-6xl font-bold select-none header-mode" v-text="Greeter.greet()" />

        <h2 class="mt-4 text-xl font-bold select-none header-mode" v-text="Greeter.say( 'That\'s a quick way to develop and test a package!' )" />

    </div>

</template>

À ce stade, tout est prêt pour développer un package Node simple. Mais dans cet article, il est question de mettre en œuvre une commande npm run greet qui appellera la classe statique Greeter.

Pour commencer, il est nécessaire de créer la commande greet. Pour cela il faut retourner dans le dossier du package et créer la commande Greet.js dans le dossier Commands du dossier source src.

package/src/Commands/Greet.js

#!/usr/bin/env node

import Greeter from '../Greeter.js';

console.log( Greeter.greet() );

#!/usr/bin/env node indique qu’il s’agit d’un executable node

Pour accéder à cette commande dans le template , il est dès lors possible de lancer, soit :

node node_modules/capsulescodes-package/src/commands/greet.js

Ou encore ajouter un script dans le fichier package.json qui offrira le même résultat.

>template/package.json

"scripts": {
    ...
    "greet": "node node_modules/capsulescodes-package/src/commands/greet.js"
},

> npm run greet

> greet
> node node_modules/capsulescodes-package/src/commands/greet.js

Hello world!

Il ne reste plus qu’à créer le binary via le package.json.

package/package.json

"bin": {
    "greet" : "src/Commands/Greet.js"
}

Cette propriété va, lors de l’installation du package, venir copier le fichier déterminé src/Commands/Greet.js et coller dans le dossier node_modules/.bin/ en renommant ce fichier par la clef donnée greet.

Si comme dans notre cas, notre package est déjà installé, un énième npm install ../package permet de relancer le processus.

Il n’y a plus qu’à ajouter un nouveau script au fichier package.json ou lancer simplement la commande npx greet . [ npx greet étant l’équivalent de node node_modules/.bin/greet ].

template/package.json

"scripts": {
    "greet": "greet"
},

> npm run greet

> greet
> greet

Hello world!

> npx greet

Hello world!

Dans le cas de la méthode statique say et de son paramètre, une nouvelle commande est nécessaire.

package/src/Commands/Say.js

#!/usr/bin/env node

import Greeter from '../Greeter.js';

console.log( Greeter.say( process.argv[ 2 ] ) );

process.argv représente les arguments de la commande sachant que process.argv[ 0 ] représente node et process.args[ 1 ] représente le binary node_modules/.bin/say dans ce cas-ci.

La commande peut être rajoutée à la liste des binaries dans le fichier package.json.

package/package.json

"bin": {
    "say" : "src/Commands/Say.js"
}

Il n’y a plus qu’à ajouter un nouveau script au fichier package.json ou lancer simplement la commande npx say "Capsules Codes".

template/package.json

"scripts": {
    ...
    "say": "say"
},

> npm run say "Capsules Codes"

> say
> say Capsules Codes

Capsules Codes

> npx say "Capsules Codes"

Capsules Codes

Vous désirez publier cet incroyable package ? Une dernière petite étape s’impose : éviter de publier tous les fichiers du projet :

package/package.json

"files": [ "!*", "src" ]

!* indique qu’il doit tout exclure. Il n’y aura donc plus que le dossier src à garder.

npm publish

Cette commande demande d’être connecté à NPM via npm login
Il est nécessaire d’indiquer la version dans le fichier package.json lors de la publication.

Ravi d’avoir pu aider!

Créer un package Node sur son environnement Laravel local