< Home

About

, ,

Cómo contribuir a Gutenberg: scripts NPM y configuración local

, , , , ,

Con el Contributor Day de WordCamp Valencia 2025 acercándose, he estado organizando mis ideas sobre cómo ayudar a quienes contribuyen por primera vez a Gutenberg. Esta guía comenzó como preparación para la mesa de contribuidores Core, pero esta información puede ser igual de útil para cualquier persona que quiera contribuir al editor de bloques de WordPress, sobre todo si es la primera vez.

Ya sea que estés en un Contributor Day o que te sumerjas por tu cuenta, esta guía te guiará a través de la configuración esencial y el flujo de trabajo para contribuir a Gutenberg.

Tabla de contenidos

  1. Herramientas básicas
    1. Node.js y npm
    2. Docker Desktop
    3. Git y GitHub
    4. GitHub CLI (opcional pero útil)
  2. La copia local (de trabajo) de Gutenberg
    1. Hacer fork del repositorio
    2. Clonar tu fork
    3. Mantente sincronizado
  3. El entorno local de desarrollo
    1. Instalando dependencias
    2. Iniciando WordPress con wp-env
  4. Los scripts npm esenciales
    1. Scripts de desarrollo core
    2. Scripts de calidad de código
    3. Scripts de testing
  5. ¿Qué hace npm start?
  6. Un flujo de trabajo práctico de desarrollo
    1. Configura tu entorno de desarrollo
    2. Dónde hacer cambios
    3. Lista de verificación pre-commit
    4. Encontrando issues y trabajando en ellas
    5. Creando tu pull request
    6. Solucionando problemas comunes
  7. Consejos para contribuir
  8. Recursos y comunidad
  9. Referencia rápida de comandos
  10. Notas finales

Herramientas básicas

Antes de empezar a contribuir a Gutenberg, necesitarás estas herramientas instaladas. La mayoría son estándar para desarrollo JavaScript, pero hay requisitos específicos de WordPress que vale la pena mencionar.

Node.js y npm

Gutenberg actualmente requiere Node.js v20 (Active LTS) y npm v10. Recomiendo usar nvm para gestionar las versiones de Node: es super útil cuando cambias entre proyectos con diferentes requisitos.

nvm install 20
nvm use 20

Docker Desktop

Tener Docker simplifica bastante el lanzar un entorno local para los diferentes proyectos de WordPress. El equipo de Gutenberg construyó @wordpress/env alrededor de Docker, y aunque existen alternativas como Local o MAMP, te perderías la integración perfecta que hace el desarrollo tan fluido.

Descarga Docker Desktop e inícialo antes de comenzar. Ten en cuenta que las descargas iniciales de imágenes pueden tomar algo de tiempo.

Git y GitHub

Necesitarás una cuenta de GitHub y Git configurado localmente. La documentación del flujo de trabajo Git en el Block Editor Handbook es bastante completa por si necesitas más detalles.

GitHub CLI (opcional pero útil)

Esto no es imprescindible pero una vez que descubras comandos como gh pr checkout para revisar pull requests, se volverá esencial en tu flujo de trabajo.

# macOS
brew install gh

# Windows/Linux
# Ver: https://cli.github.com/

La copia local (de trabajo) de Gutenberg

Aquí se aplica el flujo de trabajo estándar de código abierto: fork, clonar y agregar upstream. Este sería el proceso completo:

1. Hacer fork del repositorio

  1. Navega a github.com/WordPress/gutenberg
  2. Haz clic en “Fork” arriba a la derecha
  3. GitHub crea tu copia personal del repo bajo tu usuario

2. Clonar tu fork

git clone git@github.com:TU_USUARIO/gutenberg.git
cd gutenberg
git remote add upstream https://github.com/WordPress/gutenberg.git

El comando git remote add upstream conecta tu fork personal con el repositorio original de WordPress. Así tendrás dos referencias: origin (tu fork) donde haces cambios, y upstream (el repo oficial) de donde traes las actualizaciones. Sin esta conexión, tu fork quedaría desactualizado rápidamente.

3. Mantente sincronizado

Ahora que tienes upstream configurado, puedes traer los últimos cambios del proyecto principal. Gutenberg recibe docenas de commits diarios, así que es importante mantener tu fork actualizado:

git fetch upstream
git merge upstream/trunk

