> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Environment Setup

> Setting up your development environment for Qwen Code

# Development Environment Setup

This guide will help you set up your development environment for contributing to Qwen Code.

## Prerequisites

### Required

1. **Node.js**
   * **Development:** Use Node.js `~20.19.0` (specific version required due to upstream dependency issue)
   * **Production:** Any version `>=20.0.0` works for running the CLI
   * **Recommended:** Use [nvm](https://github.com/nvm-sh/nvm) to manage Node.js versions

2. **Git**
   * For version control and repository management

### Optional (but Recommended)

3. **Docker or Podman**
   * For sandboxing feature (optional but recommended for security)
   * Enables isolated code execution

4. **VS Code**
   * Recommended IDE with excellent TypeScript support
   * Pre-configured launch configurations included

## Initial Setup

### 1. Clone the Repository

```bash theme={null}
# Clone the repository
git clone https://github.com/QwenLM/qwen-code.git

# Or clone your fork
git clone https://github.com/YOUR_USERNAME/qwen-code.git

# Navigate to the directory
cd qwen-code
```

### 2. Install Node.js (if needed)

Using nvm (recommended):

```bash theme={null}
# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Install the required Node.js version
nvm install 20.19.0
nvm use 20.19.0

# Verify installation
node --version  # Should show v20.19.0
```

### 3. Install Dependencies

```bash theme={null}
# Install all dependencies (root and workspaces)
npm install
```

This will install dependencies for all packages in the monorepo.

## Build Process

### Basic Build

Build all packages:

```bash theme={null}
npm run build
```

This compiles TypeScript to JavaScript and prepares packages for execution.

### Full Build (with Sandbox)

To build everything including the sandbox container:

```bash theme={null}
npm run build:all
```

This builds:

* All packages
* Sandbox Docker container
* VS Code companion extension

### Build Individual Packages

```bash theme={null}
# Build only packages (skip sandbox and extras)
npm run build:packages

# Build VS Code extension only
npm run build:vscode

# Build sandbox only
npm run build:sandbox
```

### Development Mode

For faster development with hot reload:

```bash theme={null}
npm run dev
```

This watches for file changes and automatically rebuilds.

## Running Qwen Code

### From Source

After building, run from the source directory:

```bash theme={null}
npm start
```

### Link Globally

To use `qwen-code` command from anywhere:

```bash theme={null}
# From the project root
npm link packages/cli

# Now you can use it globally
qwen-code
```

### With Debug Mode

Run with debugging enabled:

```bash theme={null}
# Enable debug mode
DEBUG=1 npm start

# Or for sandbox debugging
DEBUG=1 qwen-code
```

## Testing

### Unit Tests

Run all unit tests:

```bash theme={null}
npm run test
```

Run tests for a specific package:

```bash theme={null}
# Test core package only
npm run test --workspace=packages/core

# Test CLI package only
npm run test --workspace=packages/cli
```

### Integration Tests

Run integration tests without sandbox:

```bash theme={null}
npm run test:e2e
```

Run with different sandbox modes:

```bash theme={null}
# With Docker sandbox
npm run test:integration:sandbox:docker

# With Podman sandbox
npm run test:integration:sandbox:podman

# All sandbox modes
npm run test:integration:all
```

### Test Coverage

Generate coverage reports:

```bash theme={null}
npm run test:ci
```

## Code Quality

### Linting

Run ESLint:

```bash theme={null}
# Check for linting errors
npm run lint

# Fix auto-fixable issues
npm run lint:fix

# Lint with zero warnings (CI mode)
npm run lint:ci
```

### Formatting

Format code with Prettier:

```bash theme={null}
npm run format
```

### Type Checking

Run TypeScript type checker:

```bash theme={null}
npm run typecheck
```

### Preflight Checks

Run all checks before submitting a PR:

```bash theme={null}
npm run preflight
```

This runs:

1. Clean build artifacts
2. Fresh install of dependencies
3. Code formatting check
4. Linting (CI mode)
5. Full build
6. Type checking
7. All tests

## Sandboxing Setup

Sandboxing is highly recommended for security and requires additional setup.

### Enable Sandboxing

Set the environment variable:

```bash theme={null}
# In your ~/.env file
echo "QWEN_SANDBOX=true" >> ~/.env
```

### Docker Setup

If using Docker:

```bash theme={null}
# Build sandbox container
npm run build:sandbox

# Verify Docker is running
docker ps

# Test sandbox
QWEN_SANDBOX=docker npm start
```

### Podman Setup

If using Podman:

```bash theme={null}
# Enable Podman sandbox
QWEN_SANDBOX=podman npm start
```

### Sandbox Providers

Supported sandbox providers:

* `docker` - Docker Desktop (recommended for most users)
* `podman` - Podman (alternative to Docker)
* `macOS Seatbelt` - macOS native sandboxing
* `false` - Disable sandboxing (not recommended)

## Development Tools

### VS Code Setup

The project includes pre-configured VS Code settings:

1. **Launch Configurations** (`.vscode/launch.json`):
   * `F5` - Start with debugger attached
   * "Attach" - Attach to running debug session
   * "Launch Program" - Debug current file

2. **Recommended Extensions**:
   * ESLint
   * Prettier
   * TypeScript and JavaScript Language Features

3. **Debugger Usage**:

```bash theme={null}
# Start in debug mode
npm run debug

# Then in VS Code, use "Attach" configuration
# Or press F5 to launch directly
```

### React DevTools

For debugging the CLI's React UI:

```bash theme={null}
# Terminal 1: Start CLI in dev mode
DEV=true npm start

# Terminal 2: Launch React DevTools
npx react-devtools@4.28.5
```

The CLI will automatically connect to React DevTools.

## Environment Configuration

### Environment Variables

Key environment variables for development:

```bash theme={null}
# Debug mode
DEBUG=1

# Sandbox mode
QWEN_SANDBOX=docker  # or podman, or false

# API configuration (for testing)
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o

# Development mode (enables React DevTools)
DEV=true

# Verbose output (for integration tests)
VERBOSE=true

# Keep test output (for debugging tests)
KEEP_OUTPUT=true
```

### Configuration Files

Configuration hierarchy:

1. **Project settings**: `.qwen/settings.json` (project-specific)
2. **User settings**: `~/.qwen/settings.json` (global)
3. **Environment variables**: Override any setting
4. **CLI arguments**: Highest priority

## Troubleshooting

### Common Issues

#### Node Version Mismatch

```bash theme={null}
# Error: Unsupported Node.js version
# Solution: Use nvm to switch to the correct version
nvm use 20.19.0
```

#### Build Failures

```bash theme={null}
# Clean and rebuild
npm run clean
npm install
npm run build
```

#### Test Failures

```bash theme={null}
# Run tests with verbose output
VERBOSE=true npm run test

# Keep test output for inspection
KEEP_OUTPUT=true npm run test:e2e
```

#### Permission Errors (Docker)

```bash theme={null}
# Add your user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

# Or use rootless Docker
```

#### Import Resolution Errors

```bash theme={null}
# Error: Cannot find module
# Solution: Rebuild and ensure .js extensions in imports
npm run build

# Check that imports use .js extension:
# ✅ import { x } from './file.js'
# ❌ import { x } from './file'
```

### Getting Help

If you encounter issues:

1. Check [existing issues](https://github.com/QwenLM/qwen-code/issues)
2. Review the [documentation](https://qwenlm.github.io/qwen-code-docs/)
3. Ask in [discussions](https://github.com/QwenLM/qwen-code/discussions)
4. Open a new issue with:
   * Node.js version (`node --version`)
   * npm version (`npm --version`)
   * OS and version
   * Error messages and stack traces

## Next Steps

Now that your environment is set up:

* Read the [Contributing Guidelines](./contributing.mdx)
* Explore the [Architecture Overview](./architecture.mdx)
* Learn about the [Tools System](./tools-system.mdx)
* Start with good first issues on GitHub