Desarrollo de extensiones modernas para VS Code: conceptos básicos

Según las estadísticas de programación de WakaTime de 2022, Microsoft Visual Studio (VS) Code es actualmente el editor de código fuente más popular. Aunque a menudo se lo clasifica como un editor de código fuente, puede usarse como un entorno de desarrollo integrado (IDE) con todas las funciones. Solo tienes que agregar el conjunto adecuado de extensiones desde Visual Studio Code Marketplace.

El atractivo de VS Code va mucho más allá de su capacidad de ampliación. Aunque actualmente hay muchísimos complementos disponibles, a veces es necesario crear tu propia extensión. Esta serie está diseñada precisamente para eso.

En esta parte de nuestra serie Desarrollo moderno de extensiones para VS Code, hablaremos sobre distintos tipos de extensiones, exploraremos la arquitectura habitual de las extensiones de VS Code y conoceremos algunas prácticas recomendadas para desarrollarlas. Este artículo es una introducción que sienta bases sólidas antes de profundizar en la próxima publicación.

Tipos de extensiones de VS Code

En Visual Studio Code Marketplace, las extensiones y los complementos se agrupan en categorías conocidas como tipos de extensión (según sus distintas funciones y características). La forma más sencilla de acceder a estas categorías es a través de la versión web del Marketplace, aunque también puedes acceder a ellas desde la interfaz de la vista Extensiones de Visual Studio Code con la etiqueta @category: en la barra de búsqueda:

Al explorar esta lista, quizá te preguntes qué significan realmente estas agrupaciones. ¿Qué hace que una extensión sea un formateador y otra un tema?

A continuación, encontrarás algunos de los tipos de extensión más comunes en Visual Studio Code Marketplace y Open VSX Registry, un registro de extensiones de código abierto impulsado por la comunidad para las extensiones de Visual Studio Code (VS Code).

Temas

Con más de 10,000 entradas, los temas son uno de los tipos de extensión más comunes en Visual Studio Code Marketplace. Te permiten cambiar la apariencia de la interfaz de VS Code, incluidos sus paneles, menús y área de texto.

Para buscar todos los complementos de temas, usa el filtro @category:"Themes":

Algunas extensiones de temas son específicas de ciertos componentes o complementos. Por ejemplo, el complemento C/C++ Themes que se mostró antes ofrece un conjunto de temas optimizados visualmente para el desarrollo en C/C++, con mejoras para la colorización semántica.

Los temas de color suelen crearse y configurarse con JSON, y se pueden personalizar fácilmente. Encontrarás las opciones workbench.colorCustomizations y editor.tokenColorCustomizations en Configuración de usuario.

Por lo general, las extensiones de temas tienen una función principalmente estética y son de las más fáciles de crear. Sin embargo, también pueden usarse para mejorar la accesibilidad y la experiencia general de programación.

Extensiones funcionales

Las extensiones funcionales abarcan distintas categorías de extensiones que agregan funciones a VS Code, como linters (@category:"linters"), notebooks (@category:"notebooks"), formateadores (@category:"formatters"), pruebas (@category:"testing"), visualizaciones (@category:"visualization"), lenguajes de programación (@category:"programming languages"), depuradores (@category:"debuggers") e integraciones de administración de la cadena de suministro de software (SCM) (@category:"scm providers").

Sin embargo, como Microsoft y VS Code tienen una cantidad limitada de etiquetas de categoría, algunas categorías quizá no describan con precisión la finalidad de una extensión. Por ejemplo, Snyk Security se clasifica como linter y extensión de lenguaje de programación. Aunque la extensión Snyk Security pueda parecer una herramienta de linting, es mucho más que eso. Su objetivo principal es mejorar la seguridad de tus proyectos de desarrollo de software. Analiza vulnerabilidades de código abierto, vulnerabilidades en el código, problemas de licencias, configuraciones inseguras de infraestructura como código (IaC) y mucho más:

De hecho, los complementos de VS Code como Snyk Security también pueden ayudar a mejorar el desarrollo de extensiones. Snyk puede verificar automáticamente que las dependencias de tu extensión sean seguras, garantizar que tus proyectos estén configurados correctamente y validar la calidad y seguridad de tu código.

Fragmentos y atajos

Las extensiones de fragmentos y atajos te ayudan a personalizar las funciones de asignación de teclas (@category:"keymaps") y fragmentos de código (@category:"snippets") de VS Code. Por ejemplo, REST Client es una extensión multilingüe que genera fragmentos y plantillas para solicitudes HTTP:

Por su parte, Eclipse Keymap agrega las combinaciones de teclas del IDE Eclipse a VS Code. Esto es útil para desarrolladores de Java que usan Eclipse como su IDE principal y quizá quieran migrar a VS Code:

Paquetes

