One Config File To Rule Them All

Bienvenidos a todos. Mi nombre es Marco Ippolito, y hoy hablaré sobre un archivo de configuración para gobernarlos a todos. Entonces, ¿quién soy? Soy un Ingeniero de Seguridad Senior en Herodevs, y soy miembro del Comité de Dirección Técnica de NodeJS y un liberador. Entonces, NodeJS en los últimos años ha lanzado muchas características muy interesantes. Por ejemplo, el test runner, el modo watch, cosas que anteriormente necesitabas descargar de NPM, el soporte nativo de TypeScript es también otro grande en el que trabajé personalmente. Tenemos cobertura de pruebas y finalmente un modelo de permisos para mejorar la seguridad de ejecutar aplicaciones NodeJS.

Entonces, lo que todas estas características tienen en común es que todas requieren algún tipo de configuración. Por ejemplo, si quieres configurar el test runner, necesitas pasar muchos flags, y lo mismo se aplica para la mayoría de las características de NodeJS de las que hablamos. Hay algunos flags para watch, algunos flags para el modelo de permisos, algunos flags para la cobertura, otros flags para el tracing. Son muchos flags. Honestamente, ni siquiera conozco todos estos flags. Necesito ir a revisar la documentación, pero son muchos. Entonces, obviamente el problema con eso es que muchos flags se vuelve muy difícil conocerlos todos.

Comencemos con un caso de uso simple, y te mostraré cómo podemos mejorar la experiencia del desarrollador. Entonces, tomemos un flag llamado experimental transform types. Si has estado siguiendo la integración de TypeScript en NodeJS, sabes que NodeJS no soporta toda la sintaxis de TypeScript. Para habilitar este soporte al 100%, necesitas pasar este flag experimental transform types. Entonces, en este caso, podemos ejecutar enums. Tenemos el color rojo, y creamos un archivo.ts, y lo ejecutamos. Entonces, pasamos Node – experimental transform types, y funciona. Imprime rojo e imprime una advertencia experimental. Entonces, ¿cómo eliminamos la advertencia experimental? Podemos pasar otro flag. Este flag es disable experimental warning. Y, boom, tenemos rojo sin la advertencia. Entonces, agreguemos algunas pruebas. Para imaginar cómo está creciendo nuestra aplicación, queremos ejecutar algunas pruebas. Necesitamos pasar el flag – test, y luego ejecutará un conjunto de pruebas. ¿Verdad? Porque todos sabemos que la prueba es una de las primeras cosas que necesitamos agregar cuando creamos nuestra aplicación. Tal vez agreguemos algo de cobertura. ¿De acuerdo? Entonces, necesitamos pasar experimental test coverage, y luego configuramos la cobertura de prueba con el número de líneas que queremos tener al 100%.

Y, boom, tenemos esta tabla aquí con la cobertura de prueba. ¿Qué más podemos hacer? Podemos hacer modo watch. Entonces, si en el pasado usabas Nodemon para recarga en caliente, ahora puedes usar –watch. Y si cambiamos algo, la aplicación comenzará. Entonces, este eres tú ahora, porque tienes tantos flags que es muy difícil de leer.

Déjame regresar por un segundo. Como, tenemos uno, dos, tres, cuatro, cinco, seis flags. Ahora, imagina todos estos flags dentro de tu package JSON. Sería muy ancho. Entonces, necesitas desplazarte horizontalmente para verlos todos. Y esto no es genial. Podemos hacerlo mejor, ¿de acuerdo?

Entonces, si ejecutamos – si revisamos el manual de node, entonces ejecutamos man node, veremos una gran lista de cosas que no nos importan. Pero si miramos la última, podemos ver que hay una variable de entorno que la aplicación Node.js leerá. Y se llama node options. Entonces, node options es otra forma de pasar a la aplicación Node.js todos esos flags de configuración. No todos los flags son compatibles. Está documentado cuáles no son compatibles, pero la mayoría sí lo son.

Entonces, node options también es muy útil cuando estás ejecutando otra aplicación, pero no tienes control sobre el comando node. Por ejemplo, cuando estás ejecutando algo con NPX. Un caso de uso que encuentro muy útil es pasar la opción de node –abort on uncaught exception con NPX. De esta manera, si hay un error, puedo verlo sin que sea absorbido por NPX. Entonces, ¿qué hacemos ahora? Creamos esta variable de entorno llamada node options, y pasamos algunos de los flags que están permitidos dentro de los node options. Y así, podemos eliminar todos los flags después del comando node, y podemos ver que solo estamos ejecutando tres flags y funciona de la misma manera.

