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

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.

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)
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)
new-edition-drafts/	Markdown curriculum content	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.

---

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 or missing fetch polyfills for the Workers environment.

How to investigate:

1. Start the worker locally:

   npx wrangler dev

2. Watch the terminal for stack traces pointing to entry/index.js.

3. Stream production logs with:

   npx wrangler tail

Add defensive error handling in entry/index.js:

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:

   npm run dev

2. Verify you're using the correct Vite config:

   • vite.main.config.ts – main UI build
   • vite.base.config.ts – shared base configuration
   • vite.renderer.config.ts – markdown rendering

3. Check tailwind.config.js against the Tailwind version in 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.

How to investigate:

Verify variables in entry/wrangler.toml:

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

Or access secrets via Wrangler:

npx wrangler secret put OPENAI_API_KEY

Add validation in entry/index.js:

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 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 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/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

   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, Vite configs, and Tailwind setup.

4. Run the test suite

   npm test

5. Add targeted logging using utilities from enjoy/src/utils.ts:

   // 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 for known issues.

---

Frontend API Debugging with Logging

When frontend calls fail, wrap them for visibility. In enjoy/src/utils.ts:

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)	Main Worker script – add error boundaries here
[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)	Primary build configuration
[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)	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 and Vite configs before chasing code bugs.
• Add explicit error handling in entry/index.js and logging wrappers in 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. If undefined, verify the variable exists in 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 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.

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