Estructura del proyecto

Un proyecto de Vela es un proyecto de SvelteKit corriente. Todo lo que aparece a continuación es un archivo real que te pertenece y que puedes editar — no hay runtime ni código oculto del framework.

my-project/
├── data/                  el backend de PocketBase
│   ├── fixtures/          datos simulados para desarrollo y pruebas
│   ├── hooks/             hooks de JS y tareas programadas de PocketBase
│   └── seeds/             datos que la aplicación necesita para funcionar
├── migrations/            migraciones de base de datos, aplicadas en orden
├── src/
│   ├── lib/
│   │   ├── components/ui/ componentes de shadcn-svelte
│   │   ├── schemas/       esquemas Zod, generados junto a los modelos
│   │   ├── server/        código solo de servidor, incluido el runtime de workflows
│   │   ├── workflows/     workflows en segundo plano, uno por archivo
│   │   ├── site.ts        el nombre y la URL pública de la aplicación
│   │   └── utils.ts       el helper cn y utilidades de tipos de componentes
│   ├── routes/
│   │   ├── (public)/      rutas accesibles por cualquiera
│   │   ├── (app)/         rutas tras la autenticación
│   │   └── api/           tus propias rutas de API
│   ├── app.css            importaciones de Tailwind y tokens del tema
│   ├── app.d.ts           los tipos de App.Locals, sincronizados por `vela sync`
│   └── hooks.server.ts    el middleware handlePocketbase y el init del worker de workflows
├── static/                servido tal cual
├── test/setup.ts          el contexto de pruebas del servidor
├── .vela/project.json     el id de la aplicación y los objetivos — súbelo al repositorio
├── components.json        configuración de shadcn-svelte
├── vite.config.ts         Vite, Tailwind y el adaptador de SvelteKit
└── velastack.config.ts    valores por defecto de despliegue (opcional)

Grupos de rutas

Vela se apoya en los grupos de rutas de SvelteKit para expresar el acceso. (public) es accesible por cualquiera; (app) se crea cuando se habilita la autenticación y requiere un usuario con sesión iniciada, redirigiendo las peticiones no autenticadas a la página de inicio de sesión. Los generadores colocan las rutas nuevas en (app) cuando la autenticación está habilitada y en (public) cuando no lo está, y --route lo anula. En un proyecto sin ninguno de los dos grupos, van directamente en src/routes.

Nombre y URL de la aplicación

src/lib/site.ts contiene el nombre de la aplicación y la URL en la que se sirve, en todos los proyectos, con backend o sin él:

export const site = {
    name: 'My App',
    url: 'http://localhost:5173'
};

Las páginas lo leen con import { site } from '$lib/site'. vela create escribe el nombre. Define url con la dirección donde se despliega el sitio: los enlaces canónicos, las URLs de las imágenes Open Graph y el feed RSS del blog se construyen a partir de ella, también en las páginas prerenderizadas. vela deploy avisa mientras siga siendo una dirección de localhost o no coincida con el dominio al que se despliega.

Este archivo es la fuente de verdad de ambos. Con backend, PocketBase guarda un nombre de aplicación propio para los correos que envía — {APP_NAME} en los correos de verificación y de restablecimiento de contraseña — así que vela dev y vela deploy copian site.name en él cada vez que se ejecutan. Un nombre cambiado en el panel de administración se sobrescribe la próxima vez que se ejecute cualquiera de los dos; cámbialo en src/lib/site.ts.

Workflows

src/lib/workflows/ contiene un archivo por workflow en segundo plano, y src/lib/server/workflows.ts el cliente y el worker sobre los que corren. El worker arranca desde el hook init de src/hooks.server.ts y no hace nada hasta que hay un archivo de workflow que ejecutar.

Generado y sincronizado

src/app.d.ts y los tipos de las colecciones los regenera vela sync, que se ejecuta automáticamente tras los cambios en la base de datos durante el desarrollo. src/lib/schemas lo escriben los generadores y es tuyo para editarlo después.

Estado versionado

.vela/project.json contiene el id permanente de la aplicación y el servidor al que está vinculado cada objetivo. Debe estar en el control de versiones — sin él, un despliegue de CI genera un id nuevo y deja huérfana la aplicación que ya está en el servidor. .env no: contiene las credenciales del superusuario local, y los valores de producción viven en el servidor, gestionados con vela env.