Configuration Files in the holaOS Apps Directory: Complete Reference Guide

The apps directory in holaboss-ai/holaOS contains two main applications—docs and desktop—each with specialized configuration files including Vite, TypeScript, Wrangler, and TSUP configs that govern building, bundling, type-checking, and runtime behavior.

The holaOS repository organizes its applications within the apps folder, where each sub-project maintains isolated configuration files optimized for its specific deployment target. Understanding these configuration files in the holaOS apps directory is essential for customizing build pipelines, managing environment variables, and optimizing runtime performance for both the browser-based documentation site and the native desktop client.

Docs Application Configuration

The docs application serves the holaOS documentation site through a Cloudflare worker, utilizing a modern React-based stack with specialized tooling for static site generation and edge deployment.

vite.config.ts

The apps/docs/vite.config.ts file defines the Vite build configuration for the documentation site, handling plugin composition, path aliasing, and CSS preprocessing. This configuration manages how the documentation UI is bundled for production deployment.

wrangler.jsonc

The apps/docs/wrangler.jsonc file contains Cloudflare Wrangler configuration, specifying environment variables, KV bindings, and routing rules for the Cloudflare worker that serves the docs site. This JSONC file supports comments and defines the edge deployment parameters.

tsconfig.json

Located at apps/docs/tsconfig.json, this file specifies TypeScript compiler options specific to the docs application, including strict type-checking rules and module resolution strategies tailored for the documentation codebase.

react-router.config.ts

The apps/docs/react-router.config.ts file configures React Router routes for the documentation UI, defining the navigation structure and route hierarchies that power the client-side routing experience.

source.config.ts

The apps/docs/source.config.ts file provides custom source-file mapping used by the docs site generator, enabling the application to locate and render documentation content from specific source directories.

worker-configuration.d.ts

The apps/docs/worker-configuration.d.ts file contains TypeScript type definitions for the Cloudflare worker environment, ensuring type safety when accessing worker-specific globals and bindings within the docs application code.

Desktop Application Configuration

The desktop application compiles to a native executable using a combination of Vite for the UI layer and TSUP for the final bundling process, with environment-specific settings managed through dedicated configuration files.

vite.config.ts

The apps/desktop/vite.config.ts file configures Vite for the desktop UI, including custom plugins and environment handling specific to Electron-like runtime contexts. This setup handles the renderer process bundling with React support.

tsup.config.ts

The apps/desktop/tsup.config.ts file defines TSUP bundler configuration, specifying how the desktop application compiles to a single executable. This configuration manages entry points, external dependencies, and output formats for the production build.

tsconfig.json

The apps/desktop/tsconfig.json file contains TypeScript compiler settings specific to the desktop project, often including Node.js and Electron type definitions alongside the standard React TypeScript configuration.

.env.example

Located at apps/desktop/.env.example, this template file documents required runtime environment variables such as API keys and service endpoints. Developers copy this file to .env and populate it with actual values for local development.

Practical Configuration Examples

When extending the desktop application build pipeline, modify the Vite configuration to include custom path aliases:

// apps/desktop/vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      // Example: map "@components" to the components folder
      '@components': '/src/components',
    },
  },
});

For the documentation site, integrate CSS preprocessors by extending the Vite configuration:

// apps/docs/vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import tailwindcss from 'tailwindcss';

export default defineConfig({
  plugins: [react()],
  css: {
    postcss: {
      plugins: [tailwindcss],
    },
  },
});

When implementing runtime configuration for the desktop app, reference the environment variable template:

// apps/desktop/src/main.tsx
const apiKey = process.env.NEXT_PUBLIC_API_KEY ?? 'YOUR_API_KEY_HERE';
console.log('API Key:', apiKey);

Summary

• The apps directory contains distinct configuration sets for the docs and desktop applications, each optimized for their respective runtime environments.
• Docs configuration files include wrangler.jsonc for Cloudflare deployment, worker-configuration.d.ts for worker types, and react-router.config.ts for client-side routing.
• Desktop configuration files leverage tsup.config.ts for executable bundling and .env.example for runtime variable documentation.
• Both applications use vite.config.ts and tsconfig.json files, though with environment-specific settings for browser versus native execution contexts.
• According to the holaboss-ai/holaOS source code, modifying these configuration files directly controls how each sub-application compiles, serves, and executes in production environments.

Frequently Asked Questions

What is the purpose of the wrangler.jsonc file in the docs app?

The wrangler.jsonc file configures Cloudflare Wrangler deployment settings for the documentation site, including KV namespace bindings, environment variables, and routing rules. This JSONC format allows comments and defines how the docs application deploys to Cloudflare's edge network.

How does the desktop application differ from the docs app in terms of bundling?

While both use Vite for development builds, the desktop application specifically utilizes tsup.config.ts to bundle the final output into a single executable file suitable for native desktop environments. The docs app relies on Cloudflare Workers for deployment rather than native executables.

Why are there separate tsconfig.json files for each app?

Each tsconfig.json file contains TypeScript compiler options tailored to the specific application's runtime environment. The desktop configuration includes Node.js and Electron type definitions, whereas the docs configuration focuses on browser and Cloudflare Worker globals, ensuring accurate type-checking for their distinct platforms.

What environment variables should be configured for the desktop app?

The apps/desktop/.env.example file serves as a template for required runtime variables, typically including API keys, service endpoints, and feature flags. Developers should copy this file to .env and populate it with actual values, as the desktop application reads these variables during initialization to configure external service connections.

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