Hay dos tipos de paquetes: paquetes de idiomas (@category:"language packs") y paquetes de extensiones (@category:"extension packs"). Los paquetes de idiomas contienen datos de localización, como traducciones de texto y entradas de teclado. Por ejemplo, el paquete de idioma chino (simplificado) (简体中文) te permite reemplazar el idioma predeterminado de la interfaz de VS Code por chino simplificado.

VS Code también te permite cambiar el idioma de visualización después de instalar el paquete de idioma. Si te interesa ayudar con las traducciones y contribuir a la creación de un paquete de idioma, considera unirte al proyecto de localización de la comunidad de VS Code.

Además, los paquetes de extensiones agrupan varias extensiones en una sola instalación. Suelen seguir un tema o proporcionarte un entorno de desarrollo para empezar rápidamente. Por ejemplo, Python Extension Pack contiene la extensión Python for VS Code, además de Python Environment Manager, Python Indent y autoDocstring - Python Docstring Generator.

Cuando haces clic en el botón Instalar de Python Extension Pack, VS Code instala al mismo tiempo todas las extensiones del paquete que aún no estén instaladas:

En definitiva, los paquetes de extensiones te evitan descargar varias extensiones por separado. Son especialmente útiles para configurar espacios de trabajo para lenguajes que Microsoft no admite directamente (ni oficialmente). También pueden ser una excelente forma de agrupar todas tus extensiones personalizadas de VS Code.

Una vez que hayas decidido qué tipo de extensiones quieres crear, es hora de empezar a definir su estructura.

Arquitectura habitual de las extensiones de VS Code

El host de extensiones de VS Code se encarga de ejecutar las extensiones. Usa el manifiesto de la extensión (package.json) para encontrar la ubicación del punto de entrada de la extensión y ejecutarla según sus eventos de activación. Estos eventos de activación también se declaran en el archivo de manifiesto. Te permiten definir desencadenadores para tus extensiones (por ejemplo, cuando se ejecuta un comando o se selecciona un lenguaje específico).

El archivo package.json también contiene una lista de dependencias esenciales para tu proyecto de extensión. Entre ellas se encuentra el módulo @types/vscode, que te permite conectarte a la API de extensiones de VS Code.

Nota: El módulo @types/vscode reemplaza al paquete `vscode-extension-vscode`, ya que este último está obsoleto y no debe mencionarse en tu archivo package.json ni en ninguna otra parte de tu proyecto.

El manifiesto de la extensión también contiene un conjunto de puntos de contribución. Estos te permiten controlar cómo se invocan las funciones de tu extensión desde VS Code (por ejemplo, puedes configurar un comando o un elemento de menú para que invoque tu extensión).

El archivo de entrada de la extensión contiene su comportamiento principal. Se basa principalmente en el módulo vscode, que siempre debe ser la primera importación de tu extensión:

export function activate(context: vscode.ExtensionContext) {
    //Instructions and Commands
}

El módulo vscode contiene la API de VS Code, que te ofrece una colección de interfaces para ampliar las funciones de VS Code. Entre ellas está la interfaz de extensión, que incluye las funciones que necesitas para administrar, configurar y crear extensiones.

El método activate de la interfaz de extensión te permite definir qué hace tu extensión cuando se activa, y es el siguiente paso en el archivo de entrada:

export function activate(context: vscode.ExtensionContext) {
    //Instructions and Commands
}

Este código funciona de forma similar a un controlador de eventos: declara un conjunto de comandos que se ejecutan cuando ocurre un evento. También puedes incluir una llamada y una exportación para la función deactivate:

export function deactivate(context: vscode.ExtensionContext) {}

Esto te permite realizar tareas de limpieza después de la activación o ejecución de tu extensión.

Los archivos de entrada pueden escribirse en TypeScript o JavaScript; sin embargo, se recomienda usar el primero. En cualquier caso, los proyectos de extensiones en TypeScript y JavaScript deben incluir un archivo config, ya que indica cuál es la carpeta raíz del proyecto y ayuda al compilador a encontrarla. El archivo config también incluye varias propiedades y opciones del compilador. Debes usar el archivo tsconfig.json para tus proyectos de TypeScript y los archivos jsconfig.json para tus proyectos de JavaScript.

El directorio de tu proyecto de extensión también contiene dos archivos adicionales dentro de la carpeta .vscode:

1. tasks.json

tasks.json define un conjunto de tareas específicas de una carpeta, un proyecto o un espacio de trabajo que VS Code debe ejecutar cuando se activen. Estas tareas consisten principalmente en instrucciones y configuraciones para compilar el proyecto. Por ejemplo, como VS Code compila sus extensiones con administradores de paquetes como npm, el archivo tasks.json de tu proyecto de extensión suele hacer referencia a ellos, así:

	"type": "npm",
	"script": "watch",
	"problemMatcher": "$ts-webpack-watch",
	"isBackground": true,
	"presentation": {
		"reveal": "never",
		"group": "watchers"
	},
	"group": {
		"kind": "build",
		"isDefault": true
	}