El entorno local de desarrollo

Una vez tengas instaladas las herramientas basicas y tengas tu copia local de gutenberg debidamente configurada, llega el momento de preparar tu entorno local para contribuir a Gutenberg. A diferencia de la configuración manual clásica de WordPress —donde tenías que instalar Apache, MySQL y PHP por separado— el proyecto ha simplificado radicalmente este proceso. Gracias a las herramientas que utilizan Docker, obtendrás una instalación de WordPress lista para desarrollar en unos pocos pasos y sin dolores de cabeza, todo completamente automatizado.

Instalando dependencias

Siempre usa npm ci en lugar de npm install:

npm ci

El comando ci asegura que obtengas exactamente las mismas versiones de paquetes que otros contribuidores, esto previene esas frustrantes situaciones de “funciona en mi máquina”.

A diferencia de npm install que puede actualizar versiones según los rangos permitidos (ej: ^1.2.3 podría instalar 1.3.0), npm ci instala exactamente lo que está en package-lock.json. Además, es más rápido, borra node_modules antes de instalar, y falla si hay discrepancias entre archivos – garantizando que todos trabajen con el mismo entorno.

Iniciando WordPress con wp-env

El paquete @wordpress/env proporciona una instalación completa de WordPress con un solo comando:

npm run wp-env start

La primera ejecución descarga imágenes de Docker (10-15 minutos), pero los inicios posteriores toman segundos. Obtendrás:

  • WordPress en http://localhost:8888
  • Admin en http://localhost:8888/wp-admin/
  • Usuario: admin
  • Contraseña: password

Gestionando tu entorno:

npm run wp-env stop     # Pausar cuando termines
npm run wp-env destroy  # Reinicio completo si es necesario

Los scripts npm esenciales

El repositorio de Gutenberg contiene más de 100 scripts npm. Aquí comento los que considero que realmente importan para los contribuidores.

Scripts de desarrollo core

Estos son los scripts fundamentales que usarás durante tu sesión de desarrollo. Son los comandos que mantendrás ejecutándose mientras trabajas en tus cambios y que te permiten ver el resultado de tu código en tiempo real.

npm start (alias: npm run dev)

Tu comando principal de desarrollo. Compila todos los paquetes y observa cambios, reconstruyendo automáticamente cuando guardas archivos. Mantén esto ejecutándose en una terminal mientras trabajas.

npm start

Referencia: package.json#L230

npm run build

Crea compilaciones optimizadas listas para producción. Úsalo para pruebas finales o crear un ZIP del plugin.

npm run build

Referencia: package.json#L186

Scripts de calidad de código

WordPress mantiene estándares de código muy específicos y estos scripts te ayudan a cumplirlos automáticamente. Ejecutar estos comandos antes de hacer commit te ahorrará tiempo en la revisión de código y garantizará que tu contribución siga las convenciones del proyecto.

npm run format

Formatea automáticamente el código según los estándares de WordPress usando Prettier. Ejecuta antes de hacer commit para evitar discusiones de estilo en la revisión de código.

npm run format

npm run lint:js y npm run lint:css

ESLint para JavaScript/TypeScript y Stylelint para CSS. Ambos tienen variantes de auto-corrección:

npm run lint:js:fix
npm run lint:css:fix

Scripts de testing

En el repo de Gutenberg tenemos disponibles varios scripts para lanzar los tests. Ten en cuenta que para la mayoría de estos comandos, necesitas tener WordPress ejecutándose correctamente con wp-env (es decir, que ya hayas corrido npm run wp-env start). Si el entorno de WordPress no está activo o configurado, estos scripts podrían fallar, ya que dependen del entorno Docker para ejecutar las pruebas dentro de la instancia local de WordPress.

Los scripts de testing cubren distintos niveles:

  • Pruebas unitarias de JavaScript (npm run test:unit): Ejecutadas principalmente con Jest, verifican que funciones y componentes JavaScript hagan lo esperado.
  • Pruebas end-to-end (E2E) (npm run test:e2e): Usan Playwright para simular interacciones reales en el editor como si fueras un usuario.
  • Pruebas unitarias de PHP (npm run test:unit:php): Utilizan PHPUnit dentro del contenedor Docker para asegurar que el código PHP funcione correctamente.

npm run test:unit

