Tu primera extensión de Chrome: 15 minutos para hacer funcionar un Hello World
💡 Resumen en una frase: una carpeta, tres archivos y el modo de desarrollador de Chrome; en 15 minutos, el navegador muestra el Hello World de tu propia extensión.
La lección anterior C1 Qué es una extensión de navegador ya cubrió los conceptos: una extensión es HTML/CSS/JS más un manifest.json. Esta lección es práctica: el paso más sólido de la introducción a las extensiones de chrome no es memorizar diez términos más, sino hacer que el navegador muestre realmente tu propia extensión.
No te saltes estos 15 minutos, aunque pienses dejar que la IA escriba todo el código. Cargar localmente, recargar y ver el popup son tres acciones que siempre tendrás que hacer tú mismo; el Hello World sirve para convertirlas en memoria muscular.
Qué podrás hacer al terminar
- Crear una extensión que de verdad se instala en Chrome: al hacer clic en el icono de la barra de herramientas, aparece «Hello Extensions»
- Escribir letra por letra el ejemplo mínimo oficial de manifest.json y explicar para qué sirve cada campo
- Completar la carga local en tres pasos:
chrome://extensions→ modo de desarrollador → Load unpacked - Fijar la extensión a la barra de herramientas con Pin, lista para usar en cualquier momento
- Recordar la regla de recarga: qué archivos exigen recargar la extensión y cuáles no
Tu situación actual
- «He memorizado un montón de términos de extensiones: manifest, MV3, popup... pero no he hecho correr ni una línea de código en el navegador»
- «La IA ya escribió el código, pero no sé dónde van estos archivos ni cómo hacer que Chrome los reconozca»
- «Copié tutoriales antiguos de internet y Load unpacked da error en cuanto hago clic, sin saber dónde está el fallo»
Cuándo usar esta técnica
Cuando necesitas:
- Convertir «hacer una extensión» de idea en realidad: primero haz funcionar la versión mínima y luego añade funciones
- Verificar que la cadena de desarrollo funciona: poder crear archivos, cargarlos y ver el popup, superando las tres pruebas
- Darle a los requisitos de la IA un punto de partida real: primero el Hello World funciona, y en la próxima lección la IA construye encima
Y no quieres:
- Estudiar de entrada todos los campos del manifest: la próxima lección C3 los desglosa uno por uno
- Tocar el empaquetado, la publicación o la revisión: eso es asunto de C6
- Instalar ningún entorno de desarrollo: basta una carpeta + el modo de desarrollador que Chrome trae de fábrica
🎒 Preparativos antes de empezar
- Haber completado C1 Qué es una extensión de navegador, saber que extensión = HTML/CSS/JS + manifest.json, y que ahora solo escribimos MV3
- Tener el navegador Chrome instalado en tu ordenador
- Una herramienta para crear y editar archivos de texto (el Bloc de notas del sistema sirve; un editor de código como VS Code es más cómodo)
- 15 minutos
Idea central
La forma mínima de una extensión de Chrome es una carpeta con tres archivos:
| Archivo | Función | Quién lo usa |
|---|---|---|
manifest.json | El DNI + manual de la extensión: cómo se llama, qué versión tiene, qué hace el icono al pulsarlo | Chrome lo lee |
hello.html | La pequeña página que se abre al hacer clic en el icono de la barra de herramientas | El usuario la ve |
hello_extensions.png | El icono de la barra de herramientas (se puede omitir; Chrome asignará un icono genérico) | El usuario lo ve |
El principio de funcionamiento en una frase: Chrome reconoce tu extensión gracias a manifest.json; dentro del manifest, action.default_popup le dice a Chrome «al hacer clic en el icono de la barra de herramientas, abre hello.html».
Antes de empezar, establecemos dos reglas:
manifest_versionescribe solo 3. La documentación oficial dice claramente que el único valor admitido es 3; no copies el 2 de los tutoriales antiguos (C1 explicó que MV2 está totalmente deshabilitado; las reglas de los campos se detallan en C3 explicación detallada).- El modo de desarrollador ≠ publicación. El modo de desarrollador + Load unpacked es solo un interruptor que «permite instalar una carpeta local en el navegador»; publicar en la Chrome Web Store requiere registro de desarrollador y revisión, y es otro camino (ver C6).
💡 ¿Hay que escribirlo a mano en esta lección?
Los tres archivos son tan pequeños que escribirlos a mano lleva pocos minutos; recomendamos hacerlo tú la primera vez, porque en este paso es fácil fallar por una comilla o un nombre de campo; al escribirlo a mano una vez, después sabrás qué revisar del código que escriba la IA. A partir de la próxima lección los archivos serán cada vez más numerosos, y ese será el terreno de la IA.
Hazlo conmigo
Paso 1: crea la carpeta de la extensión
Por qué: un plugin es «unos archivos en una carpeta»; primero hay que darles un hogar.
Operación: crea una carpeta nueva en el escritorio (o en cualquier lugar que puedas encontrar) y ponle el nombre hello-extensions.
Si quieres comparar con el resultado final, el código fuente del ejemplo oficial está en GitHub: el directorio functional-samples/tutorial.hello-world del repositorio GoogleChrome/chrome-extensions-samples. Pero en esta lección se recomienda crearlo tú mismo — en total son solo tres archivos.
Deberías ver: una carpeta vacía.
Paso 2: escribir manifest.json — el primer archivo para iniciarte en los plugins de Chrome
Por qué: Chrome solo reconoce manifest.json. Sin él, esta carpeta es simplemente una carpeta normal.
Operación: crea manifest.json dentro de la carpeta, copiando el contenido literalmente del ejemplo oficial:
{
"name": "Hello Extensions",
"description": "Base Level Extension",
"version": "1.0",
"manifest_version": 3,
"action": {
"default_popup": "hello.html",
"default_icon": "hello_extensions.png"
}
}Qué hace cada uno de los seis campos:
| Campo | Valor en esta lección | Qué hace |
|---|---|---|
name | Hello Extensions | Nombre del plugin, se muestra en la página de extensiones y otros lugares |
description | Base Level Extension | Descripción en una frase |
version | 1.0 | Número de versión (enteros separados por puntos, de 1-4 segmentos) |
manifest_version | 3 | Declara el uso de MV3 — el único valor admitido |
action.default_popup | hello.html | Al hacer clic en el ícono de la barra de herramientas se abre esta página emergente |
action.default_icon | hello_extensions.png | El ícono de la barra de herramientas usa esta imagen |
⚠️ Dos detalles
- En JSONno se pueden escribir comentarios — tanto
//como/* */hacen que el análisis falle directamente. Si quieres tomar notas, escríbelas fuera del archivo. - ¿No quieres preparar un ícono? Elimina toda la línea de
"default_icon"y Chrome le dará automáticamente al plugin un ícono genérico.
Deberías ver: un manifest.json dentro de la carpeta.
- Pequeña comprobación: vuelve a abrirlo con el editor y confirma que
"manifest_version": 3, con cada comilla en pares
Paso 3: escribir hello.html y añadir un ícono
Por qué: el archivo al que apunta default_popup debe existir realmente, para que al hacer clic en el ícono haya algo que abrir.
Operación: crea hello.html, copiando el contenido del ejemplo oficial:
<html>
<body>
<h1>Hello Extensions</h1>
</body>
</html>Para el ícono, elige una de dos opciones:
- Opción A (siguiendo el ejemplo oficial): descarga el ícono de ejemplo desde la página del tutorial oficial, renómbralo como
hello_extensions.pngy ponlo en la carpeta — el nombre del archivo debe coincidir exactamente con lo escrito endefault_icon. - Opción B (más fácil): si en el paso anterior eliminaste
default_icon, sáltalo directamente; Chrome dará un ícono genérico.
Deberías ver: dos o tres archivos en la carpeta: manifest.json, hello.html, más el ícono (si elegiste la opción A).
Paso 4: activar el modo de desarrollador de Chrome y cargar localmente con Load unpacked
Por qué: por defecto, Chrome solo instala plugins de la tienda. El modo de desarrollador es el interruptor que «permite la instalación local», y Load unpacked se encarga de instalar tu carpeta en el navegador.
Operación (tres pasos oficiales):
- Escribe
chrome://extensionsen la barra de direcciones de una pestaña nueva y pulsa Enter para abrir la página de gestión de extensiones. Otras dos entradas: botón de rompecabezas de la barra de herramientas → Manage Extensions; o menú de Chrome → More Tools → Extensions. - Activa el interruptor Developer mode (modo de desarrollador).
- Haz clic en Load unpacked y selecciona tu carpeta del plugin en el cuadro de selección de archivos.
Nota: la carpeta que elijas debe contener directamente el manifest.json — la documentación oficial exige que esté en el directorio raíz del plugin; si lo envuelves en una subcarpeta adicional, Chrome no lo encontrará.
Deberías ver: Hello Extensions aparece en la lista de la página de extensiones, con el mensaje The extension has been successfully installed. (el plugin se ha instalado con éxito); si no proporcionaste un ícono, Chrome asignó automáticamente uno genérico.
- Pequeña comprobación: la tarjeta de Hello Extensions se muestra normalmente, sin que aparezca ningún diálogo de error
Paso 5: fijar en la barra de herramientas y abrir tu primera ventana emergente
Por qué: los plugins cargados localmente están ocultos por defecto en el menú del rompecabezas y hay que hacer clic extra cada vez; fijarlos es lo cómodo.
Operación: haz clic en el botón de rompecabezas de la barra de herramientas, busca Hello Extensions y haz clic en el ícono de pin (Pin) que está a su lado para fijarlo en la barra de herramientas. Luego haz clic en el ícono de este plugin en la barra de herramientas.
Deberías ver: se abre una pequeña ventana emergente que dice Hello Extensions — tu primer plugin de Chrome ya funciona.
Paso 6: modificar el código y aprender a recargar el plugin
Por qué: el plugin no lee automáticamente los archivos que has modificado; la mayoría de los cambios requieren una recarga manual para surtir efecto — este es el punto que los principiantes más suelen malinterpretar como «la IA escribió mal».
Operación: cambia name en manifest.json a "Hello Extensions of the world!" y guarda. Vuelve a chrome://extensions y haz clic en el ícono de recarga junto al interruptor on/off de la tarjeta del plugin.
Deberías ver: el nombre del plugin cambia a Hello Extensions of the world!. Sin hacer clic en recargar, seguirá con el nombre antiguo.
La tabla oficial de reglas de recarga, memorízala desde ahora:
| Qué se cambió | ¿Hay que recargar el plugin? |
|---|---|
| manifest | Sí |
| Service worker | Sí |
| Content scripts | Sí (y además hay que recargar la página web correspondiente) |
| Ventana emergente (popup) | No |
| Página de configuración (Options page) | No |
| Otras páginas HTML del plugin | No |
El complemento de esta lección solo tiene dos tipos de archivos: manifest y popup. La regla es muy simple: si cambias el manifest, ve a la página de extensiones y haz clic en actualizar; si cambias hello.html, no hace falta actualizar—vuelve a abrir el popup y verás el nuevo contenido.
Punto de control ✅
- En
chrome://extensionsla tarjeta de Hello Extensions se muestra correctamente, sin errores - El complemento está fijado (Pin) en la barra de herramientas y al hacer clic en el icono se abre Hello Extensions
- Después de cambiar
name, fuiste a la página de extensiones y hiciste clic en el icono de actualizar, y el nombre cambió - Puedes explicar la regla de recarga: manifest, service worker y content scripts requieren actualizar; el popup y otros HTML no
- Sabes que el modo de desarrollador es solo un interruptor para la «carga local»; para publicar hay que pasar por registro + revisión (C6)
Advertencia sobre errores comunes
❌ Escribir comentarios en manifest.json
JSON no admite comentarios. Si escribes // o /* */, el manifest falla al analizarse—al cargarlo localmente aparece directamente un cuadro de diálogo de error; la documentación oficial también aclara que al empaquetar y subir, un JSON con comentarios dará el error Cannot parse the manifest.
Forma correcta: escribe los comentarios y notas fuera del archivo; si dudas del significado de un campo, consulta la referencia rápida de campos C3.
❌ Copiar tutoriales antiguos y escribir manifest_version como 2
Hay muchísimos tutoriales en internet escritos en la era MV2. Ahora manifest_version el único valor admitido es 3, y los complementos MV2 ya están completamente deshabilitados en Chrome—copiarlos equivale a trabajar en vano.
Forma correcta: antes de empezar, comprueba que esta línea sea "manifest_version": 3; si ves un tutorial que enseña MV2, ciérralo directamente.
❌ Cambiar el código sin actualizar el complemento y pensar «la IA se equivocó»
Si no actualizas después de cambiar el manifest, el service worker o los content scripts, el navegador sigue ejecutando el código antiguo—pensarás erróneamente que el código tiene un problema y harás que la IA modifique una y otra vez un fragmento de código totalmente correcto.
Forma correcta: al terminar de cambiar, repasa primero la tabla de reglas de recarga del paso 6: lo que requiere actualización, actualízalo desde la página de extensiones con el icono de actualizar; si cambiaste el popup, no hace falta. Si sigue fallando, ve a buscar los registros en C5.
❌ Creer que activar el modo de desarrollador ya cuenta como «publicado»
El modo de desarrollador es solo un interruptor que permite la instalación local; en ese momento el complemento solo lo puedes usar tú. Para publicarlo en la Chrome Web Store hay que pasar por el registro de desarrollador (pagando una tarifa de registro única, cuyo monto se rige por la página de pago real del panel del desarrollador) y la revisión.
Forma correcta: una vez que funcione localmente, sigue el flujo completo de publicación en C6 para registrarte, empaquetar y enviar a revisión.
Técnicas avanzadas (opcional)
🚀 Añade una línea de registro al popup y adelanta el contacto con la depuración. Añade una línea <script src="popup.js"></script> antes de </body> en hello.html, crea el nuevo archivo popup.js y escribe console.log("This is a popup!"). Abre el popup → clic derecho en el popup → Inspect → panel Console, y podrás ver este registro. Cuando escribas código erróneo a propósito (por ejemplo, faltando una comilla), aparecerá el botón Errors en la página de extensiones; ábrelo para ver los detalles. Dónde están los registros del service worker y de los content scripts: C5 tiene el mapa completo.
La estructura del proyecto es libre: la documentación oficial dice claramente que la forma de organizarlo es libre; el único requisito estricto es que manifest.json esté en el directorio raíz del complemento. Si usas TypeScript, instalar el paquete npm chrome-types te da autocompletado de la Chrome API—se actualiza automáticamente con el código fuente de Chromium, y la documentación oficial recomienda actualizarlo con frecuencia.
Resumen de la lección
✅ Primera lección de introducción a los complementos de Chrome, ya has:
- Creado y ejecutado tu primer complemento: carpeta +
manifest.json+hello.html; al hacer clic en el icono se abre Hello Extensions - Dominado los 3 pasos de la carga local:
chrome://extensions→ Developer mode → Load unpacked - Sabes fijar (Pin) el complemento en la barra de herramientas para usarlo en cualquier momento
- Recuerdas la regla de recarga: manifest, service worker y content scripts requieren actualizar tras cambiarlos; el popup no
- Sabes cuál es la primera entrada a los registros: clic derecho en el popup → Inspect
Repaso de los campos de configuración clave:
| Campo | Valor de esta lección | Descripción |
|---|---|---|
manifest_version | 3 | Único valor admitido; no escribas 2 |
name | Hello Extensions | Nombre del complemento |
description | Base Level Extension | Descripción |
version | 1.0 | Número de versión, enteros separados por puntos en 1-4 segmentos |
action.default_popup | hello.html | Página que se abre al hacer clic en el icono |
action.default_icon | hello_extensions.png | Icono; si no se especifica, se usa un icono genérico |
Avance de la próxima lección
En la próxima lección C3 análisis detallado de manifest.json: desmontaremos campo por campo este manual mínimo. Aprenderás:
- Las reglas de los tres campos obligatorios:
namecon máximo de 75 caracteres, y los detalles de formato deversion - Campos imprescindibles para publicar:
description(máximo de 132 caracteres),icons - Cómo escribir campos opcionales de alta frecuencia como
content_scripts,permissions - Por qué, tras subir a la tienda, corregir una sola letra errónea exige subir el número de versión y volver a empaquetar
Cuando estés listo, entra en C3 →