web-ext es una herramienta de línea de comano diseñada para acelerar varias partes del proceso de desarrollo de WebExtension, haciendo el desarrollo más rápido y fácil. Este artículo explica cómo instalar y usar web-ext.

Instalación

web-ext es una aplicación basada en node que puedes instalar con la herramienta nodejs/npm. Instala web-ext usando el siguiente comando:

npm install --global web-ext

Ahora puedes probar si tu instalación funciona ejecutanddo el siguiente comando, que lista el número de versión instalada de web-ext:

web-ext --version

Usando web-ext

Una vez que la has instalado, ya puedes probar web-ext. En este punto, es buena idea tener un ejemplo de WebExtension con la cual probar — si no tiene una propia, puedes clonar nuestro repositorio webextensions-examples.

Probando una extensión

Puedes probar una extensión en Firefox yendo al directorio raiz de tu extensión e ingresando el siguiente comando:

web-ext run

Esto iniciará Firefox y cargará la extensión temporalmente en el navegador, como puedes hacerlo en la  página de bout:debugging.

Revisa la guía de referencia de ejecución para aprender sobre todas las opciones disponibles.

Recargar la extensión automáticamente

El comando run observará tus archivos fuente y le dirá a Firefox que recargue la extensión después que has editado y guardado un archivo. Por ejemplo, si cambias la propiedad name en tu archivo manifest.json, Firefox mostraría el nuevo nombre. Esto hace más fácil probar nuevas características y verlas inmediátamente. Para usar la función de recarga automática, ejecuta el comando run:

web-ext run

Presionando 'R' mientras el comando run está activo lanzará la recarga manualmente.

Si se produce un comportamiento inesperado con la función de recarga, por favor registra un bug. También puedes deshabilitar la recarga con esto:

web-ext run --no-reload

La recarga de extension está sólo soportada desde Firefox 49 en adelante.

Probar un diferentes versiones de Firefox

Para ejecutar tu extensión en una versión de Firefox que no sea tu versión por defecto, usa la opción --firefox para especificar la ruta completa al archivo binario. Aquí un ejemplo en Mac OS:

web-ext run --firefox=/Applications/FirefoxNightly.app/Contents/MacOS/firefox-bin

En Windows, la ruta necesita incluir la parte del archivo firefox.exe, por ejemplo:

web-ext run --firefox="C:\Program Files\Mozilla Firefox\firefox.exe"

Probando en 48

Firefox 48 fue la primera versión estable de la plataforma de WebExtension pero éste no permite web-ext para instalar una extensión remotamente. Necesitas ejecutar tu extensión en Firefox 48 con una opción de instalación diferente:

web-ext run --pre-install

Probando extensiones sin firmar

Cuando ejecutas web-ext run, la extensión se instala temporalmente hasta que cierres Firefox. Esto no viola las restricciones de firma. Si creas un archivo zip con web-ext build e intentas instalarlo en Firefox, verás un error diciendo que el complemento no está firmado. Necesitarás usar una versión sin marca o usar una versión de desarrollo para instalar versiones sin firmar.

Usando un perfil personalizado

Por defecto, el comando creará un perfil de Firefox temporal. Puedes ejecutar tu extensión con un perfil específico usando la opción --firefox-profile, como esto:

web-ext run --firefox-profile=chris-work-profile

Esta opción acepta una cadena de texto que contenga el nombre de tu perfil o una ruta absoluta al directorio del perfil.

Cuando usas un perfil personalizado, web-ext primero copia el perfil. El perfil personalizado no será alterado.

Empaquetando tu extensión

Una vez que has probado tu extensión y verificado que funciona, puedes convertirla en un paquete enviandola a addons.mozilla.org usando el siguiente:

web-ext build

Esto mostrará la ruta completa al archivo .zip generado que puede ser cargado dentro un navegador.

El archivo .zip generado no funciona en Firefox sin firmarlo, o sin agregar la propiedad applications.gecko.id dentro del manifest.json. Para más información, por favor revisa la página de WebExtensions y el identificador de complemento.

web-ext build está diseñado para ignorar autimáticamente archivos que son comunmente no necesarios en paquetes, como .git, node_modules, y otros artefactos.