Ejecuta tests de Jest. Durante el desarrollo, prefiero el modo watch:

npm run test:unit:watch

Para ejecutar tests específicos, usa el parámetro --testPathPattern:

npm run test:unit -- --testPathPattern packages/components/src/button

Actualiza snapshots después de cambios intencionales:

npm run test:unit -- --updateSnapshot

npm run test:e2e

Tests end-to-end usando Playwright simulan interacciones reales del usuario:

npm run test:e2e

Para ejecutar un archivo de test específico:

npm run test:e2e -- site-editor/title.spec.js

Con navegadores específicos:

npm run test:e2e -- --project=webkit --project=firefox

Modo debug para solucionar problemas:

npm run test:e2e:debug

npm run test:unit:php

Tests unitarios de PHP via PHPUnit en el contenedor Docker:

npm run test:unit:php

Para ejecutar tests específicos con PHPUnit, puedes usar filtros:

npm run test:unit:php -- --filter Block_Template_Tests

¿Qué hace npm start?

npm start es el script principal que tendrá que tener en marcha para contribuir. Cuando ejecutas npm start, se dispara npm run dev, que ejecuta node ./bin/dev.mjs. Esto pone en marcha una serie de procesos automatizados y coordinados:

  1. Limpiando compilaciones anteriores – Elimina artefactos de build/ y node_modules/.cache/
  2. Compilando workspaces – Compila cada uno de los 100+ paquetes según su configuración
  3. Validación de TypeScript – Asegura versiones consistentes de TypeScript entre contribuidores
  4. Generación de tipos – Crea archivos .d.ts para mejor soporte del IDE
  5. Validación de tipos – Verifica que los tipos generados sean válidos (crucial en un monorepo)
  6. Empaquetado de vendors – React, ReactDOM y otras dependencias compartidas se empaquetan una vez y se reutilizan
  7. Compilación de paquetes – Tres fases:
  • Transpilación: JavaScript moderno → código compatible con navegadores
  • Empaquetado: Archivos combinados y optimizados
  • Construcción de rutas: Paquetes especiales para páginas admin de WordPress
  1. Archivos de registro PHP – Genera archivos que le dicen a WordPress qué scripts cargar
  2. Modo watch – Monitorea archivos y reconstruye solo lo que cambió

Compilación inicial: 2-3 minutos. Recompilaciones incrementales: segundos.

Ver ejemplo completo de lo devuelve el comando (cuando todo va bien) 

⬢ gutenberg-forktrunk ⦾ npm start
> gutenberg@22.0.0 start
> npm run dev

> gutenberg@22.0.0 dev
> node ./bin/dev.mjs

🔨 Starting development build...
🧹 Cleaning packages...
📦 Building workspaces...
🔍 Validating TypeScript version...
📘 Building TypeScript types...
✅ Checking type declaration files...

📦 Building vendor files...
🔨 Building vendor files...
📦 Copying React UMD files...
📦 Bundling react-jsx-runtime...
📦 Bundling React Refresh...
✔ Copied React UMD files
✔ Bundled react-jsx-runtime
✔ Bundled React Refresh
🎉 Vendor files built successfully! (19ms)

✅ Initial build completed! (113s)
👀 Starting watch mode...
- TypeScript compiler watching for type changes
- Package builder watching for source changes

[09:56:52] Starting compilation in watch mode...
[09:56:52] Found 0 errors. Watching for file changes.

🔨 Building packages...

