Custom Frontends

Custom frontends allow you to build web interfaces for PowerShell Universal using standard JavaScript, HTML, and CSS libraries instead of the PowerShell Universal App Framework. This approach is usefu

Custom Frontends

Custom frontends are static web applications that you build with standard web tooling and host with PowerShell Universal. They are useful when you want to use a JavaScript framework, reuse an existing design system, or have full control over the client-side experience.

PowerShell Universal does not need to compile or understand your frontend source code. Build the application with your preferred tooling, publish the generated files with a published folder, and call PowerShell Universal APIs from the browser.

This differs from static apps, which are built from PowerShell Universal App definitions. Custom frontends use standard HTML, CSS, and JavaScript directly.

Using JavaScript Libraries

You can use React, Vue, Angular, Svelte, or any other frontend library that produces static files. PowerShell Universal serves the compiled output, such as a dist, build, or wwwroot folder.

A typical workflow is:

1. Create the frontend project with the framework's tooling.
2. Configure the build to use the request path you will publish in PowerShell Universal.
3. Build the frontend.
4. Publish the build output as a published folder.

When hosting the application under a path such as /dashboard, configure your bundler's base path so JavaScript, CSS, image, and font URLs resolve correctly. Avoid /portal because it conflicts with the built-in PowerShell Universal Portal.

For Vite-based applications, set the base option.

import { defineConfig } from 'vite'

export default defineConfig({
	base: '/dashboard/'
})

For Angular applications, set the base href when building.

ng build --base-href /dashboard/

If the application uses client-side routing, configure the router to use the published request path. You can also use hash-based routing when you do not want the server to handle deep links directly.

During development, you can run the framework's local development server and call PowerShell Universal APIs from the browser. If the development server runs on a different origin than PowerShell Universal, configure CorsHosts or use the frontend development server's proxy feature. In production, prefer relative URLs so calls go back to the same PowerShell Universal instance that served the frontend.

Using CSS Frameworks

You can use CSS frameworks such as Tailwind CSS, Bootstrap, Bulma, or framework-specific component libraries. Include the CSS the same way you would in any static web application.

For most applications, install the CSS framework through your package manager and include it in the bundle. This keeps the application self-contained and avoids depending on external CDNs.

npm install bootstrap

import 'bootstrap/dist/css/bootstrap.min.css'

The custom frontend is independent of the Admin Console and the PowerShell Universal App Framework. Include all styles, fonts, and assets your application requires in the build output or serve them from another published folder.

Calling PSU APIs

Custom frontends can call both custom API endpoints and the PowerShell Universal Management API.

Use custom API endpoints for application-specific data and actions. This is the recommended approach for most custom frontends because you control the route, input validation, response shape, authentication, and role requirements.

New-PSUEndpoint -Url '/frontend/profile' -Method Get -Authentication -Endpoint {
		[PSCustomObject]@{
				UserName = $User.Identity.Name
				ServerTime = Get-Date
		}
}

From the frontend, call the endpoint with fetch.

const response = await fetch('/frontend/profile', {
	credentials: 'same-origin'
})

if (!response.ok) {
	throw new Error(`Request failed: ${response.status}`)
}

const profile = await response.json()

For JSON requests, send the Content-Type header and parse the body in the endpoint or use a param block.

New-PSUEndpoint -Url '/frontend/tickets' -Method Post -Authentication -Endpoint {
		$Ticket = ConvertFrom-Json $Body

		[PSCustomObject]@{
				Id = [guid]::NewGuid()
				Title = $Ticket.Title
				Created = Get-Date
		}
}

await fetch('/frontend/tickets', {
	method: 'POST',
	credentials: 'same-origin',
	headers: {
		'Content-Type': 'application/json'
	},
	body: JSON.stringify({ title: 'Reset development environment' })
})

The Management API is available under /api/v1 and is intended for administrative operations. Use it when you are building an administrative frontend and the signed-in user has the required permissions. For user-facing workflows, consider exposing a smaller custom API endpoint that performs only the operation the frontend needs.

Avoid creating custom endpoint URLs that conflict with internal Management API URLs. See API endpoints and API security for more details.

Documenting APIs with OpenAPI

OpenAPI documentation is helpful when building custom frontends because it describes the API contract in a standard format. Developers and AI agents can use it to understand routes, HTTP methods, parameters, authentication requirements, request bodies, response shapes, and status codes before writing frontend code.

