How Ontology Playground Handles GitHub Pages Deployment Base Path Configuration

Ontology Playground uses a custom resolveBasePath() function in 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.

# 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 implements this three-tier logic and supplies the result to Vite's base configuration option:

// 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:

# .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:

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:

# .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 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}