#Estructura del proyecto y stack técnico

La mayor parte del desarrollo diario puede dejarse en manos de la IA. Aun así, conocer la estructura de la plantilla le permite juzgar si la IA ha puesto su código en el lugar correcto y facilita localizar los problemas.

#Stack técnico

La plantilla de Portal se basa en @nocobase/portal-template-default, con el código fuente en nocobase/portal-template-default.

Esta combinación es el stack frontend que la IA mejor conoce hoy en día, lo que hace que lo que escribe sea más preciso.

Por ahora el Portal es un proyecto puramente frontend, con la lógica de negocio resuelta mediante la API de NocoBase, los componentes estándar y demás. El soporte para que el AI Agent escriba también el código backend del Portal llegará más adelante.

#Estructura de directorios

src/
├── app/            Rutas y carga de extensiones
├── pages/          Inicio de sesión, registro, recuperación de contraseña, etc.
├── components/     Componentes
│   ├── ui/         Base de componentes shadcn/ui
│   ├── app-shell/  Diseño, navegación, estados de carga
│   ├── auth/       Componentes de autenticación
│   └── ...
├── extensions/     Extensiones, activas una vez instaladas
├── lib/            Envoltorio del cliente de NocoBase y lógica de ACL
├── providers/      Providers de Refine
├── hooks/          Hooks personalizados
└── locales/        Textos localizados

Algunas ubicaciones clave:

• src/app/routes.tsx: estructura de rutas. Las rutas autenticadas y no autenticadas están separadas, y las rutas que aportan las extensiones se montan automáticamente
• src/app/extensions.tsx: carga de extensiones, mediante import.meta.glob para escanear src/extensions/*/extension.tsx
• src/providers/data.ts: el data provider de Refine, que traduce la sintaxis de consulta de Refine a parámetros de la API de NocoBase
• src/lib/nocobase/client.ts: NocoBaseClient, el envoltorio de bajo nivel que hay detrás de cada petición
• src/components/ui/: unos 60 componentes de shadcn/ui, listos para usar

Las páginas de negocio suelen ir bajo src/extensions/, un directorio por módulo funcional. Consulte Componentes estándar y extensiones.

#Archivos clave

#Variables de entorno

nb portal dev y nb portal deploy las escriben por usted, así que normalmente no necesitará tocarlas. Las tres últimas solo hay que alinearlas cuando el servidor haya personalizado la forma de almacenar los tokens de autenticación.

Durante el desarrollo, si NOCOBASE_API_URL es una dirección absoluta, Vite configura un proxy para reenviar las peticiones, de modo que no tendrá que ocuparse usted mismo del CORS.

#Comandos habituales

Estos son los que usará en el día a día. La instalación de dependencias, la actualización de las variables de entorno y las compilaciones las gestiona la CLI en segundo plano:

Para conocer los parámetros completos de cada comando, consulte la Referencia del comando nb portal.

#Dónde vive el espacio de trabajo de desarrollo

El espacio de trabajo de desarrollo de un Portal se crea en el directorio en el que se encontraba al ejecutar nb portal create o nb portal pull:

./<portal>

Puede indicar otra ubicación con --path al crear o al descargar. Los artefactos de despliegue compilados van a otro sitio, bajo el storage de la aplicación destino, se mantienen sincronizados mediante nb portal deploy y normalmente no hay que ocuparse de ellos.

Si no está seguro de dónde está el espacio de trabajo de desarrollo de un Portal, simplemente consúltelo:

nb portal info main

#Enlaces relacionados

• Inicio rápido del AI Portal — ponga en marcha su primera entrada frontend escrita por la IA
• Componentes estándar y extensiones — la base de componentes shadcn/ui y el mecanismo de extensión
• Despliegue y gestión del código fuente — el flujo de compilación y despliegue, y el source storage
• Construcción con un AI Agent — dirija a la IA en lenguaje natural para que escriba las páginas
• nb portal info — consulte dónde está el espacio de trabajo de desarrollo de un Portal