Visual Code es sin duda el IDE más popular hoy en día. Gran parte de su potencia radica en su extensibilidad a través de sus extensiones. A través de las extensiones de Visual Code, los desarrolladores tenemos la oportunidad de customizar la experiencia de este IDE para mejorar la experiencia de desarrollo con nuestros proyectos.

Para empezar a crear extensiones, desde la documentación de Visual Code acerca de extensiones te recomiendan utilizar Yeoman y su VS Code Extension Generator para generar la estructura de archivos necesaria para una extensión. La estructura de archivos que te genera esta herramienta de scaffolding es muy completa, ya que incluye todos lo necesario para debugear, testear, lintear y publicar la extensión. Pero para una primera aproximación al desarrollo de extensiones, creo que toda esta estructura añaden un poco de ruido a lo que serían las ideas claves de crear extensiones.

Así que para este artículo vamos a hacer el ejercicio de crear una extensión desde cero, con una estructura de archivos mucho más simple y básica, y sin utilizar ninguna herramienta de scaffolding.

Tabla de Contenidos

• La extensión más simple
  1. Manifiesto de la extensión
  2. Archivo de entrada de la extensión
• Probando la extensión en local
• En resumen

La extensión más simple

Una extensión en Visual Code requiere como mínimo de dos archivos:

• Manifiesto de la extensión – se define en el package.json del proyecto.
• Archivo de entrada de la entensión – el archivo definido en la propiedad main del package.json (index.js por ejemplo). La función activate exportada desde este archivo es ejecutada cuando la extensión es activada.

Manifiesto de la extensión

Para empezar, crea una carpeta llamada vscode-extension-minimal y dentro un archivo package.json con el siguiente contenido:

{
  "name": "vscode-extension-minimal",
  "displayName": "minimal-extension",
  "description": "Minimal Visual Code extension",
  "version": "0.0.1",
  "publisher": "juanmagarrido",
  "engines": {
    "vscode": "^1.94.0"
  },
  "main": "index.js",
  "contributes": {
    "commands": [
      {
        "command": "minimalExtension.helloWorld",
        "title": "Hello World"
      }
    ]
  },
  "devDependencies": {
    "@types/vscode": "^1.94.0",
    "@types/node": "20.x"
  }
}

Este archivo package.json es el archivo “manifiesto” de la extensión y contiene las propiedades esperadas en un paquete NPM más algunas propiedades extra específicas de las extensiones de Visual Code. La metadata de la extensión se define en este archivo package.json y Visual Code la utiliza para mostrar información sobre la extensión.

En el código de arriba tenemos definidas para nuestro paquete las siguientes propiedades comunes a cualquier paquete NPM de las que Visual Code hace un especial uso:

• name – nombre del paquete
• description – descripción de la extensión
• version – versión de la extensión
  • debe ser actualizada con cada actualización de la extensión en el marketplace
• engines – versiones mínimas de los motores
  • vscode – La versión instalada de Visual Code debe matchear con la versión indicada en esta propiedad
• main – punto de entrada de la extensión. Este es el archivo JS que debe exportar (via exports) la función activate que se ejecuta al instalar la extensión.
• devDependencies – dependencias necesarias en entorno de desarrollo

Además de las propiedades comunes a cualquier paquete NPM, en el código de arriba tenemos también definidas algunas propiedades específicas de las extensiones de Visual Code:

• displayName – título de la extensión
• publisher – el editor que publica de la extensión

Mención aparte merece la propiedad contributes que define los puntos de contribución registrados por la extensión para extender Visual Studio Code. En nuestro código tenemos definida una “contribución” del comando minimalExtension.helloWorld para la Paleta de comandos .

  "contributes": {
    "commands": [
      {
        "command": "minimalExtension.helloWorld",
        "title": "Hello World"
      }
    ]
  },

Este código, añade un nuevo comando “Hello World” a la Paleta de comandos (⇧⌘P).

Para que este comando funcione aún tenemos que definir qué función queremos que se ejecute cuando se invoque este comando. Esto lo haremos dentro de la función activate, exportada desde index.js.

Archivo de entrada de la extensión

index.js es nuestro punto de entrada a la extensión tal y como hemos definido en la propiedad main del `package.json

De este archivo se espera al menos la función activate, que es ejecutada cuando se activa la extensión. Desde esta función podemos, por ejemplo, registrar comandos 😉

Este archivo también puede exportar la función deactivate que se ejecuta cuando la extensión es deshabilitada, aunque se puede dejar sin definir en muchos los casos.

Crea un archivo index.js con el siguiente contenido:

const vscode = require("vscode");

function activate(context) {
  console.log("Congratulations, your minimal extension is now active!");
  const disposable = vscode.commands.registerCommand(
    "minimalExtension.helloWorld",
    () => {
      vscode.window.showInformationMessage(
        "Hello World from minimalExtension.helloWorld!"
      );
    }
  );
  context.subscriptions.push(disposable);
}

module.exports = {
  activate,
};

Esté código define y exporta la función activate que recibe como argumento el objeto context que es una instancia de ExtensionContext y representa el contexto de la extensión.

En la función activate se registra la funcionalidad del comando minimalExtension.helloWorld a través de vscode.commands.registerCommand que devuelve un objeto instancia de Disposable preparado para liberar recursos cuando el plugin se desactive.

El objeto “disposable” devuelto por registerCommand se añade al array context.subscriptions que alberga los recursos “desechables” de la extensión para que puedan ser eliminados cuando la extensión se desactive.

La funcionalidad definida para el comando minimalExtension.helloWorld muestra simplemente un mensaje en el IDE utilizando la función vscode.window.showInformationMessage

Probando la extensión en local

La scaffolding tool recomendada por Visual Code para crear extensiones (Yeoman y su VS Code Extension Generator) genera un launch.json especifico que te permite testear la extensión a través de la propia herramienta de debug de Visual Studio Code ( Run Extension)

Pero una manera más directa de probar nuestra extensión en local, que no requiere configuración adicional, es añadir un link simbolico (symlink) de la carpeta en local que contiene la extension (vscode-extension-minimal en nuestro caso) a la carpeta donde Visual Code guarda tiene las extensiones (~/.vscode/extensions)

Si nuestro proyecto está en ~/PROJECTS/2024/ podriamos hacer:

ln -s ~/PROJECTS/2024/vscode-extension-minimal ~/.vscode/extensions/vscode-extension-minimal

Una vez creado el symlink deberiamos ver en Visual Code el comando Hello World en la Paleta de comandos (⇧⌘P) y este comando debería mostrar el mensaje Hello World from minimalExtension.helloWorld! utilizando la UI de Visual Code.

En resumen

Las ideas basicas que hay que tener en cuenta a la hora de crear una extensión de Visual Code son:

• Toda extensión requiere de un manifiesto de la extensión en un package.json
• Toda extensión requiere de archivo .js de entrada de la entensión definido en la propiedad main del package.json
• El archivo .js de entrada de la extension debe exportar una función activate que es ejecutada al activarse la extension
• Podemos utilizar el VS Code Extension Generator de Yeoman para generar la estructura de un proyecto de extension para Visual Code.