Estructura del proyecto de Fabric Apps

Los proyectos de Fabric Apps usan una estructura de carpetas coherente para que puedas encontrar rápidamente los modelos de datos, la configuración del backend y el código del frontend. En este artículo se explican los archivos y carpetas con los que es más probable que trabaje después de crear un proyecto.

Diseño de carpetas

Al crear un nuevo proyecto de Fabric Apps, la plantilla genera la siguiente estructura:

your-project/
├── rayfin/
│   ├── data/
│   │   ├── schema.ts
│   │   └── *.ts
│   ├── .env
│   ├── rayfin.yml
│   └── tsconfig.json
├── src/
├── package.json
├── tsconfig.json
└── README.md

Archivos de configuración principales

rayfin/rayfin.yml

El archivo rayfin/rayfin.yml es el archivo de configuración principal del back-end de Fabric Apps. Controla qué servicios se ejecutan durante el desarrollo local y admite la interpolación de variables de entorno para los valores de configuración dinámica.

Ejemplo completo:

id: my-app
name: my-app
version: 1.0.0
services:
  auth:
    enabled: true
    expiryInMinutes: 60
    refreshToken:
      lifetimeInDays: 30
    customClaims:
      tenant: "default"
    scopes:
      - read:data
      - write:data
    allowedRedirectUris:
      - http://localhost:5173
      - http://localhost:5173/auth/callback
    password:
      enabled: true
    fabric:
      enabled: false
    passwordless:
      magicLink:
        enabled: false
        expiryMinutes: 15
      smsOtp:
        enabled: false
    email:
      enabled: false
      provider: smtp
      senderName: Rayfin Platform
      verificationTokenExpirationHours: 24
      passwordResetTokenExpirationMinutes: 30
      smtp:
        host: maildev
        port: 1025
        senderEmail: noreply@rayfin.local
        username: ""
        password: ""
        useSsl: false
        useStartTls: false
        webPort: 1080
  data:
    enabled: true
    dialect: mssql
  storage:
    enabled: false
  staticHosting:
    enabled: true
    root: .
    folder: dist
    buildCommand: npm run build
    indexDocument: index.html

La configuración incluye estos campos clave:

Campos de nivel superior

Campo Tipo Obligatorio Descripción
id string Sí Slug del proyecto usado como nombre del proyecto de Docker Compose e identificador de elemento de Fabric.
name string Sí Nombre para mostrar del proyecto comprensible para las personas.
version string Sí Versión del proyecto (semver).
services object Sí Bloque de configuración del servicio.

services.data

Campo Tipo Predeterminado Descripción
enabled boolean false Habilite el servicio de datos.

services.auth

Campo Tipo Predeterminado Descripción
enabled boolean false Habilite el servicio de autenticación.
expiryInMinutes number — Expiración del token JWT en minutos.
customClaims Record<string, string> — Declaraciones personalizadas añadidas a los JWT emitidos.
scopes string[] — Ámbitos de OAuth (por ejemplo, ["read:data", "write:data"]).
refreshToken.lifetimeInDays number — Vigencia del token de actualización en días.
allowedRedirectUris string[] ["http://localhost:5173"] URI de redirección permitidas para respuestas de autenticación.

services.auth.password

Campo Tipo Predeterminado Descripción
enabled boolean true Habilitación de la autenticación de correo electrónico y contraseña para el desarrollo local

services.auth.fabric

Campo Tipo Predeterminado Descripción
enabled boolean false Habilite la autenticación mediada de Fabric (Microsoft Entra ID SSO).

services.staticHosting

Campo Tipo Predeterminado Descripción
enabled boolean false Habilite el hospedaje de contenido estático.
root string — Directorio raíz del proyecto de front-end (relativo a la raíz del proyecto).
folder string "dist" Directorio que contiene recursos estáticos compilados (relativos a root).
buildCommand string — Comando shell que se ejecutará antes del empaquetado (por ejemplo, npm run build).
indexDocument string — Documento predeterminado servido para la ruta de acceso raíz (por ejemplo, index.html).

Sugerencia

Todos los valores de cadena admiten la interpolación de variables de entorno con la sintaxis ${VAR} y ${VAR:-default}. Las variables se resuelven desde rayfin/.env y el entorno de shell.

rayfin/.env

El rayfin/.env archivo es un archivo de entorno opcional que se usa para proporcionar valores a rayfin.yml través de la interpolación. No confirme secretos en el repositorio. En su lugar, cree un rayfin/.env.example archivo con fines de documentación y agregue .env al .gitignore archivo.

rayfin/tsconfig.json

El archivo rayfin/tsconfig.json es una configuración typeScript de referencia de proyecto que usa la CLI de Fabric Apps para compilar las definiciones de entidad. Extiende tu raíz tsconfig.json y sobrescribe la configuración que Fabric Apps necesita, como composite: true y la resolución de módulos de Node.js. No es necesario editar este archivo directamente.

Archivos de modelo de datos

rayfin/data/*.ts

Los archivos en la carpeta rayfin/data/ definen tus entidades. Las entidades son clases typeScript decoradas con @entity() más decoradores de campo como @uuid() y @text(). Cada archivo de entidad exporta una clase que representa un modelo de datos en la aplicación.

rayfin/data/schema.ts

El archivo rayfin/data/schema.ts relaciona los nombres de las entidades con sus clases. El cliente del SDK de Rayfin usa este mapa para proporcionar acceso seguro de tipos a las entidades a través de client.data.<Entity>. Al agregar una nueva entidad, debe registrarla en este archivo de esquema.

Artefactos generados

rayfin/.temp/

La rayfin/.temp/ carpeta contiene artefactos de back-end generados que se crean al ejecutar el servidor de desarrollo. Si el backend parece estar usando un esquema o una configuración obsoletos, detén y reinicia la pila de desarrollo para regenerar estos archivos.

Importante

No subas la carpeta .temp/ a tu repositorio. Agréguelo al .gitignore archivo.

Estructura de front-end

La src/ carpeta contiene el código de la aplicación de front-end. La estructura exacta depende de la plantilla que haya elegido al crear el proyecto, como React o Vue.

Las plantillas de aplicaciones de Fabric usan las siguientes variables de entorno de Vite para la configuración de la interfaz:

  • VITE_RAYFIN_API_URL – URL base que dirige el frontend al backend de Fabric Apps. Establezca esta variable de entorno antes de ejecutar npm run dev para invalidar el valor predeterminado.
  • VITE_RAYFIN_PUBLISHABLE_KEY – Clave que se puede publicar usada para la autenticación de cliente.
  • VITE_FABRIC_ITEM_ID: identificador de elemento de Fabric establecido por rayfin up. Se escribe en .env.fabric-<workspacename> (y en .env.fabric) durante el despliegue. Se usa para la autenticación mediada de Fabric.
  • VITE_FABRIC_WORKSPACE_ID: identificador de área de trabajo de Fabric establecido por rayfin up. Se escribe junto con VITE_FABRIC_ITEM_ID durante el despliegue.

Contenido relacionado

  • Last updated on