Entonces, también podemos usar –mfile para establecer los node options desde un archivo. Así que, creamos un .mfile, ponemos dentro de este archivo los node options, y luego lo pasamos. Entonces, si en el pasado estabas usando .env, ahora ya no necesitas instalarlo más porque está incorporado en la aplicación Node.js. Así que, creamos un archivo, ponemos los node options dentro, y luego ejecutamos node –mfile y los mismos flags que antes. Watch, experimental, test, coverage, y test. No podemos poner esos flags dentro de los node options porque no están permitidos. Muy bien.

Así que, esto es una mejora, pero aún no es genial. Creo que podemos hacerlo mucho, mucho mejor que esto. Aún tienes .mfile sin autocompletado para IDE. Tienes que saber qué flags están permitidos, cuáles no están permitidos. Es una experiencia de desarrollador subóptima. Podemos hacerlo mejor. Entonces, lo que le falta a Node.js es realmente una configuración de inicialización basada en archivos. Entonces, el nombre suena aterrador, pero si estás acostumbrado a otros lenguajes, PHP tiene uno, Java tiene uno, .NET tiene uno, Ruby tiene uno. Todos los entornos de ejecución de los principales lenguajes de programación tienen uno. Y también, otros entornos de ejecución de JavaScript tienen uno. Está el dna.json y el banfig.toml. Entonces, Node.js necesita algo similar a esto para configurar la aplicación con solo un archivo. Muy bien. Esto se ha discutido durante años. Esta discusión es de julio de 2024. Y hubo mucho ida y vuelta con los mantenedores de Node.js sobre cómo hacemos esto y cuál es la mejor manera de hacerlo. Mucho ida y vuelta. Y esto fue en febrero de 2025.

Envié un PR. Entonces, en ese momento no estaba seguro de cuál sería, como, cómo crecería la característica y la evolución de esta característica. Entonces, en ese momento se llamaba Node.json. Y básicamente podías pasar un archivo de configuración experimental y Node analizaría este archivo JSON y haría lo que veremos en unos segundos. Entonces, en Node 23, esta característica aterrizó. Esto se llama archivo de configuración experimental. Y consiste en dos flags, dos flags principales.

Entonces, el primer flag se llama archivo de configuración predeterminado experimental. Entonces, si pasas el archivo de configuración predeterminado experimental, Node buscará un Node config JSON. Entonces, el archivo necesita llamarse Node config JSON. La razón por la que no pudimos usar Node.json es porque ya está siendo utilizado por algunos paquetes de NPM en el mundo y no queremos romperlos. Entonces, si solo pasas este flag, Node lo buscará automáticamente. De lo contrario, puedes especificar un archivo JSON de tu elección pasando el flag archivo de configuración experimental. Entonces, puedes usar el archivo que quieras. Puedes ponerlo en otra carpeta. La única parte importante es que sea un archivo JSON.

Entonces, el archivo se ve así. Entonces, tiene un esquema, lo cual es muy importante. Entonces, el esquema necesita coincidir exactamente con la versión de Node que estás ejecutando. Entonces, si estás ejecutando Node 24.7, el esquema necesita coincidir con esa versión. De lo contrario, la configuración y el tiempo de ejecución no serán como habrá diferencias entre los flags que son compatibles y podría romperse. Entonces, quieres que coincidan siempre. Además, el esquema te da autocompletado. Te da soporte para IDE. Es muy bueno. Lo veremos un poco más tarde. Entonces, en este caso, tienes un campo llamado Node options, que es lo mismo que las Node options que estábamos usando antes. Y podemos poner dentro los flags que estábamos usando. Pero ahora ya no tenemos una variable de entorno, sino un archivo de configuración. Entonces, el campo Node options contiene los mismos valores que en Node options.

Entonces, las mismas que están permitidas, funcionan de la misma manera. Y no todas las flags de V8 están permitidas. Entonces, ¿qué son las flags de V8? Sabes que V8 es el motor de JavaScript dentro de Node.js que ejecuta el código JavaScript. Un ejemplo de una flag de V8 es el límite de stack trace. Entonces, puedes aumentar el tamaño de la stack trace. Por ejemplo, puedes hacer que una stack trace sea así de grande. Esto es muy útil si quieres depurar un objeto muy anidado o simplemente quieres tener el campo Java en JavaScript. Si estás acostumbrado a Java, funciona en ambos sentidos.

