Development Environment Setup

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

Prerequisites

Required

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 to manage Node.js versions
Git
- For version control and repository management

Optional (but Recommended)

Docker or Podman
- For sandboxing feature (optional but recommended for security)
- Enables isolated code execution
VS Code
- Recommended IDE with excellent TypeScript support
- Pre-configured launch configurations included

Initial Setup

1. Clone the Repository

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

# 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

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

npm run build

This compiles TypeScript to JavaScript and prepares packages for execution.

Full Build (with Sandbox)

To build everything including the sandbox container:

npm run build:all

This builds:

All packages
Sandbox Docker container
VS Code companion extension

Build Individual Packages

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

npm run dev

This watches for file changes and automatically rebuilds.

Running Qwen Code

From Source

After building, run from the source directory:

npm start

Link Globally

To use qwen-code command from anywhere:

# From the project root
npm link packages/cli

# Now you can use it globally
qwen-code

With Debug Mode

Run with debugging enabled:

# Enable debug mode
DEBUG=1 npm start

# Or for sandbox debugging
DEBUG=1 qwen-code

Testing

Unit Tests

Run all unit tests:

npm run test

Run tests for a specific package:

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

npm run test:e2e

Run with different sandbox modes:

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

npm run test:ci

Code Quality

Linting

Run ESLint:

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

npm run format

Type Checking

Run TypeScript type checker:

npm run typecheck

Preflight Checks

Run all checks before submitting a PR:

npm run preflight

This runs:

Clean build artifacts
Fresh install of dependencies
Code formatting check
Linting (CI mode)
Full build
Type checking
All tests

Sandboxing Setup

Sandboxing is highly recommended for security and requires additional setup.

Enable Sandboxing

Set the environment variable:

# In your ~/.env file
echo "QWEN_SANDBOX=true" >> ~/.env

Docker Setup

If using Docker:

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

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

Launch Configurations (.vscode/launch.json):
- F5 - Start with debugger attached
- “Attach” - Attach to running debug session
- “Launch Program” - Debug current file
Recommended Extensions:
- ESLint
- Prettier
- TypeScript and JavaScript Language Features
Debugger Usage:

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

# Terminal 1: Start CLI in dev mode
DEV=true npm start

# Terminal 2: Launch React DevTools
npx [email protected]

The CLI will automatically connect to React DevTools.

Environment Configuration

Environment Variables

Key environment variables for development:

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

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

Troubleshooting

Common Issues

Node Version Mismatch

# Error: Unsupported Node.js version
# Solution: Use nvm to switch to the correct version
nvm use 20.19.0

Build Failures

# Clean and rebuild
npm run clean
npm install
npm run build

Test Failures

# 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)

# Add your user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

# Or use rootless Docker

Import Resolution Errors

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

Check existing issues
Review the documentation
Ask in discussions
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
Explore the Architecture Overview
Learn about the Tools System
Start with good first issues on GitHub

Contributing

Core Concepts

Tools Reference

​Development Environment Setup

​Prerequisites

​Required

​Optional (but Recommended)

​Initial Setup

​1. Clone the Repository

​2. Install Node.js (if needed)

​3. Install Dependencies

​Build Process

​Basic Build

​Full Build (with Sandbox)

​Build Individual Packages

​Development Mode

​Running Qwen Code

​From Source

​Link Globally

​With Debug Mode

​Testing

​Unit Tests

​Integration Tests

​Test Coverage

​Code Quality

​Linting

​Formatting

​Type Checking

​Preflight Checks

​Sandboxing Setup

​Enable Sandboxing

​Docker Setup

​Podman Setup

​Sandbox Providers

​Development Tools

​VS Code Setup

​React DevTools

​Environment Configuration

​Environment Variables

​Configuration Files

​Troubleshooting

​Common Issues

​Node Version Mismatch

​Build Failures

​Test Failures

​Permission Errors (Docker)

​Import Resolution Errors

​Getting Help

​Next Steps