Este ejemplo de tasks.json define un observador de compilación que supervisa los procesos de compilación de tu proyecto para detectar errores y advertencias. Este script se basa principalmente en npm para ejecutar y empaquetar el comparador de problemas ts-webpack-watch.

2. launch.json

launch.json define cómo debe ejecutar (o depurar) VS Code tus extensiones una vez compiladas. Incluye información sobre el entorno de ejecución que usa tu extensión:

"configurations": [
    {
        "name": "Run Extension",
        "type": "extensionHost",
        "request": "launch",
        "args": [
            "--extensionDevelopmentPath=${workspaceFolder}"
        ],
        "outFiles": [
            "${workspaceFolder}/dist/**/*.js"
        ],
        "preLaunchTask": "${defaultBuildTask}"
    },
]

Este ejemplo de launch.json es una configuración que define las instrucciones para iniciar una extensión de VS Code. Incluye la ubicación del código fuente y de los ejecutables empaquetados.

Un directorio básico de proyecto de extensión se ve así:

Project Parent Folder
├── .vscode
│   ├── launch.json     
│   └── tasks.json                
├── src
│   └── extension.ts    //Extension Entry File
├── package.json       	//Manifest
├── tsconfig.json  

Prácticas recomendadas para desarrollar extensiones de VS Code

Debido a la estructura de las extensiones de VS Code, es posible que los desarrolladores pasen por alto algunos aspectos fundamentales. Sin embargo, si quieres crear extensiones de forma eficaz, debes seguir ciertos principios, entre ellos estas prácticas recomendadas:

Prueba tus extensiones a fondo

Si planeas publicar tus extensiones en cualquiera de las instancias compatibles de Visual Studio Code Marketplace, debes evitar agregar código defectuoso. Esto significa que tienes que asegurarte de que tus extensiones estén bien probadas mediante distintas técnicas de evaluación de software, como pruebas unitarias (cuando corresponda) y pruebas rigurosas de escenarios.

No es obligatorio usar complementos o bibliotecas externos para probar tus extensiones de VS Code, pero VS Code ofrece mecanismos y herramientas para realizar pruebas de integración. En particular, el host de desarrollo de extensiones te permite probar tus extensiones en un entorno separado de la instancia oficial de VS Code.

No olvides que los usuarios califican y reseñan las extensiones en Visual Studio Code Marketplace, por lo que es importante probarlas a fondo. No pongas en riesgo la reputación de tu marca al implementar un producto con errores o sin protección.

Almacena los datos confidenciales de la forma más segura posible

VS Code ha evolucionado la forma en que guarda y almacena los datos de usuario. Antes de la introducción de VS Code 1.53, la información de los usuarios se gestionaba mediante la interfaz ExtensionContext; sin embargo, no era una solución eficiente.

Actualmente, la mejor forma de administrar información confidencial en VS Code es usar su utilidad SecretStorage.

Sigue las pautas de experiencia de usuario (UX) de Microsoft para VS Code

Microsoft cuenta con un conjunto de pautas de experiencia de usuario (UX) que ayudan a garantizar que las extensiones sean coherentes con la arquitectura y los estándares de VS Code. Se recomienda familiarizarte con todas estas pautas, pero presta especial atención a las que se relacionan con la funcionalidad de tu extensión.

Por ejemplo, aunque tu extensión no implemente componentes visuales sofisticados, como vistas web, sus funciones principales podrían ser lo suficientemente complejas como para justificar un recorrido guiado. Crear un recorrido guiado, es decir, un tutorial interactivo de inicio rápido, ayuda a los nuevos usuarios a familiarizarse con las funciones de tu extensión. Como buena práctica, los desarrolladores deben procurar que su software esté bien documentado, tanto en el código como en las instrucciones de uso.

Además, procura que el proceso para comenzar sea lo más sencillo posible. Esto significa agregar las imágenes y las señales visuales necesarias. Microsoft recomienda usar archivos SVG con el color del tema de la API de VS Code.

Las mejores extensiones de VS Code se integran tan perfectamente en la interfaz que es casi imposible distinguirlas de las funciones principales de VS Code.

Empaqueta tus extensiones

Como VS Code pertenece a Microsoft, es fácil olvidar que VS Code (y sus variantes) es una aplicación multiplataforma. Además de Windows, VS Code está disponible para las versiones más recientes de macOS y las distribuciones de Linux basadas en Debian y Red Hat. Esto significa que tus extensiones deben seguir los principios fundamentales de VS Code y funcionar en todas las plataformas compatibles con VS Code.

La mejor manera de lograrlo es mediante el empaquetado. Microsoft recomienda usar esbuild para empaquetar tus extensiones de VS Code por su velocidad y eficiencia. webpack es otra buena alternativa.

