# How Ontology Playground Handles GitHub Pages Deployment Base Path Configuration

> Learn how Ontology Playground automatically configures GitHub Pages deployment base paths using a custom Vite function. Discover how it detects repository names and allows manual overrides for seamless deployment.

- Repository: [Microsoft/Ontology-Playground](https://github.com/microsoft/Ontology-Playground)
- Tags: how-to-guide
- Published: 2026-07-21

---

**Ontology Playground uses a custom `resolveBasePath()` function in [`vite.config.ts`](https://github.com/microsoft/Ontology-Playground/blob/main/vite.config.ts) that automatically detects GitHub Actions environments to derive the repository name for the base path, while allowing full override via the `VITE_BASE_PATH` environment variable.**

The Microsoft Ontology-Playground repository automates its **GitHub Pages deployment base path configuration** through a conditional resolution strategy implemented directly in its Vite build configuration. This approach ensures that static assets, route links, and imports resolve correctly whether the application runs from a project page (`https://<owner>.github.io/<repo-name>/`), a custom domain root, or a local development server.

## How the Base Path Resolution Works

The system evaluates three conditions in strict priority order to determine the correct URL prefix for the Vite build.

### Explicit Environment Variable Override

If the `VITE_BASE_PATH` variable is defined in the environment, its value is used directly as the base path without further processing. This takes precedence over all automatic detection logic.

```bash

# Any build environment

VITE_BASE_PATH=/my/custom/prefix/

```

### Automatic GitHub Actions Detection

When the build runs inside GitHub Actions (`GITHUB_ACTIONS` equals `'true'`) and the repository identifier is available (`GITHUB_REPOSITORY`), the code extracts the repository name from the `owner/repo-name` format. It then constructs the base path as `/<repo-name>/`, which matches the default GitHub Pages project site structure.

### Local Development Fallback

If neither the override variable nor the GitHub Actions environment is detected, the function returns `'/'`. This configures the application to assume it will be served from the domain root, which is appropriate for `npm run dev` or root-hosted deployments.

## Implementation in vite.config.ts

The `resolveBasePath()` function in [`vite.config.ts`](https://github.com/microsoft/Ontology-Playground/blob/main/vite.config.ts) implements this three-tier logic and supplies the result to Vite's `base` configuration option:

```typescript
// vite.config.ts – base-path handling
function resolveBasePath(): string {
  if (process.env.VITE_BASE_PATH) return process.env.VITE_BASE_PATH;

  // GitHub Actions: infer base from repo name when deploying to GitHub Pages
  if (process.env.GITHUB_ACTIONS === 'true' && process.env.GITHUB_REPOSITORY) {
    const [, repoName] = process.env.GITHUB_REPOSITORY.split('/');
    if (repoName) return `/${repoName}/`;
  }

  // Fallback for local dev or custom hosting
  return '/';
}

```

This ensures all generated asset URLs and router base configurations receive the correct prefix for the target hosting environment.

## Configuration Examples

### Custom Base Path for Local Development

To test a specific base path locally without modifying the source code, create a `.env.local` file in the project root:

```bash

# .env.local

VITE_BASE_PATH=/ontology-playground/v2/

```

Running `npm run build` will now embed `/ontology-playground/v2/` as the prefix for all static assets and relative links.

### Default GitHub Pages Deployment

When GitHub Actions triggers a build, the following environment variables are automatically populated:

```bash
GITHUB_ACTIONS=true
GITHUB_REPOSITORY=microsoft/Ontology-Playground

```

The `resolveBasePath()` function splits `GITHUB_REPOSITORY` to extract `"Ontology-Playground"` and returns `"/Ontology-Playground/"`. This matches the exact URL path where GitHub Pages serves the site at `https://microsoft.github.io/Ontology-Playground/`.

### Overriding in GitHub Actions Workflows

To deploy with a custom base path even when using GitHub Actions, explicitly set the variable in your workflow file:

```yaml

# .github/workflows/deploy.yml

env:
  VITE_BASE_PATH: /custom-path/
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm ci && npm run build

```

Because `VITE_BASE_PATH` is defined, the build ignores the automatic repository name detection and uses `/custom-path/` instead.

## Summary

- The **base path resolution** logic resides in [`vite.config.ts`](https://github.com/microsoft/Ontology-Playground/blob/main/vite.config.ts) within the `resolveBasePath()` function.
- **Priority order**: `VITE_BASE_PATH` environment variable → GitHub Actions auto-detection (`GITHUB_REPOSITORY`) → root path (`'/'`) fallback.
- Automatic detection parses the `GITHUB_REPOSITORY` environment variable to derive the `/<repo-name>/` prefix required for standard GitHub Pages project sites.
- Developers can override any automatic behavior by setting `VITE_BASE_PATH` in local `.env` files or CI workflow configurations, ensuring flexibility for custom domains or subdirectory deployments.

## Frequently Asked Questions

### What happens if I don't set any environment variables?

If neither `VITE_BASE_PATH` nor the GitHub Actions environment variables are present, `resolveBasePath()` returns `'/'`. According to the source code in [`vite.config.ts`](https://github.com/microsoft/Ontology-Playground/blob/main/vite.config.ts), this configures the application to run from the domain root, which is the correct behavior for local development using `npm run dev` or for deployments to custom domains hosted at the root path.

### How does Ontology Playground detect GitHub Pages automatically?

The detection relies on standard GitHub Actions environment variables. When a workflow runs, `GITHUB_ACTIONS` is set to `'true'` and `GITHUB_REPOSITORY` contains the string `owner/repo-name`. The code splits this string to isolate the repository name and returns it wrapped in forward slashes (e.g., `/Ontology-Playground/`), which aligns with the default GitHub Pages project site URL pattern.

### Can I use a custom domain with this base path configuration?

Yes. For custom domains served from the root (such as `https://ontology.example.com/`), the default fallback to `'/'` works automatically without configuration changes. If your custom domain serves the application from a subdirectory (e.g., `https://example.com/playground/`), set `VITE_BASE_PATH=/playground/` in your build environment to ensure assets load correctly.

### Where is the base path logic defined in the source code?

The configuration is defined in [`vite.config.ts`](https://github.com/microsoft/Ontology-Playground/blob/main/vite.config.ts) at the root of the Microsoft Ontology-Playground repository. Specifically, the `resolveBasePath()` function contains the logic for checking `process.env.VITE_BASE_PATH`, detecting `GITHUB_ACTIONS` and `GITHUB_REPOSITORY`, and providing the fallback value. This function is passed directly to the `base` property in the Vite configuration object exported from the file.