# How to Debug Issues in everyone-can-use-english: A Complete Troubleshooting Guide

> Debug everyone-can-use-english issues effectively by running local instances, inspecting logs, and validating configurations. Our guide simplifies troubleshooting for this Cloudflare Worker and Vite frontend.

- Repository: [Zuodao/everyone-can-use-english](https://github.com/ZuodaoTech/everyone-can-use-english)
- Tags: how-to-guide
- Published: 2026-08-14

---

**The most effective way to debug everyone-can-use-english is running both the Cloudflare Worker (`npx wrangler dev`) and Vite frontend (`npm run dev`) locally, then inspecting console logs, validating configuration files, and checking environment variables in [`entry/wrangler.toml`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/wrangler.toml).**

The everyone-can-use-english project is a full-stack English learning platform maintained by ZuodaoTech. It combines a Cloudflare Workers backend for API services with a Vite-powered TypeScript frontend and browser extension. This guide walks you through proven debugging strategies based on the actual source code architecture.

---

## Understanding the Project Architecture

Before debugging, you need to know which component is failing. The repository divides cleanly into three areas:

| Component | Purpose | Key Entry Point |
|-----------|---------|---------------|
| **`entry/`** | Cloudflare Workers backend exposing APIs | [[`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js)](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js) |
| **`enjoy/`** | Vite frontend (web, desktop, extension) | [[`enjoy/vite.main.config.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/vite.main.config.ts)](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/vite.main.config.ts) |
| **`new-edition-drafts/`** | Markdown curriculum content | [`new-edition-drafts/`](https://github.com/ZuodaoTech/everyone-can-use-english/tree/main/new-edition-drafts) |

The **backend** runs inside Cloudflare's `workerd` runtime as plain JavaScript. The **frontend** uses TypeScript, Vite for bundling, and TailwindCSS for styling. Shared utilities live in [`enjoy/src/utils.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/src/utils.ts).

---

## Common Failure Points and Diagnostic Steps

### Cloudflare Worker Runtime Errors

**Symptoms:** 500/502 responses, missing CORS headers, or API timeouts.

**Root cause:** Unhandled exceptions in [`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js) or missing fetch polyfills for the Workers environment.

**How to investigate:**

1. Start the worker locally:
   ```bash
   npx wrangler dev
   ```

2. Watch the terminal for stack traces pointing to [`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js).
3. Stream production logs with:
   ```bash
   npx wrangler tail
   ```

Add defensive error handling in [`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js):

```javascript
addEventListener('fetch', event => {
  event.respondWith(
    handleRequest(event.request).catch(err => {
      console.error('Unhandled error in worker:', err);
      return new Response('Internal Server Error', { status: 500 });
    })
  );
});

```

---

### Frontend Build Failures

**Symptoms:** Vite fails to start, missing modules, or Tailwind styles not applying.

**Root cause:** Mismatched config versions or incorrect `vite.*.config.ts` selection.

**How to investigate:**

1. Run the dev server and read the error trace:
   ```bash
   npm run dev
   ```

2. Verify you're using the correct Vite config:
   - [`vite.main.config.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/vite.main.config.ts) – main UI build
   - [`vite.base.config.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/vite.base.config.ts) – shared base configuration
   - [`vite.renderer.config.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/vite.renderer.config.ts) – markdown rendering
3. Check [`tailwind.config.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/tailwind.config.js) against the Tailwind version in [`package.json`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/package.json).

---

### Environment Variable Issues

**Symptoms:** "Missing API key" or "Invalid token" errors despite having a `.env` file.

**Root cause:** Variables not loaded into the Workers runtime or missing from [`wrangler.toml`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/wrangler.toml).

**How to investigate:**

Verify variables in [`entry/wrangler.toml`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/wrangler.toml):

```toml
[vars]
OPENAI_API_KEY = "your-key-here"

```

Or access secrets via Wrangler:

```bash
npx wrangler secret put OPENAI_API_KEY

```

Add validation in [`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js):

```javascript
const OPENAI_KEY = process.env.OPENAI_API_KEY;
if (!OPENAI_KEY) {
  console.error('OPENAI_API_KEY is missing');
  throw new Error('Missing OPENAI_API_KEY');
}

```

---

### Static Asset Loading Problems

**Symptoms:** Images or videos not appearing in the UI.

**Root cause:** Wrong relative paths or assets not committed to `new-edition-drafts/`.

**How to investigate:**

1. Open browser DevTools → **Network** tab.
2. Confirm the request URL matches an actual file path in the repository.
3. Check that assets live under `new-edition-drafts/` with correct relative references.

---

### Browser Extension Debugging

**Symptoms:** Extension fails to inject scripts on YouTube or Netflix.

**Root cause:** Missing permissions in [`manifest.json`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/manifest.json) or Content Security Policy blocks.

**How to investigate:**

1. Navigate to `chrome://extensions`.
2. Click "Inspect views" on the everyone-can-use-english extension.
3. Look for CSP violations or permission errors in the console.

---

### Markdown Rendering Issues

**Symptoms:** Content displays as raw markdown or sections disappear.

**Root cause:** Misconfigured markdown loader in [`vite.renderer.config.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/vite.renderer.config.ts) or incorrect file paths.

**How to investigate:**

Check the markdown loader options in [[`vite.renderer.config.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/vite.renderer.config.ts)](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/vite.renderer.config.ts) and verify file paths match the `new-edition-drafts/` structure.

---

## Step-by-Step Debugging Workflow

Follow this sequence to isolate and fix issues efficiently:

1. **Reproduce locally**
   ```bash
   npm ci
   npx wrangler dev      # Terminal 1: backend

   npm run dev           # Terminal 2: frontend

   ```

2. **Check all consoles** – terminal output, browser DevTools, and extension inspection views.

3. **Validate configuration files** – [`wrangler.toml`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/wrangler.toml), Vite configs, and Tailwind setup.

4. **Run the test suite**
   ```bash
   npm test
   ```

5. **Add targeted logging** using utilities from [`enjoy/src/utils.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/src/utils.ts):

   ```typescript
   // Example: safer parsing with error context
   export const safeParse = (json: string) => {
     try {
       return JSON.parse(json);
     } catch (e) {
       console.error('safeParse failed', { json, error: e });
       return null;
     }
   };
   ```

6. **Verify external services** – check OpenAI, ElevenLabs, or other API status pages.

7. **Inspect CI/CD** – click the README badges to view GitHub Actions failures.

8. **Consult the FAQ** at [1000h.org/enjoy-app/faq.html](https://1000h.org/enjoy-app/faq.html) for known issues.

---

## Frontend API Debugging with Logging

When frontend calls fail, wrap them for visibility. In [`enjoy/src/utils.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/src/utils.ts):

```typescript
export async function fetchWithLogging(url: string, init?: RequestInit) {
  console.debug('fetchWithLogging →', { url, init });
  const resp = await fetch(url, init);
  if (!resp.ok) {
    console.error('fetch error', {
      url,
      status: resp.status,
      statusText: resp.statusText,
    });
  }
  return resp;
}

```

This surfaces request/response details immediately in browser DevTools.

---

## Key Debugging Files Reference

| File | Role |
|------|------|
| [[`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js)](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js) | Main Worker script – add error boundaries here |
| [[`entry/wrangler.toml`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/wrangler.toml)](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/wrangler.toml) | Environment variables and bindings |
| [[`enjoy/vite.main.config.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/vite.main.config.ts)](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/vite.main.config.ts) | Primary build configuration |
| [[`enjoy/src/utils.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/src/utils.ts)](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/src/utils.ts) | Shared utilities for logging and data handling |
| [[`README.md`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/README.md)](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/README.md) | CI status badges and quick-start instructions |

---

## Summary

- **Start local reproduction** with `npx wrangler dev` and `npm run dev` to catch errors early.
- **Use `wrangler tail`** for production Worker logs and browser DevTools for frontend issues.
- **Validate [`wrangler.toml`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/wrangler.toml)** and Vite configs before chasing code bugs.
- **Add explicit error handling** in [`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js) and logging wrappers in [`enjoy/src/utils.ts`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/enjoy/src/utils.ts).
- **Check external APIs and CI badges** when local debugging doesn't explain the failure.

---

## Frequently Asked Questions

### How do I check if my environment variables are loaded correctly?

Run `npx wrangler dev` and add a console log for `process.env.YOUR_VAR` in [`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js). If undefined, verify the variable exists in [`wrangler.toml`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/wrangler.toml) under `[vars]` or as a Wrangler secret. You can also list secrets with `npx wrangler secret list`.

### Why does the frontend show a blank screen in development?

Most commonly caused by Vite config mismatches or the dev server proxy failing to connect to the Worker. Confirm `npm run dev` shows no errors in the terminal, check that `wrangler dev` is running on the expected port, and verify the proxy configuration in your Vite config files.

### Where do I find logs for the deployed Cloudflare Worker?

Use `npx wrangler tail` to stream live logs from the production environment. For historical logs, check the Cloudflare dashboard under Workers & Pages → your script → Logs. Add structured `console.error()` calls in [`entry/index.js`](https://github.com/ZuodaoTech/everyone-can-use-english/blob/main/entry/index.js) to surface more context.

### The browser extension stopped working—how do I debug it?

Open `chrome://extensions`, find everyone-can-use-english, and click "Inspect views: background page" or "service worker". Check the Console for CSP violations, permission denials, or network failures. Verify the extension has host permissions for sites where injection fails.