# TUUI Development Setup and Dependency Management: Complete Guide

> Master TUUI development setup and dependency management with this guide. Learn about its Electron-Vite-Vue architecture and package.json configuration for efficient cross-platform packaging.

- Repository: [AIQL/tuui](https://github.com/ai-ql/tuui)
- Tags: how-to-guide
- Published: 2026-02-23

---

**TUUI uses an Electron-Vite-Vue architecture with Node.js 22.12.0+, managed through a single [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json) that defines strict engine requirements, runtime libraries, and build scripts for cross-platform desktop packaging.**

The `ai-ql/tuui` repository is a modern desktop application built on Vue 3 and Electron. All development tooling, dependency constraints, and build orchestration are centralized in the root [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json), enabling reproducible installs via lockfile enforcement. This guide breaks down the exact dependency versions, npm scripts, and configuration files that power the development workflow.

## Project Architecture and Tech Stack

TUUI is structured as a **Vue 3** single-page application running inside an **Electron** native shell, bundled by **Vite 7** for rapid hot-module replacement during development.

### Electron-Vite-Vue Foundation

The stack combines:
- **Vue 3** (`^3.5.28`) with Composition API for the renderer process UI
- **Vuetify 3** (`^3.11.8`) for Material Design components
- **Pinia** (`^3.0.4`) for state management and **Vue-Router** (`^5.0.2`) for client-side navigation
- **Electron** (`^40.4.1`) providing the native desktop window and Node.js runtime
- **Vite 7** (`^7.3.1`) as the build tool and development server

### Node.js Engine Requirements

The project enforces a minimum Node.js version to ensure compatibility with modern ECMAScript features and security patches. In [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json) lines 46-48, the `engines` field specifies:

```json
{
  "engines": {
    "node": ">=22.12.0"
  }
}

```

This constraint guarantees that developers use Node.js 22.12.0 or newer, preventing runtime errors from unsupported syntax or API changes.

## Runtime Dependencies

The `dependencies` section in [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json) (lines 49-71) defines libraries required in the production bundle. Key runtime dependencies include:

- **`vue`** (`^3.5.28`) – Core UI framework
- **`vuetify`** (`^3.11.8`) – Component library with Material Design 3
- **`pinia`** (`^3.0.4`) – TypeScript-friendly state management
- **`vue-router`** (`^5.0.2`) – Declarative routing for SPA navigation
- **`electron`** (`^40.4.1`) – Desktop shell and main process APIs
- **`@anthropic-ai/mcpb`** and **`@modelcontextprotocol/sdk`** – AI/LLM integration tools
- **`@nut-tree-fork/nut-js`** – Native UI automation and control
- **[`highlight.js`](https://github.com/ai-ql/tuui/blob/main/highlight.js)**, **`katex`**, **`mermaid`** – Syntax highlighting and diagram rendering
- **`localforage`** – Offline-capable storage wrapper
- **`md-editor-v3`** – Markdown editing component

These packages are bundled into the final Electron application by the build pipeline.

## Development Dependencies and Tooling

The `devDependencies` section (lines 73-99) contains build-time tools and type definitions that are not shipped to end users.

### Vite Plugin Ecosystem

TUUI leverages several Vite-specific plugins defined in [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json):
- **`vite-plugin-electron`** and **`vite-plugin-electron-renderer`** – Bridge Vite's dev server with Electron's main and renderer processes
- **`vite-plugin-vuetify`** – On-demand Vuetify component tree-shaking
- **`@vitejs/plugin-vue`** and **`@vitejs/plugin-vue-jsx`** – Vue 3 SFC and JSX support

### Type Checking and Linting

- **`typescript`** (`^5.9.3`) – Static type system
- **`vue-tsc`** (`^3.2.4`) – Type-checking for Vue single-file components via `vue-tsc --noEmit`
- **`eslint`** with Vue and Prettier configurations – Code quality enforcement
- **`prettier`** – Opinionated code formatting

### Testing and Packaging

- **`@playwright/test`** – End-to-end testing framework executed via `npm test`
- **`electron-builder`** – Creates distributable installers for Windows, macOS, and Linux

## NPM Scripts and Build Workflow

The `scripts` field in [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json) (lines 24-45) orchestrates the entire development lifecycle from hot-reloading to production packaging.

### Development Server (Hot Module Replacement)

The primary development command starts Vite's dev server and Electron simultaneously:

```bash
npm run dev

```

This executes the `dev` script, which launches Vite on `http://localhost:5173`. The Electron main process loads this URL via the `debug.env.VITE_DEV_SERVER_URL` configuration defined in [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json) lines 19-23, enabling instant UI updates without restarting the desktop shell.

### Production Build Pipeline

The build process uses a two-stage approach:

1. **`npm run build:pre`** – Runs formatting checks, TypeScript compilation (`vue-tsc --noEmit`), and Vite production bundling
2. **`npm run build`** – Executes `build:pre` followed by `electron-builder` to generate platform-specific installers (`.exe`, `.dmg`, `.AppImage`)

For macOS-specific builds, the repository provides `npm run build:mac`, which chains `build:pre` with Electron-Builder configured for Apple platforms.

### Code Quality and Testing

Linting and formatting scripts enforce consistency before commits:

```bash
npm run lint        # ESLint check

npm run lint:fix    # Auto-fix ESLint errors

npm run format      # Prettier check

npm run format:fix  # Auto-format with Prettier

```

The test suite runs via:

```bash
npm test

```

This executes `build:pre` first to ensure type safety, then launches Playwright for end-to-end testing.

## Key Configuration Files

Beyond [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json), the development setup relies on several configuration files:

| File | Purpose |
|------|---------|
| `vite.config.mts` | Vite configuration integrating Vue, Vuetify, and Electron plugins |
| [`src/renderer/main.ts`](https://github.com/ai-ql/tuui/blob/main/src/renderer/main.ts) | Entry point for the Vue application inside the Electron renderer process |
| [`src/main/index.ts`](https://github.com/ai-ql/tuui/blob/main/src/main/index.ts) | Entry point for the Electron main (Node.js) process |
| [`buildAssets/builder/config.js`](https://github.com/ai-ql/tuui/blob/main/buildAssets/builder/config.js) | Electron-Builder settings for code signing, icons, and target platforms |
| [`src/renderer/plugins/vuetify.ts`](https://github.com/ai-ql/tuui/blob/main/src/renderer/plugins/vuetify.ts) | Vuetify theme, icon font, and internationalization setup |
| [`src/renderer/plugins/i18n.ts`](https://github.com/ai-ql/tuui/blob/main/src/renderer/plugins/i18n.ts) | Vue-i18n configuration for multi-language support |

## Local Development Quickstart

To set up the TUUI development environment:

1. **Clone and install dependencies** using the lockfile for exact version reproducibility:

   ```bash
   git clone https://github.com/ai-ql/tuui.git
   cd tuui
   npm ci
   ```

2. **Start the development server** with hot-reloading:

   ```bash
   npm run dev
   ```

3. **Verify code quality** before submitting changes:

   ```bash
   npm run lint
   npm run format
   ```

4. **Run the test suite** to validate functionality:

   ```bash
   npm test
   ```

5. **Build the production application**:

   ```bash
   npm run build
   ```

## Summary

- **Node.js 22.12.0+** is required, enforced by the `engines` field in [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json)
- **Runtime stack** includes Vue 3, Vuetify 3, Pinia, and Electron 40, defined in `dependencies` (lines 49-71)
- **Development tools** include Vite 7, TypeScript 5.9, ESLint, Prettier, and Playwright, listed in `devDependencies` (lines 73-99)
- **`npm run dev`** starts the Vite dev server on port 5173, loaded by Electron for instant HMR feedback
- **`npm run build`** executes type-checking, linting, Vite bundling, and Electron-Builder packaging
- **Configuration** is split between `vite.config.mts` for bundling and [`buildAssets/builder/config.js`](https://github.com/ai-ql/tuui/blob/main/buildAssets/builder/config.js) for installer generation

## Frequently Asked Questions

### What Node.js version is required for TUUI development?

TUUI requires **Node.js 22.12.0 or newer**, as specified in the `engines` field of [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json) (lines 46-48). This ensures compatibility with the modern JavaScript features used by Vite 7 and Electron 40. Attempting to install dependencies with an older version will trigger an engine mismatch error from npm.

### How does TUUI handle dependency installation reproducibility?

The project uses **[`package-lock.json`](https://github.com/ai-ql/tuui/blob/main/package-lock.json)** alongside the `npm ci` command. Unlike `npm install`, which may update versions based on semver ranges, `npm ci` installs exact versions recorded in the lockfile. This guarantees that every developer and CI pipeline uses identical dependency trees, preventing "works on my machine" issues with Electron or Vite plugins.

### What is the difference between `build:pre` and `build` scripts?

The **`build:pre`** script performs validation and compilation steps: it runs Prettier formatting checks, executes `vue-tsc --noEmit` for TypeScript type checking, and triggers Vite's production build. The **`build`** script calls `build:pre` first, then runs `electron-builder` to package the compiled code into OS-specific installers. This separation allows the CI pipeline to fail fast on type errors before attempting the slower packaging step.

### How do I add a new runtime library to TUUI?

Install the package as a production dependency using npm:

```bash
npm install library-name@^version

```

This updates the `dependencies` section in [`package.json`](https://github.com/ai-ql/tuui/blob/main/package.json) automatically. After installation, import the library in your Vue components or Electron main process code. Always run `npm run build:pre` afterward to ensure the new dependency does not introduce TypeScript compilation errors before committing.