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`
│   ├── env.ts             las variables de entorno que lee la aplicación, ver `vela env`
│   └── 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 la configuración de SvelteKit, adaptador incluido

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.js'. 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. Es deliberadamente el sitio canónico, así que las páginas de una previsualización siguen apuntando a producción.

Este archivo es código corriente, y el único lugar donde vive el nombre. Con backend, PocketBase nombra los correos que envía con APP_NAME — {APP_NAME} en las plantillas de verificación y de restablecimiento de contraseña — y vela dev y vela deploy le entregan site.name a través de su entorno, donde aparece bloqueado en el panel de administración. La URL a la que enlazan esos correos es distinta de site.url: es el origen en el que se sirve cada instancia, así que los enlaces de restablecimiento de una previsualización llegan a la previsualización. Consulta vela env para ver qué más lee PocketBase del entorno.

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. .env.example sí, y documenta lo que la aplicación lee.