Setup de SolidJS con Vite y TypeScript: Guía Paso a Paso con Comandos y Salidas Esperadas

Introducción

Si estás empezando con SolidJS, querés una pila moderna y rápida para el desarrollo frontend, probablemente hayas escuchado hablar de Vite y TypeScript. Juntos forman un trio perfecto: Vite provee un servidor de desarrollo ultrarrápido y empaquetado optimizado, SolidJS brinda un framework reactivo y ligero, y TypeScript añade tipado estático para hacer tu código más seguro y mantenible. En este artículo, vas a aprender exactamente cómo montar un proyecto SolidJS desde cero usando Vite y TypeScript, ejecutar los comandos necesarios y entender qué salida podés esperar en cada paso.

El artículo está pensado tanto para principiantes como para desarrolladores que ya usan frameworks similares (React, Vue, Angular). Si ya conocés la terminal, un poco de npm o yarn, y sabes cómo navegar en un repo, vas a poder seguir sin problemas. Al final, vas a tener un skeleton funcional de una aplicación SolidJS listo para que le agregues tus componentes, estilos y lógica de negocio.

Requerimientos Previos

Antes de empezar, hay un par de cosas que necesitás en tu máquina:

• Node.js ≥ 18 (para correr Vite y npm scripts).
• npm o yarn (prefiero yarn si lo tenés instalado, pero los pasos funcionan igual con npm).
• Un editor de código (VS Code, Polacode, o cualquier otro).
• Conocimientos básicos del terminal (cómo listar directorios, crear carpetas, correr comandos).

Puedes chequear tus versiones así:

node -v
npm -v
# o
yarn --version

Si algún comando falla o las versiones son muy bajas, instalá la versión más reciente desde nodejs.org o usá tu gestor de versionado preferido.

Crear un Nuevo Proyecto con Vite

Vite viene con un asistente de creación de templates que puede generar un montón de proyectos preconfigurados. Para SolidJS, usás el siguiente comando:

npm create solid@latest

O equivalentemente con yarn:

yarn create solid@latest

Cuando corrés este comando, Vite va a preguntarte unas pocas cosas mediante prompts interactivos:

1. Nombre del proyecto: elegí algo descriptivo, por ejemplo mi-app-solid.
2. ¿Querés usar TypeScript? (responde y).
3. ¿Querés usar el estilo jsx o tsx? (SolidJS usa tsx).
4. ¿Querés instalar los paquetes de Tailwind CSS? (opcional, podés decir n).
5. ¿Querés inicializar un git repository? (normalmente y).

La salida que verás en pantalla se verá más o menos así (he acortado algunas líneas):

Scaffolding project in /Users/tuusuario/mi-app-solid...
✅  Templates installed
✅  Package.json creado
✅  .eslintrc.cjs creado
✅  src/components/HelloWorld.tsx creado
✅  src/main.tsx creado
✅  src/App.tsx creado

Ejecutando `npm install`...
added 23 packages, actualizado 5 packages, eliminado 1 package
 Guardando la lista de nodos

✨  Listo! Para empezar a desarrollar, ejecutá:
   cd mi-app-solid
   npm run dev

Como podés ver, Vite ya instaló las dependencias, creó un archivo package.json, y generó la estructura básica. El asistente también agregó TypeScript automáticamente y creó unos cuantos componentes de ejemplo.

Navegando la Estructura del Proyecto

Una vez dentro del nuevo directorio (cd mi-app-solid), listás los archivos así:

ls -la

Resultado esperado (parcial):

app.tsx   node_modules/   package.json   public/   src/

Dentro de src/ tenés:

components/   assets/   env.d.ts   main.tsx   App.tsx   styles.css

• main.tsx: El punto de entrada donde se renderiza la app en el DOM.
• App.tsx: El componente raíz que contiene la lógica principal.
• components/HelloWorld.tsx: Un componente de ejemplo mínimo.
• styles.css: Archivo de estilos global (puedes renombrarlo a styles.ts si usás CSS-modules).
• assets/: Carpeta para imágenes, fuentes, etc.

El archivo package.json ya tiene los scripts necesarios:

{
  "name": "mi-app-solid",
  "version": "0.0.0",
  "scripts": {
    "dev": "vite",
    "build": "tsc && vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "solid-js": "^1.7.11",
    "vite": "^4.3.9"
  },
  "devDependencies": {
    "typescript": "^5.0.4",
    "@vitejs/plugin-solid": "^0.0.0-placeholder",
    "@types/node": "^20.2.5"
  }
}

El archivo tsconfig.json también viene preconfigurado; podés editarlo si necesitás ajustes personalizados.

Correr el Desarrollo Local

Con todo instalado, podés iniciar el servidor de desarrollo con:

npm run dev

O con yarn:

yarn dev

El servidor de Vite va a arrancar en http://localhost:5173. Verás algo como esto:

   > Vite 4.3.9 ready in development
   > Listening on http://localhost:5173
   > Check out http://localhost:5173/

Ahora abrí tu navegador y navegá a esa URL. Deberías ver la interfaz predeterminada de SolidJS (un título "¡Hola, mundo!" y un contador) funcionando con recarga rápida en cada cambio.

Un Script Rápido en TypeScript

Para probar el flujo TypeScript → JavaScript, podés crear un pequeño componente o script que solo imprima algo en consola. El playground de este artículo te permite probar código TypeScript directamente:

const greeting: string = "Hola desde TypeScript con SolidJS!";
console.log(greeting);

Al ejecutar este bloque, verás la salida:

Hola desde TypeScript con SolidJS!

Esto confirma que TypeScript se está transfiriendo correctamente y que el lenguaje tipado funciona en el contexto del proyecto.

Agregar Componentes y Rutas