📝 Phase 1: Transpiling packages...
✔ Transpiled create-block-interactive-template (125ms)
✔ Transpiled create-block-tutorial-template (124ms)
✔ Transpiled docgen (128ms)
✔ Transpiled babel-plugin-import-jsx-pragma (132ms)
✔ Transpiled babel-plugin-makepot (132ms)
✔ Transpiled browserslist-config (131ms)
✔ Transpiled block-serialization-spec-parser (131ms)
✔ Transpiled env (129ms)
✔ Transpiled dependency-extraction-webpack-plugin (130ms)
✔ Transpiled project-management-automation (127ms)
✔ Transpiled postcss-themes (128ms)
✔ Transpiled prettier-config (128ms)
✔ Transpiled readable-js-assets-webpack-plugin (127ms)
✔ Transpiled npm-package-json-lint-config (128ms)
✔ Transpiled lazy-import (131ms)
✔ Transpiled stylelint-config (129ms)
✔ Transpiled blob (138ms)
✔ Transpiled dom-ready (136ms)
✔ Transpiled html-entities (135ms)
✔ Transpiled autop (140ms)
✔ Transpiled block-serialization-default-parser (137ms)
✔ Transpiled wp-build (132ms)
✔ Transpiled jest-puppeteer-axe (137ms)
✔ Transpiled escape-html (139ms)
✔ Transpiled private-apis (141ms)
✔ Transpiled is-shallow-equal (147ms)
✔ Transpiled latex-to-mathml (146ms)
✔ Transpiled token-list (144ms)
✔ Transpiled warning (146ms)
✔ Transpiled shortcode (151ms)
✔ Transpiled jest-console (153ms)
✔ Transpiled priority-queue (154ms)
✔ Transpiled vips (155ms)
✔ Transpiled redux-routine (156ms)
✔ Transpiled hooks (158ms)
✔ Transpiled report-flaky-tests (165ms)
✔ Transpiled style-engine (173ms)
✔ Transpiled wordcount (175ms)
✔ Transpiled interactivity (181ms)
✔ Transpiled url (197ms)
✔ Transpiled e2e-test-utils-playwright (200ms)
✔ Transpiled base-styles (797ms)
✔ Transpiled babel-preset-default (18ms)
✔ Transpiled jest-preset-default (17ms)
✔ Transpiled create-block (17ms)
✔ Transpiled postcss-plugins-preset (17ms)
✔ Transpiled deprecated (35ms)
✔ Transpiled undo-manager (36ms)
✔ Transpiled i18n (43ms)
✔ Transpiled element (50ms)
✔ Transpiled sync (56ms)
✔ Transpiled eslint-plugin (34ms)
✔ Transpiled react-i18n (48ms)
✔ Transpiled keycodes (50ms)
✔ Transpiled date (58ms)
✔ Transpiled primitives (59ms)
✔ Transpiled a11y (60ms)
✔ Transpiled api-fetch (71ms)
✔ Transpiled theme (70ms)
✔ Transpiled dom (88ms)
✔ Transpiled scripts (5ms)
✔ Transpiled react-native-aztec (5ms)
✔ Transpiled interactivity-router (96ms)
✔ Transpiled preferences-persistence (96ms)
✔ Transpiled compose (119ms)
✔ Transpiled icons (224ms)
✔ Transpiled e2e-tests (2ms)
✔ Transpiled react-native-bridge (3ms)
✔ Transpiled router (8ms)
✔ Transpiled data (33ms)
✔ Transpiled data-controls (37ms)
✔ Transpiled keyboard-shortcuts (44ms)
✔ Transpiled notices (48ms)
✔ Transpiled viewport (48ms)
✔ Transpiled rich-text (66ms)
✔ Transpiled annotations (32ms)
✔ Transpiled blocks (57ms)
✔ Transpiled components (2375ms)
✔ Transpiled server-side-render (62ms)
✔ Transpiled plugins (81ms)
✔ Transpiled global-styles-engine (87ms)
✔ Transpiled admin-ui (156ms)
✔ Transpiled list-reusable-blocks (158ms)
✔ Transpiled nux (158ms)
✔ Transpiled preferences (160ms)
✔ Transpiled commands (164ms)
✔ Transpiled dataviews (217ms)
✔ Transpiled views (13ms)
✔ Transpiled upload-media (24ms)
✔ Transpiled interface (78ms)
✔ Transpiled block-editor (400ms)
✔ Transpiled core-data (54ms)
✔ Transpiled format-library (69ms)
✔ Transpiled media-utils (79ms)
✔ Transpiled core-commands (80ms)
✔ Transpiled reusable-blocks (129ms)
✔ Transpiled patterns (131ms)
✔ Transpiled widgets (145ms)
✔ Transpiled global-styles-ui (160ms)
✔ Transpiled fields (104ms)
✔ Transpiled block-library (1030ms)
✔ Transpiled customize-widgets (193ms)
✔ Transpiled edit-widgets (264ms)
✔ Transpiled editor (383ms)
✔ Transpiled boot (128ms)
✔ Transpiled block-directory (129ms)
✔ Transpiled edit-post (148ms)
✔ Transpiled edit-site (245ms)
✔ Transpiled react-native-editor (27ms)