Create an endpoint documentation definition for the API used by your frontend and assign related endpoints to it.

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
}

OpenAPI definitions appear in the built-in Swagger dashboard.

http://localhost:5000/swagger/index.html

Use comment-based help in endpoint scripts to document the purpose of the endpoint and its parameters. For richer API contracts, define input and output types in the endpoint documentation definition and reference them from .INPUTS and .OUTPUTS sections. This helps generated clients, test tools, and AI agents produce more accurate requests.

When working with an AI agent, provide the OpenAPI document or Swagger URL along with the frontend requirements. The agent can use the contract to generate typed API clients, request helpers, forms, validation, loading states, and error handling that match the real endpoints.

Authentication

Published folders and API endpoints can require authentication and roles independently.

To require users to sign in before loading the frontend files, enable authentication on the published folder.

New-PSUPublishedFolder -Name 'Dashboard' -Path 'C:\Apps\Dashboard\dist' -RequestPath '/dashboard' -DefaultDocument 'index.html' -Authentication -Role 'Operator'

To protect data and actions, enable authentication on the API endpoints the frontend calls.

New-PSUEndpoint -Url '/frontend/admin-data' -Method Get -Authentication -Role 'Administrator' -Endpoint {
		Get-Date
}

When the frontend is served from the same PowerShell Universal instance, cookie authentication works naturally for signed-in users. Use credentials: 'same-origin' with fetch so browser credentials are included with requests to authenticated endpoints.

App tokens are useful for automation, external integrations, and server-to-server calls. Do not embed app tokens in browser JavaScript, store them in local storage, or commit them with frontend source code. If a frontend needs to perform an operation that requires elevated permissions, create a custom API endpoint with the appropriate authentication, role checks, and server-side logic.

When you do need to call APIs with an app token from a trusted client, send it in the Authorization header.

Authorization: Bearer <app-token>

PowerShell 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 for token management guidance.

Hosting Static Assets

Use published folders 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.

New-PSUPublishedFolder -Name 'Dashboard' -Path 'C:\Apps\Dashboard\dist' -RequestPath '/dashboard' -DefaultDocument 'index.html'

After publishing, users can open the frontend at the request path.

http://localhost:5000/dashboard

The -DefaultDocument parameter serves index.html when the user requests the folder root. This is important for single-page applications. For direct links to nested client-side routes, use hash-based routing or ensure your hosting path can return the frontend entry point for those routes.

Only publish the compiled output folder. Do not publish source folders that contain configuration files, package metadata, environment files, or other content that should not be downloadable.

Static assets such as images, fonts, and generated JavaScript chunks can live inside the same build output folder. If you need to share assets across multiple frontends or apps, publish a separate folder such as /assets and reference it from the frontend.

Building with AI Agents

AI coding agents can help scaffold and iterate on a custom frontend, especially when you provide the PowerShell Universal constraints up front. Give the agent the request path, framework, API routes, authentication expectations, and build command you plan to use.

PowerShell Universal skills can provide AI agents with reusable PSU-specific instructions, scripts, and references. Devolutions maintains a collection of these skills in the powershell-universal-skills repository. These skills follow the Agent Skills format and can help agents perform common PowerShell Universal tasks with more product-specific context.

For example, the repository includes an install-sandbox-psu skill for installing PowerShell Universal in a sandbox environment for testing and development. You can install the collection with the skills CLI.

npx skills add devolutions/powershell-universal-skills

Once installed, supported coding agents can use the skills automatically when a relevant PowerShell Universal task is detected. This can be useful when you want an agent to create a custom frontend and also set up a local PSU instance, configure supporting resources, or validate the frontend against a sandbox environment.

For example:

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.

Useful details to include in prompts are:

• The framework and package manager to use.
• The published folder request path.
• The expected API endpoint URLs and JSON shapes.
• The OpenAPI document or Swagger URL for the frontend APIs.
• Whether the frontend is public or requires authentication.
• Role-specific behavior the UI should show or hide.
• The build output folder that will be published.
• Any installed PowerShell Universal agent skills the agent should use.

After the agent creates the frontend, review the build configuration, run the production build, and publish only the generated output folder with New-PSUPublishedFolder or the Platform / Published Folders page.