Además, a medida que aumenta la adopción de la plataforma como servicio (PaaS), es importante asegurarte de que tus extensiones sean compatibles con Visual Studio Code para la Web. Solo las extensiones empaquetadas pueden funcionar sin problemas con esta versión web.

Además, tanto esbuild como webpack pueden minimizar tu código. La minificación elimina texto innecesario y cambia los nombres de los miembros (es decir, los métodos/funciones y las variables). Por desgracia, esto puede cambiar el comportamiento de parte de tu código. Por ejemplo, se sabe que el código fuente que usa las funciones Function.prototype.name y toString() puede dejar de funcionar correctamente después de la minificación.

La realidad es que muchos minificadores tienen estas limitaciones. Si sospechas que el minificador de webpack está causando problemas en tu código, puedes desactivarlo temporalmente hasta identificar la causa.

En cambio, esbuild no minimiza el código a menos que se lo indiques explícitamente [con la opción --minify flag], lo que te da más control sobre el proceso de minificación.

Los desarrolladores también deben asegurarse de que sus dependencias críticas estén optimizadas para el empaquetado. Por desgracia, si intentas empaquetar dependencias dinámicas, es probable que el proceso falle. Estas dependencias deben declararse como estáticas o excluirse mediante externals. Los desarrolladores pueden usar dependency-check de Snyk para facilitar este proceso.

Protege tus extensiones

Visual Studio Code Marketplace analiza activamente las extensiones nuevas y sus actualizaciones para detectar contenido malicioso. Además, los usuarios de VS Code pueden denunciar extensiones inseguras mediante el enlace Report Abuse. Sin embargo, a pesar de estas medidas preventivas, Visual Studio Code Marketplace no está libre de contenido malicioso.

Una investigación publicada por Snyk descubrió varias extensiones vulnerables en Visual Studio Code Marketplace que podían exponer los sistemas a distintos tipos de ataques, como la falsificación de solicitudes del lado del servidor y el recorrido de directorios.

Muchas de estas extensiones no se crean con intención maliciosa; simplemente, los desarrolladores no priorizan la seguridad porque desconocen los riesgos o no tienen tiempo. Las medidas de seguridad deben considerarse e implementarse desde las primeras etapas del ciclo de desarrollo.

Puede parecer una tarea abrumadora, pero gracias a herramientas como Snyk, no tienes que definir tus propias prácticas ni verificaciones de seguridad. Snyk ofrece un plan gratuito, así que cualquier desarrollador puede usar e integrar sus funciones principales.

Además, Snyk sabe que el desarrollo de software moderno avanza a un ritmo acelerado. Al permitirte vincular tu perfil de GitHub o Google, Snyk facilita el registro de una cuenta nueva. Además, no tienes que usar la interfaz web de Snyk para autenticarte ni acceder a sus funciones. Puedes usar la Snyk CLI o alguna de sus muchas integraciones, incluida la extensión para VS Code:

No solo puede analizar tu código para detectar problemas de seguridad, sino también los módulos y las bibliotecas de los que depende. La interfaz de usuario de la extensión de Snyk para VS Code es una versión reducida de la interfaz web. Se integra con muchos elementos de la interfaz de VS Code, como los diagnósticos, la vista de problemas/el panel y el editor. Con ella, puedes ver qué líneas de tu código exponen tu extensión a posibles ataques:

Como algunos de tus módulos o dependencias podrían quedar aislados en un entorno de pruebas una vez publicada tu extensión, no siempre es necesario protegerlos manualmente. Por ejemplo, puedes usar el panel de análisis de Snyk para ignorar las líneas o los archivos que consideres irrelevantes para la seguridad de tu proyecto:

De forma predeterminada, la extensión de Snyk para VS Code supervisa y analiza automáticamente tu proyecto mientras lo creas. Sin embargo, también puedes configurarla para que se ejecute cuándo y cómo quieras:

En última instancia, tú decides cómo integrar la extensión en tu flujo de trabajo.

Conclusión

Esta guía te ofrece todo lo que necesitas saber para empezar a desarrollar extensiones de VS Code. En ella, exploraste la estructura básica de estas extensiones, incluido cómo se conecta el manifiesto de la extensión con el archivo de entrada. Además, aprendiste algunas buenas prácticas para comenzar.

Lo más importante es asegurarte de que tu extensión cumpla con los estándares de UX de Microsoft y de que sea segura. La mejor manera de verificar que tus extensiones usan código fuente de alta calidad y dependencias seguras es Snyk, la plataforma de seguridad diseñada para desarrolladores. Snyk ofrece una impresionante lista de integraciones, entre ellas un complemento para VS Code que permite realizar y automatizar verificaciones de calidad y seguridad en tus proyectos.