El esqueleto de SolidJS ya incluye un componente HelloWorld. Podés usar este como punto de partida para crear componentes propios:

// src/components/HelloWorld.tsx
import { Show } from "solid-js/web";

interface Props {
  name: string;
}

export default function HelloWorld(props: Props) {
  return (
    <div class="hello-world">
      <h1>¡Hola, {props.name}!</h1>
      <Show when={props.name.length > 0}>
        <p>El nombre tiene {props.name.length} caracteres.</p>
      </Show>
    </div>
  );
}

Importalo en App.tsx y usalo:

// src/App.tsx
import { Component } from "solid-js";
import HelloWorld from "./components/HelloWorld.tsx";

const App: Component = () => {
  const user = { name: "Solidista" };

  return (
    <main class="container">
      <HelloWorld name={user.name} />
    </main>
  );
};

export default App;

Ahora el contador de ejemplo ya está integrado. Podés ampliar la app con más componentes, gestión de estado (createSignal, createStore) y lógica de rutas si necesitás navegación.

Construir para Producción

Cuando tu app esté lista para ser desplegada, ejecutá:

npm run build

Vite va a ejecutar tsc (compilador TypeScript) y luego vite build. La salida esperada es similar a:

>>> Compilando con TypeScript
src/main.tsx
src/App.tsx
src/components/HelloWorld.tsx

>>> Construyendo con Vite
vite v4.3.9: empezando...
 vite v4.3.9: ¡dist se ha generado exitosamente!

Tras la compilación, una carpeta dist/ aparece con archivos estáticos optimizados:

ls -la dist

Resulta en algo como:

index.html  assets/  static/  ... (archivos .js y .css)

Ahora podés servir la carpeta dist/ con cualquier servidor web estático (nginx, Apache, Netlify, Vercel). Para una vista previa local, usá:

npm run preview

Y seguí las instrucciones en pantalla.

Errores Comunes y Soluciones Rápidas

1. "Could not find '@vitejs/plugin-solid'"

A menudo ocurre cuando la instalación se interrumpe. Borrá node_modules y package-lock.json (o yarn.lock) y volvé a instalar:

rm -rf node_modules
yarn install   # o npm install

2. "src/main.tsx:1:1: TS2691: El archivo no se encuentra o está fuera del directorio de salida del proyecto"

Significa que tsc no puede encontrar los archivos de entrada, usualmente porque tsconfig.json tiene un rootDir equivocado. Verificá el tsconfig.json base:

{
  "compilerOptions": {
    "target": "ES2020",
    "lib": ["DOM", "DOM.Iterable", "ES2020"],
    "types": ["typescript", "vite/client"],
    "allowJs": true,
    "skipLibCheck": true,
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true,
    "declaration": false,
    "noEmitOnError": false,
    "jsx": "preserve",
    "outDir": "dist"
  },
  "include": ["src"],
  "exclude": ["node_modules"]
}

Siempre que src contenga los archivos fuente, estás bien.

3. Recarga en Desarrollo No Funciona

Si el servidor de Vite no actualiza la página cuando editás un componente, aseguráte de que el servidor está corriendo con npm run dev. Reiniciá el proceso si está atascado. También aseguráte de que vite está en el PATH correctamente.

4. La Construcción Falla por Tipado Incorrecto

Ejecutá npm run build una vez, observá el error, y corregilo. Usar strict en TypeScript ayuda a atrapar errores rápidamente.

Buenas Prácticas

1. Convenciones de Nombres: Usá camelCase para nombres de variables y funciones, PascalCase para componentes.
2. Organización de Componentes: Agrupá componentes relacionados en subcarpetas bajo src/components/ (por ejemplo, components/ui/, components/features/, etc.).
3. Manejo de Estado: Para apps pequeñas, createSignal es suficiente. Para estados más complejos, considerá createStore de solid-js/store o Redux.
4. Estilizado: SolidJS funciona bien con CSS estándar, CSS Modules (.module.css), o frameworks como Tailwind CSS. Podés instalar @tailwindcss/forms y configurar postcss.config.js.
5. Linter y Formatter: El esqueleto incluye ESLint y Prettier. Corré npm run lint y npm run format regularmente.
6. Variables de Entorno: Usá el archivo .env para variables de desarrollo, y aseguráte de que .env no está en .gitignore si necesitás cargarlos en el build.
7. Separación de concerns: Mantené los componentes delgados, mové lógica de negocio a utilidades o stores.
8. Versionado: Usá un buen flujo de git. El asistente ya inicializa un repo, pero podés cambiar el main branch a master si eso se alinea con tu equipo.

Conclusión

Configurar un proyecto SolidJS con Vite y TypeScript hoy es cuestión de unos pocos comandos. Seguí esta guía, y ahora tenés un skeleton funcional de una aplicación de una sola página con tipado, recarga rápida y builds optimizados para producción. Recordá que el verdadero poder de SolidJS emerge cuando empezás a crear componentes reutilizables, manejas el estado eficientemente, y usas las herramientas de la comunidad (stores, routing, etc.).

Ahora podés centrarte en construir tu aplicación: agregá rutas, paginas dinámicas, integra APIs, y desplegá en un servicio en la nube. La base ya está lista y optimizada para escalar.

¡Feliz desarrollo con SolidJS, Vite y TypeScript!

Próximos Pasos

• Explora solid-js/router para navegación basada en rutas.
• Considerá solid-js/store para gestión de estado centralizada.
• Integrá Tailwind CSS o Styled Components para diseño.
• Desplegá tu app en plataformas como Netlify, Vercel o GitHub Pages.
• Aprende a usar Solid Start si necesitás un framework full-stack con SSR.

Con estos conocimientos, podés abordar cualquier proyecto frontend con confianza y velocidad.