> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/powershell-universal/es/aplicaciones/custom-frontends.md). # Frontends personalizados Cree frontends personalizados para PowerShell Universal con React, Vue o simplemente HTML y CSS, y después alójelos como carpetas publicadas y llame a los endpoints de la API de PSU. ## Frontends personalizados Los frontends personalizados son aplicaciones web estáticas que se crean con herramientas web estándar y se alojan con PowerShell Universal. Son útiles cuando desea utilizar un framework de JavaScript, reutilizar un sistema de diseño existente o tener control total sobre la experiencia del lado del cliente. PowerShell Universal no necesita compilar ni comprender el código fuente de su frontend. Cree la aplicación con las herramientas que prefiera, publique los ficheros generados con una [carpeta publicada](/powershell-universal/es/plataforma/published-folders.md) y llame a las API de PowerShell Universal desde el navegador. Esto se diferencia de las [aplicaciones estáticas](/powershell-universal/es/aplicaciones/static-apps.md), que se crean a partir de definiciones de App de PowerShell Universal. Los frontends personalizados utilizan HTML, CSS y JavaScript estándar directamente. ## Uso de bibliotecas de JavaScript Puede utilizar React, Vue, Angular, Svelte o cualquier otra biblioteca de frontend que genere ficheros estáticos. PowerShell Universal sirve el resultado compilado, como una carpeta `dist`, `build` o `wwwroot`. Un flujo de trabajo habitual es: 1. Cree el proyecto de frontend con las herramientas del framework. 2. Configure la compilación para utilizar la ruta de solicitud que publicará en PowerShell Universal. 3. Compile el frontend. 4. Publique el resultado de la compilación como una carpeta publicada. Cuando aloje la aplicación en una ruta como `/dashboard`, configure la ruta base de su empaquetador para que las URL de JavaScript, CSS, imágenes y fuentes se resuelvan correctamente. Evite `/portal` porque entra en conflicto con el Portal integrado de PowerShell Universal. Para aplicaciones basadas en Vite, establezca la opción `base`. ```typescript import { defineConfig } from 'vite' export default defineConfig({ base: '/dashboard/' }) ``` Para aplicaciones de Angular, establezca el base href al compilar. ```powershell ng build --base-href /dashboard/ ``` Si la aplicación utiliza enrutamiento del lado del cliente, configure el enrutador para que utilice la ruta de solicitud publicada. También puede utilizar enrutamiento basado en hash cuando no desee que el servidor gestione directamente los enlaces profundos. Durante el desarrollo, puede ejecutar el servidor de desarrollo local del framework y llamar a las API de PowerShell Universal desde el navegador. Si el servidor de desarrollo se ejecuta en un origen distinto al de PowerShell Universal, configure [CorsHosts](/powershell-universal/es/config/settings.md#corshosts) o utilice la función de proxy del servidor de desarrollo del frontend. En producción, es preferible utilizar URL relativas para que las llamadas vuelvan a la misma instancia de PowerShell Universal que sirvió el frontend. ## Uso de frameworks CSS Puede utilizar frameworks CSS como Tailwind CSS, Bootstrap, Bulma o bibliotecas de componentes específicas de un framework. Incluya el CSS de la misma manera que lo haría en cualquier aplicación web estática. Para la mayoría de las aplicaciones, instale el framework CSS a través de su gestor de paquetes e inclúyalo en el paquete. Así la aplicación se mantiene autónoma y se evita depender de CDN externas. ```powershell npm install bootstrap ``` ```javascript import 'bootstrap/dist/css/bootstrap.min.css' ``` El frontend personalizado es independiente de la Admin Console y del PowerShell Universal App Framework. Incluya todos los estilos, fuentes y recursos que necesite su aplicación en el resultado de la compilación o sírvalos desde otra carpeta publicada. ## Llamar a las API de PSU Los frontends personalizados pueden llamar tanto a endpoints de API personalizados como a la API de administración de PowerShell Universal. Utilice [endpoints de API personalizados](/powershell-universal/es/api/endpoints.md) para datos y acciones específicos de la aplicación. Este es el enfoque recomendado para la mayoría de los frontends personalizados porque usted controla la ruta, la validación de la entrada, la forma de la respuesta, la autenticación y los requisitos de rol. ```powershell New-PSUEndpoint -Url '/frontend/profile' -Method Get -Authentication -Endpoint { [PSCustomObject]@{ UserName = $User.Identity.Name ServerTime = Get-Date } } ``` Desde el frontend, llame al endpoint con `fetch`. ```javascript const response = await fetch('/frontend/profile', { credentials: 'same-origin' }) if (!response.ok) { throw new Error(`Request failed: ${response.status}`) } const profile = await response.json() ``` Para las solicitudes JSON, envíe el encabezado `Content-Type` y analice el cuerpo en el endpoint o utilice un bloque `param`. ```powershell New-PSUEndpoint -Url '/frontend/tickets' -Method Post -Authentication -Endpoint { $Ticket = ConvertFrom-Json $Body [PSCustomObject]@{ Id = [guid]::NewGuid() Title = $Ticket.Title Created = Get-Date } } ``` ```javascript await fetch('/frontend/tickets', { method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ title: 'Reset development environment' }) }) ``` La API de administración está disponible en `/api/v1` y está destinada a operaciones administrativas. Utilícela cuando esté creando un frontend administrativo y el usuario que ha iniciado sesión tenga los permisos necesarios. Para flujos de trabajo orientados al usuario, considere exponer un endpoint de API personalizado más reducido que realice únicamente la operación que necesita el frontend. Evite crear URL de endpoints personalizados que entren en conflicto con las URL internas de la API de administración. Consulte [endpoints de API](/powershell-universal/es/api/endpoints.md) y [seguridad de la API](/powershell-universal/es/api/security.md) para obtener más detalles. ## Documentar API con OpenAPI La documentación de [OpenAPI](/powershell-universal/es/api/openapi.md) resulta útil al crear frontends personalizados porque describe el contrato de la API en un formato estándar. Los desarrolladores y los agentes de IA pueden utilizarla para comprender las rutas, los métodos HTTP, los parámetros, los requisitos de autenticación, los cuerpos de las solicitudes, las formas de las respuestas y los códigos de estado antes de escribir el código del frontend. Cree una definición de documentación de endpoints para la API que utiliza su frontend y asígnele los endpoints relacionados. ```powershell New-PSUEndpointDocumentation -Name 'Dashboard API' -Url '/dashboard-api' -Description 'APIs used by the custom dashboard.' New-PSUEndpoint -Url '/frontend/tickets' -Method Get -Authentication -Documentation 'Dashboard API' -Endpoint { <# .SYNOPSIS Returns tickets displayed by the custom dashboard. .DESCRIPTION Returns the ticket list for the signed-in user. Operators receive assigned tickets and administrators receive all tickets. .OUTPUTS 200: Description: Ticket list returned successfully. 401: Description: The user is not authenticated. #> Get-Ticket | Select-Object Id, Title, Status, AssignedTo } ``` Las definiciones de OpenAPI aparecen en el panel de Swagger integrado. ```http http://localhost:5000/swagger/index.html ``` Utilice la ayuda basada en comentarios en los scripts de endpoint para documentar el propósito del endpoint y sus parámetros. Para contratos de API más completos, defina los tipos de entrada y salida en la definición de documentación de endpoints y haga referencia a ellos desde las secciones `.INPUTS` y `.OUTPUTS`. Esto ayuda a que los clientes generados, las herramientas de prueba y los agentes de IA produzcan solicitudes más precisas. Cuando trabaje con un agente de IA, proporcione el documento OpenAPI o la URL de Swagger junto con los requisitos del frontend. El agente puede utilizar el contrato para generar clientes de API tipados, asistentes de solicitudes, formularios, validación, estados de carga y gestión de errores que coincidan con los endpoints reales. ## Autenticación Las carpetas publicadas y los endpoints de API pueden requerir autenticación y roles de forma independiente. Para exigir que los usuarios inicien sesión antes de cargar los ficheros del frontend, active la autenticación en la carpeta publicada. ```powershell New-PSUPublishedFolder -Name 'Dashboard' -Path 'C:\Apps\Dashboard\dist' -RequestPath '/dashboard' -DefaultDocument 'index.html' -Authentication -Role 'Operator' ``` Para proteger los datos y las acciones, active la autenticación en los endpoints de API a los que llama el frontend. ```powershell New-PSUEndpoint -Url '/frontend/admin-data' -Method Get -Authentication -Role 'Administrator' -Endpoint { Get-Date } ``` Cuando el frontend se sirve desde la misma instancia de PowerShell Universal, la autenticación por cookies funciona de forma natural para los usuarios que han iniciado sesión. Utilice `credentials: 'same-origin'` con `fetch` para que las credenciales del navegador se incluyan en las solicitudes a los endpoints autenticados. Los tokens de aplicación son útiles para la automatización, las integraciones externas y las llamadas de servidor a servidor. No incruste tokens de aplicación en el JavaScript del navegador, no los almacene en el almacenamiento local ni los incluya en el código fuente del frontend. Si un frontend necesita realizar una operación que requiere permisos elevados, cree un endpoint de API personalizado con la autenticación adecuada, comprobaciones de rol y lógica del lado del servidor. Cuando realmente necesite llamar a las API con un token de aplicación desde un cliente de confianza, envíelo en el encabezado `Authorization`. ````http Authorization: ****** Universal also supports the `X-PSU-Authorization` header for scenarios where a reverse proxy needs to use the standard `Authorization` header for another purpose. See [App Tokens](/pages/ybubDKrhYyjSXn4SbSJH) for token management guidance. ## Hosting Static Assets Use [published folders](/pages/7K71tKGBkFetUzIPmCdd) to host the compiled frontend files. The published folder maps a local file system path to a request path on the PowerShell Universal web server. ```powershell New-PSUPublishedFolder -Name 'Dashboard' -Path 'C:\Apps\Dashboard\dist' -RequestPath '/dashboard' -DefaultDocument 'index.html' ```` Después de publicar, los usuarios pueden abrir el frontend en la ruta de solicitud. ```http http://localhost:5000/dashboard ``` El parámetro `-DefaultDocument` sirve `index.html` cuando el usuario solicita la raíz de la carpeta. Esto es importante para las aplicaciones de una sola página. Para enlaces directos a rutas anidadas del lado del cliente, utilice enrutamiento basado en hash o asegúrese de que su ruta de alojamiento pueda devolver el punto de entrada del frontend para esas rutas. Publique únicamente la carpeta con el resultado compilado. No publique carpetas de código fuente que contengan ficheros de configuración, metadatos de paquetes, ficheros de entorno u otro contenido que no deba poder descargarse. Los recursos estáticos como imágenes, fuentes y fragmentos de JavaScript generados pueden residir dentro de la misma carpeta de resultado de la compilación. Si necesita compartir recursos entre varios frontends o aplicaciones, publique una carpeta separada como `/assets` y hágale referencia desde el frontend. ## Desarrollo con agentes de IA Los agentes de codificación con IA pueden ayudar a crear la estructura inicial de un frontend personalizado e iterar sobre él, especialmente si proporciona de antemano las restricciones de PowerShell Universal. Indique al agente la ruta de solicitud, el framework, las rutas de API, las expectativas de autenticación y el comando de compilación que piensa utilizar. Las skills de PowerShell Universal pueden proporcionar a los agentes de IA instrucciones, scripts y referencias reutilizables específicas de PSU. Devolutions mantiene una colección de estas skills en el repositorio [powershell-universal-skills](https://github.com/Devolutions/powershell-universal-skills). Estas skills siguen el formato Agent Skills y pueden ayudar a los agentes a realizar tareas habituales de PowerShell Universal con más contexto específico del producto. Por ejemplo, el repositorio incluye una skill `install-sandbox-psu` para instalar PowerShell Universal en un entorno de sandbox para pruebas y desarrollo. Puede instalar la colección con la CLI de skills. ```powershell npx skills add devolutions/powershell-universal-skills ``` Una vez instaladas, los agentes de codificación compatibles pueden utilizar las skills automáticamente cuando se detecta una tarea relevante de PowerShell Universal. Esto puede ser útil cuando desea que un agente cree un frontend personalizado y además configure una instancia local de PSU, configure recursos de apoyo o valide el frontend en un entorno de sandbox. Por ejemplo: ``` Build a React and Vite frontend for PowerShell Universal. It will be hosted at /dashboard from a published folder. Configure the Vite base path for /dashboard/. Use relative fetch calls to /frontend/profile and /frontend/tickets with same-origin credentials. Do not store app tokens in the browser. Include loading, error, and empty states. ``` Detalles útiles que conviene incluir en los prompts: * El framework y el gestor de paquetes que se debe utilizar. * La ruta de solicitud de la carpeta publicada. * Las URL previstas de los endpoints de API y las formas JSON. * El documento OpenAPI o la URL de Swagger de las API del frontend. * Si el frontend es público o requiere autenticación. * El comportamiento específico por rol que la interfaz debe mostrar u ocultar. * La carpeta con el resultado de la compilación que se publicará. * Cualquier skill de agente de PowerShell Universal instalada que el agente deba utilizar. Una vez que el agente haya creado el frontend, revise la configuración de compilación, ejecute la compilación de producción y publique únicamente la carpeta de resultado generada con `New-PSUPublishedFolder` o **Build > Published Folders**. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.devolutions.net/powershell-universal/es/aplicaciones/custom-frontends.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.