Antes de escribir el primer componente de TaskFlow necesitas preparar el entorno de trabajo: instalar las herramientas básicas, crear un proyecto con una estructura sensata y comprobar que todo funciona sirviendo una página en el navegador. Esta lección es puramente práctica y está pensada para quien parte de cero: al final tendrás una carpeta de proyecto lista, con el paquete lit instalado, un servidor de desarrollo funcionando y el editor configurado para trabajar cómodamente con plantillas de Lit.

1. Instalar Node.js
2. Crear el proyecto con Vite (plantilla de Lit)
3. Alternativa: npm init @open-wc
4. Instalar el paquete lit
5. Estructura de carpetas recomendada
6. Servir el proyecto en local
7. Extensiones de editor útiles
8. JavaScript o TypeScript: la decisión de este curso

Lit en sí mismo es una biblioteca que se ejecuta en el navegador y no necesita ningún entorno especial para funcionar. Sin embargo, para el flujo de trabajo moderno de desarrollo —gestionar dependencias, levantar un servidor de desarrollo con recarga automática, empaquetar el proyecto— se utiliza Node.js junto con su gestor de paquetes, npm.

Pasos:

1. Descarga e instala la versión LTS (de soporte prolongado) de Node.js desde nodejs.org. En Linux también puedes usar el gestor de paquetes de tu distribución o un gestor de versiones como nvm.
2. Comprueba la instalación abriendo una terminal y ejecutando:

Deberías ver dos números de versión. Para este curso, cualquier versión de Node.js 18 o superior es suficiente, ya que es el mínimo que exigen las herramientas modernas del ecosistema (Vite, Lit 3.x).

Vite es una herramienta de desarrollo muy popular por su arranque casi instantáneo y su recarga en caliente. Trae plantillas oficiales para varios ecosistemas, entre ellos Lit.

Para crear un proyecto nuevo llamado taskflow:

El asistente creará una carpeta taskflow con un proyecto de ejemplo ya configurado para trabajar con Lit. A continuación, entra en la carpeta e instala las dependencias:

Y arranca el servidor de desarrollo:

