Crear un proyecto SolidStart y su estructura

Un proyecto SolidStart recién creado tiene menos ficheros de los que esperarías, y esa parquedad es intencionada: casi todo el trabajo pesado lo hacen las capas de abajo, así que lo que queda en tu directorio son justo las piezas que te pertenecen a ti. Son cuatro los pilares que importan —el fichero raíz app.tsx, los dos entry points entry-client y entry-server, y la carpeta routes— y entender la función de cada uno, más cómo se enlazan, es tener el mapa completo de por dónde entra y sale la ejecución de tu aplicación. Esta lección arranca el proyecto y recorre ese esqueleto hasta que deje de parecer una caja negra y pase a ser un circuito que sabes leer.

Arrancar el proyecto

El punto de entrada es el CLI oficial, que se invoca con npm init o su equivalente en otros gestores.

npm init solid@latest
# o con otros gestores
pnpm create solid@latest
bun create solid@latest

El asistente hace pocas preguntas, pero cada una fija una decisión de arquitectura. Te pide el nombre del proyecto; una plantilla —desde bare hasta variantes con Tailwind o autenticación—; si quieres Server Side Rendering (responder que no arranca el proyecto en modo SPA, que verás en la última lección); y si usas TypeScript. Con esas respuestas escribe el esqueleto y te deja instalar dependencias y levantar el servidor.

cd mi-app
npm install
npm run dev

Recuerda de la lección anterior que ese dev invoca a Vinxi por debajo. El asistente no ha instalado un framework monolítico: ha compuesto una configuración de Vinxi con las convenciones de Solid, y lo que ha dejado en tu carpeta es la parte editable de esa composición.

El esqueleto: los cuatro pilares

Una plantilla bare con TypeScript deja un árbol muy corto. Estos son los ficheros que gobiernan la ejecución:

mi-app/
├── public/            # activos servidos tal cual (favicon, imagenes)
├── src/
│   ├── routes/        # cada fichero es una ruta
│   │   └── index.tsx  # la ruta /
│   ├── app.tsx        # raiz compartida: Router y FileRoutes
│   ├── entry-client.tsx  # arranque en el navegador
│   ├── entry-server.tsx  # documento HTML y handler de servidor
│   └── global.d.ts    # tipos del entorno de SolidStart
├── app.config.ts      # configuracion del proyecto (siguiente leccion)
├── package.json
└── tsconfig.json

flowchart TD
R[carpeta routes ficheros igual a rutas] --> A[app.tsx raiz con Router y FileRoutes]
A --> EC[entry-client hidrata en el navegador]
A --> ES[entry-server renderiza y envuelve en el documento HTML]
style A fill:#89b4fa,color:#11111b
style EC fill:#a6e3a1,color:#11111b
style ES fill:#f9e2af,color:#11111b

La lectura del diagrama es la clave del nivel: app.tsx es el centro, la raíz compartida que ambos entornos ejecutan. entry-server la renderiza a HTML en el servidor; entry-client la hidrata en el navegador; y routes es el material que app.tsx monta dentro. Los dos entry points son puertas de entrada específicas de cada entorno; el árbol de aplicación es uno solo.

app.tsx: la raíz compartida

app.tsx exporta el componente raíz de tu aplicación, el que se ejecuta idéntico en servidor y cliente. Su trabajo canónico es montar el enrutador y declarar el envoltorio común de todas las rutas —proveedores de contexto, un layout global, la frontera de Suspense—.

// src/app.tsx
import { Router } from "@solidjs/router";
import { FileRoutes } from "@solidjs/start/router";
import { Suspense } from "solid-js";

export default function App() {
  return (
    <Router
      root={(props) => (
        <Suspense>{props.children}</Suspense>
      )}
    >
      <FileRoutes />
    </Router>
  );
}

Dos piezas hacen el trabajo. Router, de @solidjs/router, es el enrutador cuya prop root define el marco que envuelve todas las rutas: aquí es donde colocas los proveedores que deben existir en cada página, tal como viste al aislar estado por petición en el nivel de SSR. FileRoutes, de @solidjs/start/router, es la magia de SolidStart: en tiempo de build lee tu carpeta routes y genera el árbol de rutas, que inserta como hijos del Router. No escribes una tabla de rutas: la declaras con la estructura de ficheros y FileRoutes la materializa.

La carpeta routes: enrutado por ficheros

La convención central de SolidStart es que la forma de src/routes es el mapa de URLs. Un fichero se convierte en una ruta cuyo componente por defecto se renderiza en esa URL. No hay registro que mantener ni import que recordar: creas el fichero y la ruta existe.

// src/routes/index.tsx  ->  la ruta /
export default function Home() {
  return <h1>Hola SolidStart</h1>;
}

// src/routes/sobre.tsx  ->  la ruta /sobre
export default function Sobre() {
  return <p>Una pagina servida por convencion de ficheros.</p>;
}

El mapeo sigue reglas legibles a simple vista: index.tsx es la raíz de su carpeta, un nombre de fichero es un segmento literal de la URL, y una subcarpeta anida un tramo de la ruta. Así, una carpeta traduce su jerarquía directamente a la de las URLs:

src/routes/
├── index.tsx          # /
├── sobre.tsx          # /sobre
└── blog/
    ├── index.tsx      # /blog
    └── novedades.tsx  # /blog/novedades

Las piezas más ricas del enrutado —parámetros dinámicos, rutas anidadas con layouts compartidos, grupos— pertenecen a su propio nivel más adelante; lo que importa fijar hoy es el principio: la estructura del sistema de ficheros es la fuente de verdad del enrutado, y FileRoutes es quien la lee en el build para tejer el árbol que el Router consume. Cambiar la navegación de tu producto es, literalmente, mover ficheros de sitio.