Entonces, también, este es un dato curioso. Entonces, hay algunas flags en Node.js que no hacen nada. Se llaman no-op. Entonces, están ahí por razones de compatibilidad. Decidimos no soportar esas flags porque no hacen absolutamente nada. Entonces, cuando una flag está presente tanto en el CLI, las Node options, y el archivo de configuración, hay una lista de prioridades. Esto es importante. Entonces, el CLI, si ejecutas Node algo, eso tiene prioridad. Luego, tenemos las Node options como una variable de entorno. Luego, tenemos el archivo de configuración. Y, al final, tenemos las Node options del .env, del archivo .env, el que vimos antes.

Creo que deberíamos intercambiar estos dos, pero podría hacerlo en un futuro PR. Sí, entonces, otra mejora muy grande en DX es la configuración global del test runner. Entonces, como hablamos anteriormente, no todas las flags son soportadas dentro de las Node options. Por ejemplo, no todas las flags de prueba son soportadas. Entonces, este problema ha estado ahí desde 2022. Entonces, ha sido necesario durante mucho tiempo. Y así, decidimos soportar un nuevo espacio de nombres dentro del archivo de configuración solo para el test runner.

Entonces, tienes un campo llamado test runner. Y, dentro de este campo, puedes pasar cualquier configuración que desees. Todo está soportado, incluso configuraciones que normalmente no son soportadas en Node options. Y, esto se ve así. Entonces, todavía necesitas habilitarlo pasando dash dash test, pero hemos eliminado muchas de las otras flags.

Otra característica que era necesaria es el espacio de nombres watch. Es de la misma manera que el espacio de nombres test. Añadimos un nuevo espacio de nombres para el watch. Como puedes ver, funciona de la misma manera. Pasas watch, y es watch preserve output true. Lo mismo. Modelo de permisos. Lo mismo. Puedes pasar el espacio de nombres permission, y puedes pasar dentro todos los campos que quieras usar. Esto está disponible en Node 25.

Entonces, en los últimos meses, tuvimos algunos cambios. Entonces, renombramos el campo test runner a test. Y ahora, cada vez que tienes un espacio de nombres, por ejemplo, pasas el espacio de nombres test o el espacio de nombres watch o el espacio de nombres permission, la flag ya no es necesaria porque se habilitará por defecto. Entonces, si tenemos test aquí, la flag dash dash test ya no es necesaria. Lo mismo para watch y lo mismo para permission. Así es como se ve un archivo de configuración moderno. Y podemos ver en nuestro CLI, usemos esto como un ejemplo de un test donde usamos el modelo de permisos. Entonces, este test solo intentará obtener algo de Internet y verificar si el acceso a la red está denegado. Si intentamos ejecutarlo, podemos simplemente ejecutar Node dash dash experimental default config file y test. Y todo lo demás está habilitado por el archivo de configuración. Entonces, hemos omitido todas las flags posibles. Solo necesitamos una, que es experimental default config file. Así que hemos mejorado mucho la experiencia del desarrollador porque el usuario ahora solo necesita configurar un archivo y puede ejecutar la aplicación de Node.js.

Entonces, algunas preguntas que me hacen mucho. Entonces, ¿hace que el inicio de mi aplicación sea más lento? La respuesta es no, es insignificante. ¿Por qué un archivo de configuración JSON y no un YAML en el terminal? La razón es que Node.js tiene un analizador JSON incorporado y no tiene ningún otro analizador como YAML en tu terminal. Así que, por conveniencia. ¿Debería publicarlo? La respuesta es no. El consumidor sería como el Node config JSON en Node modules será ignorado. ¿Está listo para producción? No, todavía es experimental. ¿Y puedo poner configuraciones personalizadas en el Node config JSON? La respuesta es sí, pero será ignorado.

Entonces, ¿qué sigue para el desarrollo de esta característica? Más espacios de nombres, texto de ayuda en el esquema JSON. Esto en realidad se implementó hace unas semanas. Entonces, como puedes ver, el IDE te explicará lo que hace la flag. En este caso, experimental test coverage te dice que habilita la cobertura en el test runner. Esto se discutió para habilitar package JSON por defecto, como para poner la configuración en paquetes en lugar de un archivo de configuración de Node. Pero la razón es que hay mucho caos en el ecosistema de configuración de Node.js. Tuvimos, sí, así que fue muy aterrador agregar un nuevo archivo de configuración.

Y mucha gente se opuso a esto porque no queremos otro archivo de configuración. Así que, hicimos una encuesta para cambiar el valor predeterminado y ponerlo en el package JSON. Pero no llegamos a un consenso. Y hay otros problemas como la validación del esquema del package JSON. Así que, descartamos esa idea. Y lo único que queda es marcarlo como candidato a lanzamiento y desconectarlo. Así que, gracias por escuchar. En el código QR, puedes encontrar toda la información. Y nos vemos la próxima vez. Adiós.