📦 Phase 2: Bundling packages...
✔ Bundled private-apis (69ms)
✔ Bundled wordcount (103ms)
✔ Bundled escape-html (119ms)
✔ Bundled block-serialization-spec-parser (133ms)
✔ Bundled token-list (150ms)
✔ Bundled html-entities (153ms)
✔ Bundled autop (157ms)
✔ Bundled undo-manager (151ms)
✔ Bundled redux-routine (152ms)
✔ Bundled blob (157ms)
✔ Bundled warning (156ms)
✔ Bundled notices (160ms)
✔ Bundled keycodes (166ms)
✔ Bundled is-shallow-equal (167ms)
✔ Bundled hooks (170ms)
✔ Bundled theme (167ms)
✔ Bundled dom-ready (170ms)
✔ Bundled block-serialization-default-parser (193ms)
✔ Bundled interactivity-router (203ms)
✔ Bundled priority-queue (203ms)
✔ Bundled deprecated (230ms)
✔ Bundled latex-to-mathml (237ms)
✔ Bundled i18n (243ms)
✔ Bundled shortcode (242ms)
✔ Bundled url (246ms)
✔ Bundled keyboard-shortcuts (256ms)
✔ Bundled style-engine (254ms)
✔ Bundled data (258ms)
✔ Bundled interactivity (258ms)
✔ Bundled api-fetch (275ms)
✔ Bundled dom (274ms)
✔ Bundled preferences-persistence (294ms)
✔ Bundled annotations (300ms)
✔ Bundled a11y (324ms)
✔ Bundled element (339ms)
✔ Bundled date (339ms)
✔ Bundled primitives (350ms)
✔ Bundled react-i18n (350ms)
✔ Bundled viewport (349ms)
✔ Bundled data-controls (366ms)
✔ Bundled rich-text (385ms)
✔ Bundled compose (422ms)
✔ Bundled router (424ms)
✔ Bundled server-side-render (428ms)
✔ Bundled plugins (439ms)
✔ Bundled blocks (525ms)
✔ Bundled preferences (523ms)
✔ Bundled core-data (571ms)
✔ Bundled list-reusable-blocks (572ms)
✔ Bundled nux (581ms)
✔ Bundled core-commands (592ms)
✔ Bundled reusable-blocks (598ms)
✔ Bundled commands (605ms)
✔ Bundled patterns (612ms)
✔ Bundled widgets (674ms)
✔ Bundled components (724ms)
✔ Bundled format-library (753ms)
✔ Bundled boot (762ms)
✔ Bundled media-utils (784ms)
✔ Bundled block-directory (810ms)
✔ Bundled customize-widgets (857ms)
✔ Bundled block-editor (869ms)
✔ Bundled block-library (892ms)
✔ Bundled edit-widgets (894ms)
✔ Bundled edit-post (909ms)
✔ Bundled editor (926ms)
✔ Bundled edit-site (958ms)

🚦 Phase 3: Building routes...
✔ Built route home (11ms)
✔ Built route post-list (81ms)

📄 Generating PHP registration files...
✔ Generated build/modules.php
✔ Generated build/modules/index.php
✔ Generated build/scripts.php
✔ Generated build/scripts/index.php
✔ Generated build/styles.php
✔ Generated build/styles/index.php
✔ Generated build/version.php
✔ Generated build/routes.php
✔ Generated build/index.php

🎉 All packages built successfully! (7312ms total)
👀 Watching for changes...

Un flujo de trabajo práctico de desarrollo

Aquí está el flujo de trabajo que he refinado a través de múltiples contribuciones:

Configura tu entorno de desarrollo

Ejecuta estos comandos uno tras otro en la terminal:

npm run wp-env start

Este comando iniciará WordPress en Docker y dejará el entorno listo para pruebas y desarrollo. Cuando el entorno esté completamente levantado, ejecuta:

npm start

Así se iniciará el sistema de compilación de Gutenberg, que vigilará por cambios en tu código y lo recompilará automáticamente cuando guardes archivos.

Dónde hacer cambios

