earthworm

Earthworm is an English language learning application that teaches through sentence construction. The core idea is that you practice English by building sentences using conjunctions, which helps you internalize grammar patterns rather than just memorizing vocabulary. The project is open source and built with TypeScript on both the frontend and backend.

Running Earthworm locally requires a few pieces of infrastructure: Node.js 20 or newer, pnpm 8 or newer, PostgreSQL 14, Redis 5, and Docker. Docker is used to run the database and cache services with a single command, which simplifies local setup. After starting those services, you initialize the database schema, upload the course data, then start the backend and frontend servers separately.

The project uses Logto for user authentication, and the README includes initial credentials for the local admin panel. Course content is stored in the database and can be updated with a dedicated command when corrections are needed.

The codebase is structured as a monorepo. The frontend uses Vitest for unit tests and Cypress for end-to-end tests. The backend uses Jest for both unit and integration testing. The README asks contributors to run all tests before committing.

A FAQ section covers common setup problems: database connection failures (usually a missing or misconfigured .env file), pnpm installation errors on Windows related to missing C++ build tools, and Docker permission errors in WSL2 environments on Windows, with step-by-step fixes for each. There is also a brief frontend development guideline discouraging destructuring of Pinia stores and advising against placing UI logic inside composable functions.