# ui

**Repository Path**: temporalio/ui

## Basic Information

- **Project Name**: ui
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-29
- **Last Updated**: 2025-12-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Temporal UI

## Prerequisites

Temporal must be running in development.

Temporal UI requires [Temporal v1.16.0](https://github.com/temporalio/temporal/releases/tag/v1.16.0) or later.

Make sure [Corepack](https://pnpm.io/installation#using-corepack) is installed and run `corepack enable pnpm`. 

### Using Temporal CLI

You can install [Temporal CLI][] using [Homebrew][]:

```sh
brew install temporal
```

You can start a Temporal server in development using the following command:

```sh
temporal server start-dev
```

[temporal cli]: https://github.com/temporalio/cli
[homebrew]: https://brew.sh

## Development

### Local Development

#### Setup

Once you have the prerequisites going, run the following:

```bash
pnpm install
```

Running `pnpm install` will attempt to download and install the most recent version of [Temporal CLI][] into `./bin/cli/temporal`. The development server will attempt to use use this version of this Temporal when starting up.

- If that port is already in use, the UI will fallback to trying to talk to whatever process is running on that port.
- If you do not have a version of Temporal CLI at `./bin/cli/temporal`, the development server will look for a version of Temporal CLI in your path.
- For Windows users, you will need to start Temporal using one of the methods listed above until we have sufficiently tested this functionality on Windows. (We would absolutely welcome a pull request.)

```bash
git submodule update
```

This clones the [Temporal API Protos](https://github.com/temporalio/api) into the git submodule, which is required for local development of the UI when running against a local version of the UI server.


To run a local development version of the Svelte application via Vite, run `pnpm dev`. The application will run on [http://localhost:3000]() against a local ui-server running along with Temporal server from the temporal-cli.

```bash
pnpm dev
```

Alternatively, you can run `pnpm dev:temporal-cli` to run against the version of ui-server and Temporal server included temporal-cli.
```bash
pnpm dev:temporal-cli
```

### Building the UI

The Temporal UI can be built for local preview. You must set the `VITE_TEMPORAL_UI_BUILD_TARGET` environment variable in order to build the assets. This will be set for you if you use either of the following `pnpm` scripts. The resulting assets will be placed in `./dist`.

> You can preview the built app with `pnpm run preview`, regardless of whether you installed an adapter. This should _not_ be used to serve your app in production.


```bash
pnpm build:local
```


The Temporal UI can build assets for ui-server. The resulting assets will be placed in `./server/ui/assets`.

```bash
pnpm build:server
```

### Using Docker

After pulling down the lastest version of Temporal's [`docker-compose`](https://github.com/temporalio/docker-compose), you can access the UI by visiting `http://localhost:8080`.

If you want to point the development environment at the `docker-compose` version of Temporal, you can use the following command:

```bash
pnpm dev:docker
```

```bash
pnpm run build:docker
pnpm run preview:docker
```


### Running UI and Temporal Server locally

1. In `temporal` repo, run Temporal server locally
    
```diff
make start
```

2. In `ui` repo, add .env.local-temporal file with the following env variables

```diff
VITE_TEMPORAL_PORT="7134"
VITE_API="http://localhost:8081"
VITE_MODE="development"
VITE_TEMPORAL_UI_BUILD_TARGET="local"
```

3. Run UI with pnpm dev:local-temporal

```diff
pnpm dev:local-temporal
```

4. Create namespace with CLI (Temporal server does not do this automatically unlike CLI)

```diff
temporal operator namespace create default
```

## OSS API Development

### Understanding OSS API Endpoints

When developing new features that require API endpoints for the OSS version of Temporal, the available APIs can be found in the [Temporal API repository](https://github.com/temporalio/api). These gRPC APIs are converted to HTTP through the ui-server's gRPC proxy.

**Key Resources:**
- **API Definitions**: https://github.com/temporalio/api/tree/master/temporal/api
- **Service Definitions**: Look for `*_service.proto` files for available operations
- **HTTP Conversion**: The ui-server automatically converts gRPC calls to HTTP endpoints

**Common API Patterns:**
- **WorkflowService**: `temporal/api/workflowservice/v1/service.proto` - Core workflow operations
- **OperatorService**: `temporal/api/operatorservice/v1/service.proto` - Administrative operations (search attributes, clusters, etc.)
- **Endpoint Mapping**: gRPC service methods map to HTTP POST endpoints at `/api/v1/{service}/{method}`

**Example:**
- gRPC: `temporal.api.operatorservice.v1.OperatorService.ListSearchAttributes`
- HTTP: `POST /api/v1/operator/list-search-attributes`

**Finding Available Operations:**
1. Browse the API repository to find relevant service files
2. Look for existing method definitions in `*_service.proto` files
3. Check if the operation you need already exists before requesting new endpoints
4. For new operations, coordinate with the SDK team to add them to the appropriate service

**Development Workflow:**
1. Check existing API definitions for required operations
2. Use existing endpoints where possible via services in `src/lib/services/`
3. For missing endpoints, create adapters with TODO comments (like in `SearchAttributesAdapter`)
4. Coordinate with SDK team to implement missing gRPC methods
5. Update adapters once endpoints are available

## Testing
We use [Playwright](https://playwright.dev) to interactively test the Temporal UI.

### Running the E2E tests
The e2e tests run against the UI with workflows via the [TypeScript SDK](https://github.com/temporalio/sdk-typescript), a locally built version of the UI Server, a NodeJS/Express Codec Server, and a Temporal dev server via [Temporal CLI](https://github.com/temporalio/cli)

`pnpm test:e2e`

### Running the Integration tests
The integration tests run against the UI using Mocks

`pnpm test:integration`

Both `pnpm test:e2e` and `pnpm test:integration` use the `playwright.config.ts` at the root of the repo. This file will [run the UI via the vite development server](https://playwright.dev/docs/api/class-testconfig#test-config-web-server) with the correct configuration by running either `pnpm serve:playwright:e2e` or `pnpm serve:playwright:integration`. It will also invoke the default function in `tests/globalSetup.ts`, which instantiates all of the necessary dependencies (UI Server, Codec Server, Temporal Server, Temporl Workers, etc.) when running in e2e mode.

## Configuration

Set these environment variables if you want to change their defaults

| Variable  | Description                                                      | Default               | Stage |
| --------- | ---------------------------------------------------------------- | --------------------- | ----- |
| VITE_API  | Temporal HTTP API address. Set to empty `` to use relative paths | http://localhost:8322 | Build |
| VITE_MODE | Build target                                                     | development           | Build |
| UI_SERVER_VERBOSE | Enable verbose output to see Air build logs and server output for debugging | false | Development |
| UI_SERVER_HOT_RELOAD | Enable hot reload using Air                           | false | Development |

## Releases

This repository uses an automated release management system that enforces version bump PRs before releases and maintains dual version sync between `package.json` and `server/server/version/version.go`.

### Release Management

The release system uses custom GitHub Actions for modular, reusable functionality. See [GitHub Workflows Documentation](.github/WORKFLOWS.md) for detailed information about the 8 custom actions and 3 workflows.

**Release Process**:
1. **Version Bump**: Use Actions → "Version Bump" to create a PR with updated versions
   - **Auto mode**: Analyzes commits since last tag for semantic versioning
   - **Manual mode**: Specify major/minor/patch bump type
   - **Specific version**: Override with exact version (e.g., "2.38.0")
   - **Dry run**: Preview changes without making modifications
2. **Review and Merge**: Review the auto-generated version bump PR and merge to main
3. **Draft Release**: Automatically created when version changes are detected
4. **Publish Release**: Review and publish the auto-generated draft release
5. **UI-server Release**: A published release automatically triggers a matching release in the ui-server repository

**Version Source of Truth**: The Go `UIVersion` constant in `server/server/version/version.go` is the authoritative source. All validation uses this as the reference, and `package.json` must be kept in sync.

**Version Validation**: 
- Run `pnpm validate:versions` to ensure version files are in sync and ready for release
- Validation compares against last git tag (not last commit) for robust release workflows
- Custom actions provide detailed validation and error messages

**Integration**:
- Draft releases trigger downstream ui-server releases and Docker image publishing
- UI repo releases (https://github.com/temporalio/ui/releases) contain the latest UI artifacts
- Our [npm package](https://www.npmjs.com/package/@temporalio/ui) will be manually published as needed.
- UI-server repo releases (https://github.com/temporalio/ui-server/releases) manage Docker images