La mayoría de las contribuciones tocan estos directorios:

  • packages/block-library/src/ – Bloques principales (Párrafo, Imagen, etc.)
  • packages/components/src/ – Componentes UI reutilizables
  • packages/block-editor/src/ – Funcionalidad del editor
  • packages/edit-post/ – Interfaz del editor de posts
  • packages/edit-site/ – Interfaz del editor del sitio
  • docs/ – Documentación

El modo watch significa que puedes guardar → refrescar navegador → ver cambios inmediatamente.

Lista de verificación pre-commit

Antes de hacer commit, siempre ejecuta:

npm run format        # Formatear código
npm run lint:js       # Verificar problemas
npm run lint:css      # Si cambiaste estilos
npm run test:unit     # Ejecutar tests
npm run build         # Test de producción final

Encontrando issues y trabajando en ellas

Elige tu primera issue

Las buenas primeras issues tienen estas etiquetas en el repositorio de Gutenberg:

Tus primeros cambios

  1. Crea una rama:
git checkout -b fix/numero-issue-descripcion
# Ejemplo: git checkout -b fix/12345-alineacion-bloque-cover
  1. Haz tus cambios y prueba en el navegador
  2. Verifica que todo funcione:
npm run format
npm run lint:js
npm run test:unit
  1. Haz commit de tu trabajo:
git add .
git commit -m "Block Library: Fix Cover block alignment issue

Fixes #12345"
  1. Push y crea PR:
git push origin fix/numero-issue-descripcion

Creando tu pull request

Crea tu pull request teniendo en cuenta estos tips para que reciba atención más rápidamente:

  1. Hazla pequeña y específica – PRs de 50 líneas se revisan en horas; de 2000 líneas, en meses
  2. Título descriptivo – No escribas “Arreglo bug”, mejor: “Fix: Alineación del bloque Cover en móviles”
  3. Contexto claro – Explica el problema que resuelves y por qué tu solución es la mejor

Por ejemplo, una buena descripción de PR sería:

## What
Fixes alignment issue in Cover block when using full-width on mobile devices.

## Why
Fixes #12345 - Users reported content overflow on screens < 768px

## How
- Added responsive CSS for mobile breakpoints
- Updated block wrapper to handle viewport changes

## Testing Instructions
1. Add a Cover block with background image
2. Set to full-width alignment
3. Test on mobile viewport (< 768px)
4. Verify content stays within bounds

## Screenshots
[Before: content overflowing]
[After: proper alignment]

## Checklist
- [ ] My code follows WordPress standards
- [ ] I've tested on mobile and desktop
- [ ] Unit tests pass locally

Si tu PR no recibe atención en 2-3 días:

  • Comparte el link en el canal #core-editor de Slack durante el open floor
  • Menciona a los maintainers del componente (búscalos en el archivo CODEOWNERS)
  • Revisa PRs de otros – la reciprocidad funciona
  • Consulta las reuniones del Core Editor para participar en las discusiones semanales

El proceso de revisión

El feedback es un regalo. Los revisores pueden pedir:

  • Cambios de código – Implementa las sugerencias y haz push a tu branch
  • Más tests – Añade pruebas unitarias o E2E si es necesario
  • Aclaraciones – Responde preguntas y actualiza la descripción
  • Rebase – Si hay conflictos, actualiza tu branch:
  git fetch upstream
  git rebase upstream/trunk
  git push --force-with-lease origin tu-branch

Mantén la conversación activa respondiendo dentro de 24-48 horas. Si necesitas más tiempo, avisa en un comentario.

Solucionando problemas comunes

A continuación encontrarás soluciones rápidas para los problemas más típicos al trabajar con Gutenberg. Si te atascas, probablemente la respuesta esté aquí.

Conflictos de puerto

¿No inicia el entorno porque el puerto está en uso o ves errores extraños al arrancar WordPress? Esto suele ocurrir si wp-env quedó mal parado o hay restos de una sesión anterior. Elimina y reinicia el entorno para liberar los puertos:

npm run wp-env destroy
npm run wp-env start

Fallos de compilación

Si recibes errores misteriosos o la compilación no avanza, una limpieza total es la mejor forma de descartar problemas de caché o dependencias rotas. Utiliza estos comandos para restaurar un estado limpio:

npm run distclean
npm ci
npm run dev

Errores de TypeScript

¿Ves mensajes de error relacionados con los archivos de tipos (.d.ts) o verificaciones de TypeScript que fallan? Una limpieza de los tipos puede solucionar inconsistencias en la generación de archivos de tipo:

