How to Set Up the Development Environment for everyone-can-use-english: Complete Monorepo Guide

To set up the everyone-can-use-english development environment, install Node ≥20 and Yarn 4, clone the repository, run yarn install to install all workspace dependencies, then use yarn enjoy:dev for the desktop app or yarn docs:dev for the documentation site.

The everyone-can-use-english repository by ZuodaoTech is a Yarn-based monorepo housing an AI-assisted English learning desktop application called Enjoy, a VitePress-powered documentation site, and an optional web portal. This guide walks through the exact commands and configuration files needed to get each workspace running locally.

Prerequisites

Before cloning the repository, ensure your system meets these requirements defined in package.json:

Requirement	Minimum Version	Source Location
Node.js	≥20.0.0	package.json → "engines": { "node": ">=20.0.0" }
Yarn	4.6.0	package.json → "packageManager": "yarn@4.6.0"
Git	Any recent version	—

Yarn 4 is enforced via Corepack. If you haven't used Yarn 4 before, enable it with corepack enable before proceeding.

Step 1: Clone and Install Dependencies

Clone the repository and install all workspace dependencies in a single command:

git clone https://github.com/ZuodaoTech/everyone-can-use-english.git
cd everyone-can-use-english
yarn install

Yarn reads the workspace configuration from the root package.json:

"workspaces": ["enjoy", "1000-hours", "1000h-portal"]

This installs dependencies for three distinct workspaces simultaneously.

Step 2: Start the Enjoy Desktop App

The Enjoy workspace (/enjoy) is the main Electron application providing AI-assisted English learning features.

Development Mode

Run the app with auto-reload and dictionary downloads:

yarn enjoy:dev

This command executes the following sequence from enjoy/package.json (line 12):

rimraf .vite && yarn run download && \
WEB_API_URL=http://localhost:3000 WS_URL=ws://localhost:3000 \
SETTINGS_PATH=${PWD}/enjoy/tmp LIBRARY_PATH=${PWD}/enjoy/tmp \
electron-forge start

The dictionary downloader (enjoy/scripts/download-dictionaries.mjs) fetches required language data on first run.

Production-Style Start

To run without development server overrides:

yarn enjoy:start

Environment Variables

The app accepts these runtime variables that can be set in your shell or a .env file in the enjoy/ directory:

• WEB_API_URL — Backend API endpoint
• WS_URL — WebSocket endpoint
• SETTINGS_PATH — Local settings storage location
• LIBRARY_PATH — Media library storage location

Step 3: Run the Documentation Site

The 1000-hours workspace contains a VitePress-powered documentation site (the "1000 Hours" English learning book).

Start the development server:

yarn docs:dev

This launches the site at http://localhost:5173. The script is defined in the root package.json and forwards to vitepress dev in the 1000-hours workspace.

Build for production:

yarn docs:build      # Outputs to .vitepress/dist/

yarn docs:preview    # Preview the built site locally

Step 4: Run Tests

The Enjoy app includes Playwright-based end-to-end tests covering both Electron processes.

Run the full test suite:

yarn enjoy:test

Run process-specific tests:

yarn enjoy:test:main      # Main process tests only

yarn enjoy:test:renderer  # Renderer process tests only

Test files are located in enjoy/e2e/:

• main.spec.ts — Main process (Node.js/Electron backend)
• renderer.spec.ts — Renderer process (Chromium frontend)

Step 5: Build Production Bundles

Desktop App Installers

Create platform-specific packages:

yarn enjoy:package   # Packaged app without installer

yarn enjoy:make      # OS-specific installers (.deb, .dmg, .rpm, .zip)

Output appears in the out/ directory. The build uses Electron Forge with these makers configured in enjoy/package.json:

• @electron-forge/maker-deb — Debian/Ubuntu packages
• @electron-forge/maker-rpm — Red Hat/Fedora packages
• @electron-forge/maker-zip — Cross-platform archives

Workspace Overview

Workspace	Path	Purpose	Start Command
enjoy	/enjoy	Electron desktop app	yarn enjoy:dev
1000-hours	/1000-hours	VitePress documentation	yarn docs:dev
1000h-portal	/1000h-portal	Next.js web portal (optional)	Not required for basic development

Key Files Reference

File	Description
package.json	Monorepo root: workspaces, Yarn version, top-level scripts
enjoy/package.json	Electron app dependencies, download-dictionaries command, Forge config
enjoy/scripts/download-dictionaries.mjs	Language dictionary downloader
enjoy/e2e/*.spec.ts	Playwright test suites
1000-hours/package.json	VitePress documentation configuration
enjoy/README.md	Additional quick-start instructions

Summary

• Install Node ≥20 and Yarn 4 (Corepack-enabled) before starting
• Clone the repository and run yarn install to populate all three workspaces
• Develop the desktop app with yarn enjoy:dev — dictionaries download automatically
• Preview documentation with yarn docs:dev at localhost:5173
• Test with yarn enjoy:test using Playwright's main and renderer suites
• Build installers with yarn enjoy:make for cross-platform distribution

Frequently Asked Questions

What Node version is required for everyone-can-use-english development?

Node.js 20.0.0 or newer is required, as specified in the root package.json engines field. Older versions will trigger Yarn engine warnings or runtime errors with modern Electron features.

Why does yarn enjoy:dev download files on first run?

The download script executes enjoy/scripts/download-dictionaries.mjs, which fetches required language model files and pronunciation dictionaries. These assets are too large for the Git repository and must be retrieved from external mirrors before the app can perform speech recognition and synthesis.

Can I develop without the 1000h-portal workspace?

Yes. The 1000h-portal workspace is optional and not required for core development. The root package.json includes it in workspaces, but you can ignore it unless specifically contributing to the web portal features.

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