Chispa

Un motor UI reactivo y extremadamente minimalista.

Chispa no es un framework dogmático: es un motor ligero que expone reactividad mínima sobre DOM real, pensado para integrarse, incrustarse y usarse desde herramientas y entornos donde las capas pesadas sobran.

Principio: la función del componente se ejecuta una vez; el resto es flujo de datos (signals → DOM).

¿Para quién es chispa?

• Ideal para desarrolladores que necesitan control directo del DOM y baja complejidad mental.
• Perfecto para IDEs, plugins, paneles embebidos, dashboards y UIs que requieren integración con código legado.

¿Para qué NO es chispa?

• No pretende (de momento) sustituir un framework de aplicación completo (SSR complejo, abstracciones de estado a gran escala).

Diferenciadores

• HTML real: plantillas HTML importadas, sin JSX ni transformaciones mágicas.
• JS/TS real: funciones de componente normales (se ejecutan una vez) y señales explícitas.
• Bindings directos signal → DOM: actualizaciones precisas sin VDOM ni heurísticas.
• Motor embebible: sin lifecycle complejo ni arquitectura impuesta; fácil de integrar y depurar.

Características

• ⚡ Reactividad Fina: Basado en Signals para actualizaciones precisas y eficientes del DOM.
• 🧩 Componentes Funcionales: Crea componentes reutilizables con funciones simples.
• 📄 Plantillas HTML: Separa la lógica de la vista importando archivos HTML directamente.
• 🛠️ Integración con Vite: Incluye un plugin de Vite para una experiencia de desarrollo fluida.
• 📦 Ligero: Sin dependencias pesadas en tiempo de ejecución.

Instalación

Instala chispa en tu proyecto:

npm install chispa

Configuración (Vite)

Para usar las plantillas HTML, necesitas configurar el plugin de Chispa en tu vite.config.ts:

import { defineConfig } from 'vite';
import { chispaHtmlPlugin } from 'chispa/vite-plugin';

export default defineConfig({
	plugins: [chispaHtmlPlugin()],
});

Para que el tipado funcione correctamente también es necesario agregar esto en tsconfig.json:

{
	"compilerOptions": {
		// ...
		"rootDirs": [
			// ...
			".chispa/types"
		]
	}
	// ...
}

Uso Básico

1. Crear un Componente

Chispa permite definir la estructura de tu componente en un archivo HTML y la lógica en TypeScript.

my-component.html Usa el atributo data-cb para marcar elementos que serán controlados por tu código.

<div class="my-app">
	<h1>Contador: <span data-cb="countDisplay">0</span></h1>
	<button data-cb="incrementBtn">Incrementar</button>
</div>

my-component.ts

import { component, signal } from 'chispa';
import tpl from './my-component.html'; // Importa el HTML procesado

export const MyComponent = component(() => {
	// Estado reactivo
	const count = signal(0);

	// Retorna el fragmento enlazando los elementos del HTML
	return tpl.fragment({
		// Enlaza el contenido del span con la señal
		countDisplay: { inner: count },

		// Enlaza el evento click del botón
		incrementBtn: {
			onclick: () => count.update((v) => v + 1),
		},
	});
});

A diferencia de otros frameworks de UI, la función del componente se ejecuta una sola vez al montarse. Las actualizaciones de estado no provocan que la función del componente se vuelva a ejecutar. En su lugar, el sistema actualiza de manera atómica únicamente los nodos o atributos vinculados a la señal modificada. Por este motivo no está permitido leer el valor de las señales directamente en el cuerpo de la función factory del componente; su lectura debe realizarse dentro de callbacks o efectos.

2. Montar la Aplicación

main.ts

import { appendChild } from 'chispa';
import { MyComponent } from './my-component';

appendChild(document.body, MyComponent());

API Principal

Reactividad

• signal(initialValue): Crea una señal reactiva.

  const count = signal(0);
  console.log(count.get()); // Leer valor
  count.set(5); // Establecer valor

• computed(() => ...): Crea una señal derivada que se actualiza automáticamente cuando sus dependencias cambian.

  const double = computed(() => count.get() * 2);

Componentes

• component<Props>((props) => ...): Define un nuevo componente.
• appendChild(parent, child): Función auxiliar para montar componentes en el DOM.

Licencia

MIT