npm run clean:package-types

Los .d.ts se generan con TypeScript usando project references del monorepo y se escriben en packages/*/build-types/.
npm run clean:package-types borra esas salidas (packages/*/build-types/. ), pero no las regenera.

Despues de limpiar los tipos los podemos regenerar de dos maneras:

  • Opción con diagnóstico: valida versión de TS, verifica .d.ts y genera un informe de trazas en ts-traces/analysis.txt
npm run build:profile-types
  • Opción rápida (solo reconstruir tipos, sin trazas):
npx tsc --build

Los cambios no aparecen

¿Tus modificaciones no se ven reflejadas en el navegador? Sigue estos pasos para identificar el motivo más habitual:

  1. Verifica que no haya errores de compilación en la terminal donde corre el watcher.
  2. Haz un refresh forzado del navegador (Cmd+Shift+R en Mac / Ctrl+Shift+F5 en Windows).
  3. Confirma que realmente estás editando el archivo correcto.

Consejos para contributors

Aquí te dejo algunos consejos a la hora de contribuir aunque en general te recomendarias que ante cualquier duda, preguntes. Te vas a encontrar una comunidad abierta y encantada de ayudar a los contributors con sus dudas.

  1. El sistema de compilación es complejo pero lógico – Entender la estructura del monorepo hace que todo tenga más sentido.
  2. Empieza pequeño – Cualquier contribución por pequeña que sea es útil al proyecto y te ayuda a familiarizarte con el flujo de trabajo.
  3. Los tests son esenciales – Atrapan problemas que nunca pensarías verificar manualmente
  4. La comunidad es solidaria – No dudes en hacer preguntas en PRs o el canal #core-editor de Slack
  5. Lee revisiones de código – Aprendí más leyendo otros PRs que de la documentación
  6. Mantén tu fork sincronizado – Es importante mantener tu fork actualizado con los últimos cambios del repositorio principal para evitar conflictos más adelante. Hazlo regularmente con estos comandos:
git fetch upstream
git checkout trunk
git merge upstream/trunk
git push origin trunk

Recursos y comunidad

Documentación esencial

Obteniendo ayuda

Referencia rápida de comandos

Ten esto a mano:

# Configuración inicial
git clone [tu-fork]
npm ci
npm run wp-env start

# Desarrollo diario
npm run wp-env start    # Iniciar WordPress
npm start               # Iniciar compilación dev

# Antes de hacer commit
npm run format          # Formatear código
npm run lint:js         # Verificar errores
npm run test:unit       # Ejecutar tests

# Creando PR
git add .
git commit -m "Mensaje claro de commit"
git push origin nombre-rama

# Solución de problemas
npm run wp-env destroy  # Reiniciar entorno
npm run distclean       # Limpiar todo
npm ci                  # Reinstalar dependencias

Notas finales

Contribuir a Gutenberg puede abrumar un poco al principio: el repositorio es enorme, el sistema de compilación complejo y los estándares altos. Pero una vez que entiendes el flujo de trabajo y las herramientas, se vuelve manejable e incluso fácil.

Los scripts npm son la columna vertebral de la experiencia de desarrollo. Entender qué hacen y cuándo usarlos transforma el proceso de contribución de misterioso a metódico.

Cada contribución importa. Esa corrección de typo hace la documentación más clara. Ese pequeño bug fix mejora la experiencia para millones. Esa nueva característica podría ser exactamente lo que alguien necesita.

La comunidad de Gutenberg es acogedora y aprecia cada contribución, sin importar cuán pequeña sea así que ¡anímate!. Tu primera PR es solo el comienzo de tu viaje como contribuidor de WordPress.

One response to “Cómo contribuir a Gutenberg: scripts NPM y configuración local”

  1. Alberto Prado Avatar
    Alberto Prado

    Tengo experiencia con React, con PHP y casi todas las herramientas de WordPress, pero no habia encontrado una guia para simplificar un poco el desarrollo de bloques y esta es la mejor. Se agradece.

    Reply

Leave a Reply

Navigation

About

Writing on the Wall is a newsletter for freelance writers seeking inspiration, advice, and support on their creative journey.

Discover more from JuanMa Codes

Subscribe now to keep reading and get access to the full archive.

Continue reading