Vite mostrará una URL local (normalmente http://localhost:5173). Al abrirla en el navegador verás el componente de ejemplo que trae la plantilla, con recarga automática cada vez que guardes un cambio en el código.

Nota: la plantilla lit de Vite usa TypeScript por defecto. Existe también una plantilla lit-ts explícita y, si prefieres JavaScript puro, puedes partir de la plantilla vanilla y añadir lit manualmente (se explica en el apartado 4). Más adelante en esta misma lección se comenta cómo elegir entre JavaScript y TypeScript para seguir el curso.

Otra vía, mantenida por la comunidad de Open Web Components (un conjunto de herramientas y recomendaciones específicamente pensadas para Web Components, no solo para Lit), es el asistente @open-wc:

Este asistente pregunta de forma interactiva qué se quiere generar (una aplicación, un componente publicable como paquete...), si se desea usar TypeScript, y si se quieren incluir herramientas de linting, testing o demos. Es una opción algo más completa y orientada a quien va a publicar componentes reutilizables como paquetes independientes, mientras que la plantilla de Vite es más directa para empezar una aplicación cuanto antes.

Para los propósitos de este curso, cualquiera de las dos vías es válida; los ejemplos asumirán una estructura de proyecto creada con Vite, por ser la más extendida y sencilla de arrancar.

Si partes de una plantilla en blanco (por ejemplo, la plantilla vanilla de Vite) o simplemente quieres saber qué ocurre "por debajo", instalar Lit manualmente es tan sencillo como:

Esto añade lit a las dependencias del package.json del proyecto. A partir de ahí, en cualquier fichero JavaScript o TypeScript del proyecto se puede importar lo necesario:

No hace falta ninguna configuración adicional de bundler: lit se distribuye como módulos ES estándar, compatibles con Vite y con cualquier herramienta moderna de empaquetado.

Un proyecto de Lit no impone una estructura de carpetas concreta —a diferencia de algunos frameworks más opinados—, pero conviene adoptar una organización clara desde el principio, especialmente porque TaskFlow crecerá con varios componentes a lo largo del curso. Una estructura recomendada para este curso es:

Ideas clave de esta organización:

• Cada componente vive en su propio fichero, con un nombre que coincide con el nombre de la etiqueta HTML que define (task-card.js define <task-card>).
• La carpeta components/ agrupa todos los Web Components de la aplicación, separados de la lógica de arranque (main.js).
• A medida que el curso avance, esta estructura se irá ampliando (por ejemplo, con una carpeta para controladores reactivos o para pruebas), pero la idea de "un componente, un fichero" se mantendrá durante todo el curso.

Durante el desarrollo, los componentes de Lit se ejecutan directamente en el navegador, por lo que basta con un servidor que sirva los ficheros estáticos del proyecto. Ya se ha visto que Vite ofrece esto con npm run dev, pero conviene entender qué hace exactamente ese comando:

• Arranca un servidor HTTP local (no es necesario configurar Apache, Nginx ni nada similar).
• Sirve index.html y resuelve los módulos ES (import ... from 'lit') al vuelo, sin necesidad de generar antes un bundle.
• Observa los cambios en los ficheros del proyecto y refresca automáticamente el navegador (o incluso actualiza el módulo concreto sin recargar toda la página, gracias al "Hot Module Replacement").

Para generar una versión optimizada para producción (minificada, con los módulos empaquetados), Vite ofrece también:

El resultado se genera en una carpeta dist/. El proceso de empaquetado para producción, con más detalle sobre optimización y publicación, se estudia en el módulo de integración y despliegue; por ahora basta con saber que existe este segundo comando.

Trabajar con las plantillas de Lit —bloques de HTML incrustados dentro de JavaScript mediante la función html — es mucho más cómodo con el soporte adecuado del editor. Si usas Visual Studio Code (el editor más habitual en el ecosistema), estas son las extensiones recomendadas:

lit-plugin se apoya internamente en una herramienta llamada lit-analyzer, que también existe como comando de línea de órdenes y se puede integrar en la integración continua para detectar errores en las plantillas (por ejemplo, atributos mal escritos) antes de llegar a producción. Volveremos sobre herramientas de calidad de código en el módulo de pruebas y buenas prácticas.

Lit está escrito en TypeScript y ofrece una integración excelente con él (tipado de propiedades, autocompletado de plantillas, decoradores con tipos comprobados). Sin embargo, TypeScript no es obligatorio: Lit funciona igual de bien con JavaScript puro.

Existen dos maneras habituales de declarar una clase de componente en Lit:

• Con decoradores (@customElement, @property, @state...): es la sintaxis más concisa y la que usa la documentación oficial por defecto. Los decoradores son una propuesta de JavaScript que, a día de hoy, requiere una herramienta de compilación que los soporte (TypeScript, o Babel con el plugin correspondiente en proyectos JavaScript). Vite ya trae esta capacidad configurada en su plantilla de Lit.
• Sin decoradores, con static properties: una forma alternativa, totalmente equivalente en resultado, pensada para proyectos en JavaScript plano que no quieran depender de un paso de compilación con soporte de decoradores. Es más verbosa pero no requiere ninguna configuración adicional.

Este curso usará JavaScript, mostrando ambas variantes (decoradores y static properties) allí donde tenga sentido comparar, para que puedas elegir la que mejor encaje en tus propios proyectos. La primera vez que aparezca esta disyuntiva con detalle será en la próxima lección, al construir el primer componente real.

• Usar una versión antigua de Node.js: si npm create vite@latest falla con errores extraños, lo primero que hay que comprobar es la versión de Node.js instalada. Actualizarla suele resolver el problema.
• Olvidar npm install tras clonar o crear el proyecto: sin este paso, el paquete lit (y el resto de dependencias) no estarán disponibles y el proyecto no arrancará.
• Mezclar sintaxis de decoradores sin la configuración de compilación adecuada: si se copian ejemplos con @customElement en un proyecto que no tiene configurado el soporte de decoradores, aparecerán errores de sintaxis. La plantilla de Vite para Lit ya viene preparada; si se parte de cero conviene comprobarlo antes.
• Confundir el servidor de desarrollo con un servidor de producción: npm run dev no está pensado para servir tráfico real; para producción se genera primero el build y se sirve el contenido estático resultante.

1. Instala Node.js si no lo tienes ya, y comprueba las versiones de node y npm desde la terminal.
2. Crea un proyecto nuevo llamado taskflow usando la plantilla de Lit de Vite, instala las dependencias y arráncalo en modo desarrollo. Comprueba que puedes abrirlo en el navegador.
3. Dentro del proyecto recién creado, crea la carpeta src/components/ y un fichero vacío task-card.js dentro de ella, siguiendo la estructura de carpetas recomendada en esta lección.

1. La comprobación se hace con:

Si ambos comandos devuelven un número de versión (por ejemplo v20.11.0 y 10.2.4), la instalación es correcta.

Tras el último comando, la terminal mostrará una URL local (por ejemplo http://localhost:5173); al abrirla en el navegador debe verse la página de ejemplo de la plantilla de Lit.

En Windows, sin touch disponible por defecto, basta con crear el fichero vacío desde el editor de código guardándolo en esa ruta.

En esta lección has preparado todo el terreno necesario para empezar a programar: Node.js instalado, un proyecto TaskFlow creado con Vite (o alternativamente con @open-wc), el paquete lit disponible, una estructura de carpetas pensada para crecer y un editor configurado con soporte específico para las plantillas de Lit. También has visto que este curso usará JavaScript, alternando entre la sintaxis de decoradores y static properties según convenga.

Con el entorno ya listo, en la siguiente lección dejarás de configurar y empezarás a programar: crearás tu primer componente Lit real y, con él, la primera versión —totalmente estática— de <task-card>, la pieza fundamental de TaskFlow.