📦 Documentació de harmonix-cli

harmonix-cli és una eina de línia de comandes per publicar plugins al plugin store de Harmonix.

🔧 Instal·lació

Assegura’t de tenir node i npm instal·lats. Afegeix harmonix-cli com a dependència del teu projecte o de forma global:

npm install -g @uxland/harmonix-cli

🚀 Publicació d’un plugin

Comanda principal

harmonix publish

Aquesa comanda llegeix la informació del package.json i puja el fitxer compilat especificat al registry (plugin store) configurat.

📁 Estructura requerida

package.json

El fitxer package.json del teu plugin ha de contenir obligatòriament els següents camps:

{
  "name": "plugin-id",
  "version": "1.0.0",
  "module": "dist/plugin.js"
}

• name: identificador únic del plugin (id del plugin).
• version: versió que es publicarà.
• module: ruta al fitxer compilat que es pujarà.

⚙️ Configuració amb .harmonixrc

Crea un fitxer .harmonixrc a la carpeta arrel del projecte (en cas de monorepo també serveix) amb el següent contingut:

registry=https://plugins.harmonix.dev/upload
apiKey=la_teva_clau_api

• registry: URL del plugin store.
• apiKey: clau API per a l’autenticació.

🛑   Important: El fitxer .harmonixrc conté credencials sensibles. No l’incloguis al repositori de codi. Afegeix-lo al .gitignore:

.harmonixrc

🧰 Paràmetres opcionals (substitueixen .harmonixrc)

També pots passar les opcions directament per línia de comandes:

harmonix publish --registry https://plugins.harmonix.dev/upload --api-key la_teva_clau_api

• --registry: URL del servidor.
• --api-key: clau API d’autenticació.

🫠 Errors comuns i solucions

| Error | Possible causa | Solució | | ------------------------------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------- | | package.json not found | No s’ha trobat el fitxer package.json a la carpeta actual | Executa harmonix publish des de la carpeta del plugin | | 'module' field not found in package.json | Falta el camp module al package.json | Afegeix "module": "ruta/al/fitxer.js" | | Compiled bundle file not found | El fitxer indicat al module no existeix | Compila el plugin abans de publicar o verifica la ruta | | No registry configured | No s’ha especificat registry ni a .harmonixrc ni per línia de comandes | Afegeix registry= a .harmonixrc o passa --registry | | No api key configured | Falta la clau API (apiKey) | Afegeix-la a .harmonixrc o passa --api-key |

📖 Ajuda

Per veure els comandaments disponibles:

npx harmonix --help

✅ Exemple complet

npx harmonix publish --registry https://plugins.harmonix.dev/upload --api-key ABC123XYZ

O bé, si tens .harmonixrc configurat:

npx harmonix publish