A calm, powerful Chrome extension for instant word definitions, AI-powered summaries, and translations — all without leaving the page.
WordLens is a production-ready Chrome extension (Manifest V3) that provides instant dictionary lookups, AI summaries, translations, and text-to-speech directly on any webpage. Features a beautiful liquid glass UI, built-in PDF reader, and personal vocabulary vault.
The project combines:
- Chrome Extension (Vanilla JS) – lightweight, zero-overhead
- Landing Page (React + Vite + Tailwind) – modern marketing site
Both share a unified build pipeline in a single repository.
| Feature | Description |
|---|---|
| Dictionary Lookup | Double-click any word for definitions, IPA phonetics, and examples (Free Dictionary API) |
| AI Summaries | Get plain-English explanations of sentences using Groq's LLaMA 3.3 70B |
| Translation | One-click translation from 12+ languages to English |
| Text-to-Speech | Listen to results with native browser synthesis (offline) |
| Vocabulary Vault | Save and manage words in personal dictionary |
| Drag & Reposition | Freely move the floating popup; position persists |
| PDF Reader | Built-in viewer with full WordLens functionality |
| Dark Mode | System-aware theme with liquid glass UI |
| Pause-to-Peek | Hover 600ms to see underline hint before clicking |
- Manifest V3, Vanilla JavaScript (ES2022)
- Service worker for API proxying & caching
- Glassmorphism CSS design
- React 19, Vite 7, Tailwind CSS 4
- Framer Motion for animations
- react-pdf for PDF rendering
- IndexedDB for client-side storage
- Free Dictionary API (no auth)
- Groq Cloud (user-provided API key)
- Google Translate (
client=gtx)
# 1. Clone
git clone https://github.com/Aryansingh64/WordLens.git
cd WordLens
# 2. Install dependencies
npm install
# 3. Build
npm run build
# 4. Load in Chrome
# → chrome://extensions
# → Enable Developer mode
# → Load unpacked → Select dist/ folderThe extension is now active. Select any text to use WordLens.
Optional: Add Groq API key in extension Settings for AI summaries (free tier at console.groq.com).
npm run dev # Start dev server at http://localhost:5173Edit files in src/ — hot reload applies automatically.
Edit files in extension/ directly, then:
- Go to
chrome://extensions - Click reload icon on WordLens card
- Refresh webpage to test
No build step needed for extension code changes.
WordLens/
├── extension/ # Chrome extension (Vanilla JS)
│ ├── content.js # Content script (UI, events)
│ ├── background.js # Service worker (API, cache)
│ ├── popup.html/js/css # Vault UI
│ └── sidepanel.html/js # Side panel
│
├── src/ # Landing page (React)
│ ├── App.jsx # Main component
│ ├── components/ui/dynamic-hero.jsx
│ ├── pages/options/ # Dashboard
│ ├── pages/pdf-viewer/ # PDF reader
│ └── assets/ # Hero images (WebP)
│
├── public/ # Extension static assets
│ ├── manifest.json
│ └── icons/
│
├── dist/ # Build output (auto-generated)
│ ├── index.html, options.html, pdf-viewer.html
│ ├── extension/, icons/, manifest.json
│ ├── assets/ # Bundled CSS/JS + images
│ └── wordlens-extension-v2.0.0.zip
│
├── build-zip.cjs # ZIP packaging script
├── vite.config.js # Multi-page build config
├── LEARNING_GUIDE.md # Beginner tutorial (1007 lines)
├── DOCUMENTATION.md # Technical deep-dive (973 lines)
└── README.md # You are here
User selects text on webpage
↓
content.js detects → shows floating popup
↓
User clicks action (define/summarize/translate)
↓
chrome.runtime.sendMessage() to background.js
↓
background.js checks cache → fetches API if needed
↓
sendResponse() returns data
↓
content.js renders result in popup
Key insight: Content scripts cannot make cross-origin API calls directly due to CORS. The background service worker acts as a proxy, fetching data and returning it via message passing.
| Want to... | How |
|---|---|
| Change accent color | Edit CSS variables in src/index.css (e.g., --accent: #22c55e;) |
| Add translation language | Add to LANGUAGES array in extension/content.js |
| Adjust cache TTL | Modify CACHE_TTL in extension/background.js (default: 5 min) |
| Change hover delay | Edit IDLE_DELAY in extension/content.js (default: 600ms) |
| Replace hero images | Put WebP in src/assets/, update imports in src/App.jsx |
| Modify popup width | Edit .wl-popup in extension/content.css |
npm run build
git push origin main
# In GitHub repo Settings → Pages → Source: /distSite: https://Aryansingh64.github.io/WordLens/
The download button uses Google Drive. To update:
- Upload
dist/wordlens-extension-v2.0.0.zipto Drive - Get file ID from share link
- Edit
src/App.jsxline 209:const zipUrl = 'https://drive.google.com/uc?export=download&id=YOUR_FILE_ID';
Package is ready in dist/wordlens-extension-v2.0.0.zip (16 MB). Upload at Chrome Developer Dashboard ($5 one-time fee).
- Image optimization: JPG → WebP conversion (46% size reduction, 28.4 MB → 15.3 MB)
- Extension size: 16.4 MB (includes optimized assets)
- Caching: 5-minute TTL in-memory cache for API responses
- Retry logic: Exponential backoff (500ms, 1000ms) on failed requests
- DOCUMENTATION.md – Comprehensive technical deep-dive covering architecture, message passing, API integration, security, and build system (973 lines)
- LEARNING_GUIDE.md – Beginner-friendly tutorial with file-by-file explanations, practical examples, and troubleshooting (1007 lines)
- Fork the repo
- Create a feature branch:
git checkout -b feature/name - Make changes and test:
npm run build - Commit:
git commit -m "feat: description" - Push and open a PR
Note: Keep extension files (extension/) as plain JavaScript (no React). React is only for the landing page (src/).
MIT – see LICENSE for details.
Aryan Pratap Singh 📧 aaryansingh7598@gmail.com 🔗 LinkedIn • GitHub 📱 +91 9919535756
Built with care to make reading a quieter, more understood experience.