Revisa la guía de referencia sobre construcción para aprender más.

Firmando tu WebExtension para distribución

Como una alternativa a publicar tu extensión en addons.mozilla.org, puedes publicar tu mismo tu paquete pero éste necesita estar firmado por Mozilla primero. El siguiente comando empaqueta y firma un archivo ZIP, y lo convierte en un archivo XPI formado para distribución:

web-ext sign --api-key=$AMO_JWT_ISSUER --api-secret=$AMO_JWT_SECRET 

Las opciones del API son requeridas para especificar tus credenciales de addons.mozilla.org.

  • --api-key: the API key (JWT issuer) de addons.mozilla.org necesario para firmar la extensión. Esto debe ser siempre una cadena de texto.
  • --api-secret: the API secret (JWT secret) de addons.mozilla.org necesario para firmar la extensión. Esto debe ser siempre una cadena de texto.

Revisa la guía de referencia sobre firmas para aprender sobre todas las opciones disponible.

Firmando extensiones sin un ID explícto

web-ext soporta completamente firma de extensiones que no declaran la propiedad applications.gecko.id en su manifiesto. La primera vez que tu firmas una extensión sin un ID explícito, addons.mozilla.org generará automáticamente un ID y web-ext lo guardará en .web-extension-id en el actual directorio de trabajo. Deberás guardar el archivo de ID para poder firmar futuras versiones de la misma extensión. Si pierdes el archivo de ID, tendrás que agregar de nuevo la propiedad applications.gecko.id o usar la opción --id cuando firmes versiones futuras, por ejemplo:

web-ext sign --api-key=... --api-secret=... --id="{c23c69a7-f889-447c-9d6b-7694be8035bc}"

Firmando en un entorno restringido

Si estás trabajando en un entorno que restringe el acceso a ciertos dominios, puedes intentar usar un proxi cuando hagas el firmado:

web-ext sign --api-key=... --api-secret=... --api-proxy=https://yourproxy:6000

Lee más sobre --api-proxy para detalles.

Si sólo necesitas permitir los dominios usados para firmar y descargar, sigue estos:

  • addons.mozilla.org
  • addons.cdn.mozilla.net

Verificando código con "lint"

Antes de probar tu extensión con el comando run o enviar tu paquete a addons.mozilla.org, puedes usar el comando lint para asegurarte que tu manifest y otros archivos fuente no contienen errors. Por ejemplo:

web-ext lint

Esto usar la libería addons-linter para recorrer el directorio de tu código fuente y reportar de cualquier error, como la declaración de un permiso desconocido.

Revisa la guía de referencia sobre lint para aprender sobre todas las opciones disponibles.

Especificando diferentes directorios de origen y destino

Todos los comandos anteriores usan los directorios por defecto para el origen de la extensión y la creación del artefacto (p.ej. archivos.zip construidos). Los directorios por defecto son:

  • Origen: El directorio dentro del cual estás actualmente.
  • Artefactos: Un directorio llamado ./web-ext-artifacts, creado dentro el directorio actual.

Puedes especificar diferentes directorios de origen y destino usando las opciones de comando --source-dir (o el alias -s) y --artifacts-dir (o el alias -a) cuando ejecutes tus comandos. Estos valores pueden ser rutas relativas o absolutas, pero siempre deben estar especificadas como cadenas de texto. Aquí hay un ejemplo especificando ambas opciones al mismo tiempo cuando se construye la extensión:

web-ext build --source-dir=webextension-examples/notify-link-clicks-i18n --artifacts-dir=zips

Mostrando mensajes detallados

Si quieres ver lo que está web-ext está haciendo exactamente cuando ejecutas un comando, puedes incluir la opción --verbose option (o el alias -v). Por ejemplo:

web-ext build --verbose

Revisando todos los comandos y opciones

Puedes listar todos comandos y opciones con esto:

web-ext --help

Nota: También puedes usar el alias -h.

Puedes listar las opciones de un comando específico agregandolo como un argumento:

web-ext --help run

Revisa también

Etiquetas y colaboradores del documento

 Colaboradores en esta página: AngelFQC, Josephsantiago1
 Última actualización por: AngelFQC,