An intelligent Chrome extension powered by Chrome's built-in AI (Gemini Nano) that generates step-by-step website guidance tailored for different user categories.
- Overview
- Features
- Tech Stack
- Prerequisites
- Installation
- Usage
- Project Structure
- Development
- Build & Deploy
- Components
- Configuration
- Troubleshooting
- Contributing
- License
Website Guide Assistant is a cutting-edge Chrome extension that leverages Chrome's experimental built-in AI (Gemini Nano) to provide intelligent, context-aware website guidance. It analyzes the current webpage and generates customized guides based on user preferences.
- 🎯 Personalized Learning: Three user categories (Kids, Intermediate, Beginners) with tailored content
- 🤖 AI-Powered: Uses Chrome's built-in Gemini Nano AI for on-device processing
- ⚡ Fast & Private: No external API calls - everything runs locally
- 🎨 Beautiful UI: Modern, dark mode-enabled interface with shadcn/ui components
- 📥 Export Options: Download guides as PNG images or copy formatted text
- 🔄 Customizable: Select 5-10 steps for step-by-step guides
✅ Multiple User Modes
- 👶 Kids Mode: Simple, fun explanations with emoji indicators
- ⚡ Intermediate Mode: Efficient guidance with productivity tips and shortcuts
- 🎓 Beginners Mode: Detailed explanations for first-time users
✅ Two Guide Types
- Quick Summary: Brief overview of website features and purpose
- Step-by-Step Guide: Detailed walkthrough with visual flowcharts (5-10 customizable steps)
✅ Smart Content Generation
- Analyzes webpage HTML structure, meta tags, and visible content
- Category-specific prompts optimized for different user levels
- Structured JSON output with proper formatting
✅ Modern UI Features
- 🌓 Dark Mode: Seamless light/dark theme switching with localStorage persistence
- 📱 Responsive Design: Works perfectly in popup and side panel views
- 🎨 Beautiful Components: Powered by shadcn/ui with Radix UI primitives
- ⚙️ Step Count Selector: Choose between 5-10 steps for guides
✅ Export & Share
- 📋 Copy Text: Copy formatted text with smart structure detection
- 🎯 Theme-Aware: Exports respect current theme (light/dark backgrounds)
✅ AI Integration
- Uses Chrome's experimental
chrome.aiOriginTrialAPI - Real-time AI status detection and user-friendly error messages
- Graceful fallbacks when AI is unavailable
- React 19 - Latest React with concurrent features
- TypeScript 5 - Strict mode with verbatimModuleSyntax for type safety
- Vite 6 - Lightning-fast build tool with HMR
- Tailwind CSS v4 - Latest utility-first CSS with @tailwindcss/vite plugin
- shadcn/ui - Accessible component library built on Radix UI
- Radix UI - Unstyled, accessible UI primitives
- Lucide React - Beautiful icon library
- class-variance-authority - CVA for component variants
- tailwind-merge - Intelligent Tailwind class merging
- CRXJS Vite Plugin v2 - Modern Chrome extension development with HMR
- Manifest V3 - Latest Chrome extension manifest
- Chrome AI API - Built-in Gemini Nano integration
- html2canvas - HTML to PNG conversion for exports
- react-markdown - Markdown rendering with GFM support
- react-syntax-highlighter - Code syntax highlighting
- remark-gfm - GitHub Flavored Markdown support
Before installing, ensure you have:
- Node.js v18 or higher (Download)
- npm v9 or higher (comes with Node.js)
- Google Chrome v127+ with AI features enabled
The extension requires Chrome's built-in AI (Gemini Nano). Follow these steps:
-
Update Chrome to Canary/Dev
- Download Chrome Canary or Chrome Dev
- Version must be 127 or higher
-
Enable AI Features
- Navigate to
chrome://flags/#optimization-guide-on-device-model - Set to Enabled BypassPerfRequirement
- Navigate to
chrome://flags/#prompt-api-for-gemini-nano - Set to Enabled
- Navigate to
-
Download AI Model
- Restart Chrome
- Open DevTools (F12) on any page
- Type:
await ai.languageModel.create() - Wait for model download (may take a few minutes)
-
Verify Installation
- After restart, run:
(await ai.languageModel.capabilities()).available - Should return
"readily"if successful
- After restart, run:
All dependencies are pre-installed! Just follow these steps:
git clone https://github.com/raviycoder/website_guide.git
cd website_guidenpm installThe project includes an SVG icon at public/icons/icon.svg. Generate PNG versions:
npm run generate-iconsThis creates all required icon sizes (16x16, 32x32, 48x48, 128x128).
Alternative: Manual Icon Creation
If the script doesn't work, create icons manually:
- Visit Convertio
- Upload
public/icons/icon.svg - Convert and download in sizes: 16x16, 32x32, 48x48, 128x128
- Save them in
public/icons/folder
Or use ImageMagick:
cd public/icons
magick convert icon.svg -resize 16x16 icon16.png
magick convert icon.svg -resize 32x32 icon32.png
magick convert icon.svg -resize 48x48 icon48.png
magick convert icon.svg -resize 128x128 icon128.pngnpm run devThis starts Vite with CRXJS plugin. The extension will be built in the dist/ folder.
- Open Chrome and navigate to
chrome://extensions/ - Enable Developer mode (toggle in top-right corner)
- Click Load unpacked
- Select the
distfolder from your project directory - The extension icon should appear in your Chrome toolbar
- Click the puzzle icon (Extensions) in Chrome toolbar
- Find "Website Guide Assistant"
- Click the pin icon to keep it visible
For production deployment:
npm run buildThis creates an optimized production build in dist/ folder. Load this folder in Chrome using the same steps above.
-
Navigate to Any Website
- Open any website you want to learn about (e.g., amazon.com, youtube.com)
-
Open the Extension
- Click the Website Guide Assistant icon in your Chrome toolbar
- Or use keyboard shortcut (if configured)
-
Check AI Status
- Look at the top status indicator:
- ✅ Green: AI is ready
⚠️ Yellow/Red: Follow setup instructions
- Look at the top status indicator:
-
Select Your Profile
- Choose from dropdown:
- 👶 Kids: Simple, fun explanations
- ⚡ Intermediate: Efficient, productivity-focused
- 🎓 Beginners: Detailed, patient guidance
- Choose from dropdown:
-
Choose Guide Type
- Summary Tab: Quick overview of the website
- Steps Guide Tab: Detailed step-by-step instructions
- For Steps Guide, select number of steps (5-10) using the dropdown
-
Generate Guide
- Click "Start Guide" button
- Wait for AI to analyze the page (2-5 seconds)
- View your personalized guide!
Once a guide is generated:
Download as PNG
- Click the "Download PNG" button
- Guide is saved as high-quality image (2x resolution)
- Filename format:
websitename-guide-YYYY-MM-DD.png - Theme-aware: Captures current light/dark mode
Copy as Text
- Click the "Copy Text" button
- Smart formatting for structured guides
- Paste anywhere: Notion, Docs, Slack, etc.
- Click the sun/moon icon in top-right
- Switches between light and dark mode
- Preference saved to localStorage
- All components support dark mode
- Only available in "Steps Guide" tab
- Select 5-10 steps using dropdown
- Overrides category default step count
- AI generates exactly the requested number of steps
- Brief overview of website purpose
- Key features and functionality
- Main navigation areas
- Best for: Quick understanding, first impressions
- Detailed walkthrough with numbered steps
- Visual flowchart renderer
- Each step includes:
- Action to take
- Expected result
- Tips and warnings
- Next suggested actions
- Best for: Learning workflows, complex tasks
guide_ai/
├── public/
│ └── icons/ # Extension icons (generated)
│ ├── icon.svg # Source SVG icon
│ ├── icon16.png # 16x16 favicon
│ ├── icon32.png # 32x32 toolbar
│ ├── icon48.png # 48x48 extension management
│ └── icon128.png # 128x128 Chrome Web Store
│
├── src/
│ ├── components/
│ │ ├── ui/ # shadcn/ui base components
│ │ │ ├── button.tsx
│ │ │ ├── card.tsx
│ │ │ ├── input.tsx
│ │ │ ├── label.tsx
│ │ │ ├── scroll-area.tsx
│ │ │ ├── select.tsx
│ │ │ ├── tabs.tsx
│ │ │ └── tooltip.tsx
│ │ │
│ │ ├── ai-status-indicator.tsx # AI availability status
│ │ ├── category-description.tsx # Category info display
│ │ ├── category-selector.tsx # User category dropdown
│ │ ├── content-type.tsx # Summary/Steps tabs
│ │ ├── error-state.tsx # Error UI component
│ │ ├── feature-info.tsx # Feature information
│ │ ├── guide-display.tsx # Main guide renderer
│ │ ├── instructions.tsx # Setup instructions
│ │ ├── loading-state.tsx # Loading spinner
│ │ ├── markdown-renderer.tsx # Markdown display
│ │ ├── start-guide-button.tsx # Generate guide button
│ │ ├── step-count-selector.tsx # 5-10 steps selector
│ │ ├── steps-renderer.tsx # Flowchart renderer
│ │ ├── summary-content.tsx # Summary display
│ │ ├── theme-switcher.tsx # Light/dark toggle
│ │ └── website-header.tsx # Extension header
│ │
│ ├── content/
│ │ └── content-script.ts # Content script for page analysis
│ │
│ ├── hooks/
│ │ ├── use-guide-generator.ts # AI guide generation logic
│ │ └── use-website-data.ts # Webpage data extraction
│ │
│ ├── lib/
│ │ └── utils.ts # Utility functions (cn helper)
│ │
│ ├── prompts/
│ │ ├── config.ts # Category configs & instructions
│ │ ├── constants.ts # UI messages per category
│ │ ├── step-guide-prompts.ts # Step guide prompt templates
│ │ └── summary-prompts.ts # Summary prompt templates
│ │
│ ├── types/
│ │ ├── ai.types.ts # AI API type definitions
│ │ ├── guide.types.ts # Guide data structures
│ │ └── website.types.ts # Website data types
│ │
│ ├── App.tsx # Main popup component
│ ├── main.tsx # React entry point
│ └── index.css # Global styles + Tailwind
│
├── scripts/
│ └── generate-icons.mjs # Icon generation script
│
├── manifest.json # Chrome extension manifest (V3)
├── vite.config.ts # Vite + CRXJS configuration
├── tsconfig.json # TypeScript configuration
├── components.json # shadcn/ui configuration
├── package.json # Dependencies and scripts
└── README.md # This file
CRXJS provides seamless hot module replacement:
-
Start Dev Server
npm run dev
-
Load Extension Once
- Load
distfolder in Chrome as described above - Extension automatically reloads on code changes!
- Load
-
Make Changes
- Edit any
.tsx,.ts, or.cssfile - Save the file
- Extension reloads automatically in Chrome
- No manual refresh needed!
- Edit any
npx shadcn@latest add [component-name]Examples:
npx shadcn@latest add dialog
npx shadcn@latest add toast
npx shadcn@latest add dropdown-menu
npx shadcn@latest add badgePopup Debugging
- Right-click extension icon → "Inspect popup"
- Opens DevTools for the popup
- View console logs, network requests, etc.
Content Script Debugging
- Open DevTools on any webpage (F12)
- Content script logs appear in main console
- Check "Sources" tab for breakpoints
Background Script Debugging
- Go to
chrome://extensions/ - Click "Inspect views: service worker"
- View background script logs
npm run buildRuns tsc -b to type-check before building.
npm run lintRuns ESLint with React hooks and React Refresh plugins.
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import { crx } from '@crxjs/vite-plugin'
import tailwindcss from '@tailwindcss/vite'
import manifest from './manifest.json'
import path from 'path'
export default defineConfig({
plugins: [
react(),
tailwindcss(),
crx({ manifest })
],
resolve: {
alias: {
'@': path.resolve(__dirname, './src')
}
}
})- Strict mode enabled
verbatimModuleSyntaxfor explicit imports- Path alias:
@/*→./src/* - JSX: React 18+ automatic runtime
{
"style": "new-york",
"rsc": false,
"tsx": true,
"tailwind": {
"config": "",
"css": "src/index.css",
"baseColor": "zinc",
"cssVariables": true
},
"aliases": {
"components": "@/components",
"utils": "@/lib/utils"
}
}npm run buildThis command:
- Runs TypeScript compiler (
tsc -b) for type checking - Builds optimized production bundle with Vite
- Generates minified assets in
dist/folder - Creates source maps for debugging
dist/
├── assets/ # Minified JS and CSS
├── icons/ # Extension icons
├── index.html # Popup HTML
├── manifest.json # Chrome manifest
└── src/
└── content/
└── content-script.js
-
Prepare Assets
- Create promotional images (440x280, 920x680, 1400x560)
- Write compelling description
- Prepare screenshots
-
Zip the Extension
cd dist zip -r ../guide_ai.zip .
-
Upload to Chrome Web Store
- Go to Chrome Developer Dashboard
- Create new item ($5 one-time fee)
- Upload
guide_ai.zip - Fill in store listing details
- Submit for review
npm run previewOr manually:
- Run
npm run build - Load
distfolder in Chrome - Test all features in production mode
Main application component managing state:
- AI session initialization
- Category and content type selection
- Step count management
- Guide generation orchestration
- Theme persistence
Custom hook handling AI interactions:
interface UseGuideGeneratorProps {
session: AISession | null
aiPromptData: string | null
stepCount?: number
}
// Returns:
{
guide: string | null // Raw AI response
structuredGuide: Guide | null // Parsed structured data
generating: boolean // Loading state
generateGuide: (contentType, category) => Promise<void>
resetGuide: () => void
}Extracts webpage information:
- Page title and meta description
- Main headings (h1, h2)
- Navigation links
- Visible text content
- Sends to content script via Chrome messaging
Toggles light/dark mode:
- Uses localStorage for persistence
- Applies
.darkclass to<html> - Sun/Moon icon indicator
Visual flowchart for step guides:
- Renders structured step data
- Vertical flowchart with arrows
- Shows actions, results, tips, warnings
- Dark mode support with proper colors
Main guide display with export:
- Renders summary or structured steps
- Download PNG button (html2canvas)
- Copy text button (smart formatting)
- Category-specific icons
Dropdown for step customization:
- Only visible in Steps Guide tab
- Options: 5, 6, 7, 8, 9, 10
- Updates AI prompt dynamically
interface CategoryConfig {
maxSteps: number
tone: string
focusAreas: string[]
}
const CATEGORY_CONFIG = {
kids: {
maxSteps: 5,
tone: "simple, fun, and encouraging",
focusAreas: ["Visual elements", "Simple clicks", "Safety"]
},
intermediate: {
maxSteps: 7,
tone: "balanced, efficient, and practical",
focusAreas: ["Shortcuts", "Productivity", "Pro tips"]
},
beginners: {
maxSteps: 6,
tone: "clear, patient, and detailed",
focusAreas: ["Step-by-step", "Explanations", "Common mistakes"]
}
}Summary Prompts: Brief overview with key features Step Guide Prompts: Detailed JSON structure with:
- Website name and summary
- Array of steps (action, result, tips, warnings)
- Suggested next actions
No environment variables needed! Everything runs locally with Chrome AI.
Defined in manifest.json:
{
"permissions": [
"activeTab", // Access current tab
"scripting", // Inject content scripts
"storage" // Save user preferences
],
"host_permissions": [
"<all_urls>" // Work on all websites
]
}The extension stores:
category: Selected user category (kids/intermediate/beginners)theme: Current theme (light/dark)
Access via:
// Save
await chrome.storage.local.set({ category: 'intermediate' })
// Load
const { category } = await chrome.storage.local.get('category')To add/modify categories, edit:
- src/prompts/config.ts: Add category config
- src/prompts/constants.ts: Add UI messages
- src/types/guide.types.ts: Update
UserCategorytype - src/components/category-selector.tsx: Add select option
Symptoms: Red status indicator, error message
Solutions:
- Verify Chrome version (127+)
- Check
chrome://flagssettings:#optimization-guide-on-device-model→ Enabled BypassPerfRequirement#prompt-api-for-gemini-nano→ Enabled
- Restart Chrome after changing flags
- Download AI model:
// In DevTools console: await ai.languageModel.create()
- Wait 5-10 minutes for download
- Verify:
(await ai.languageModel.capabilities()).availablereturns"readily"
Symptoms: Extension not appearing, load errors
Solutions:
- Ensure
npm run devis running - Check
distfolder exists - Enable Developer mode in
chrome://extensions/ - Look for error messages in Extensions page
- Check console for icon file errors
Symptoms: Generic puzzle piece icon, manifest errors
Solutions:
- Run
npm run generate-icons - Verify icon files exist in
public/icons/:- icon16.png, icon32.png, icon48.png, icon128.png
- Rebuild extension:
npm run dev - Reload extension in Chrome
Symptoms: Changes not reflecting, manual reload needed
Solutions:
- Restart dev server:
Ctrl+Cthennpm run dev - Hard reload extension:
- Go to
chrome://extensions/ - Click reload icon on extension card
- Go to
- Clear browser cache:
Ctrl+Shift+Delete - Check terminal for Vite errors
Symptoms: "Failed to download image" error, oklch color error
Solutions:
- Issue is fixed in v1.0.0 with hex color conversion
- Ensure html2canvas is installed:
npm install html2canvas - Check browser console for detailed errors
- Try in incognito mode to rule out other extensions
Symptoms: "Unable to analyze page" error
Solutions:
- Check
manifest.jsonhas content_scripts defined - Reload extension after code changes
- Navigate to new page (content scripts run on page load)
- Check
chrome://extensions/for errors - Verify file path in manifest matches actual file
Symptoms: Red underlines, build failures
Solutions:
- Run
npm installto ensure all types are installed - Check
tsconfig.jsonhas correct paths - Restart VS Code TypeScript server:
Cmd+Shift+P→ "TypeScript: Restart TS Server" - Clear cache: Delete
node_modulesandpackage-lock.json, thennpm install
Enable detailed logging:
// In use-guide-generator.ts
const DEBUG = true
if (DEBUG) {
console.log('AI Response:', result)
console.log('Parsed Guide:', structuredGuide)
}- GitHub Issues: Report bugs
- Discussions: Ask questions
- Chrome AI Docs: Chrome for Developers
- GitHub Issues: Report bugs
- Discussions: Ask questions
- Chrome AI Docs: Chrome for Developers
| Script | Command | Description |
|---|---|---|
| Development | npm run dev |
Start Vite dev server with HMR and CRXJS |
| Build | npm run build |
Type-check with TSC and build production bundle |
| Preview | npm run preview |
Preview production build locally |
| Lint | npm run lint |
Run ESLint with React hooks rules |
| Generate Icons | npm run generate-icons |
Create PNG icons from SVG source |
// Store user preferences
chrome.storage.local.set({ category: 'intermediate', theme: 'dark' })
// Retrieve preferences
const { category, theme } = await chrome.storage.local.get(['category', 'theme'])Used for: Saving user category, theme preference, guide history
// Get current active tab
const [tab] = await chrome.tabs.query({ active: true, currentWindow: true })
// Send message to content script
chrome.tabs.sendMessage(tab.id, { action: 'analyzeWebsite' })Used for: Identifying current webpage, communicating with content scripts
// Inject content script dynamically
await chrome.scripting.executeScript({
target: { tabId: tab.id },
files: ['content-script.js']
})Used for: Runtime content script injection (if needed)
// Create AI session
const session = await ai.languageModel.create()
// Generate guide
const result = await session.prompt(promptText)
// Check capabilities
const capabilities = await ai.languageModel.capabilities()Used for: On-device AI guide generation with Gemini Nano
- Element highlighting on webpage
- Interactive tutorials with click-through
- Guide history and bookmarks
- Multiple language support
- Voice narration option
- Video tutorial integration
- Progress tracking and analytics
- Keyboard shortcuts customization
- Export to PDF format
- Chrome Web Store publication
- Collaborative guides (share with friends)
- Community-contributed guides
- Screen recording integration
- Mobile companion app
- Browser sync across devices
We welcome contributions! Here's how to get started:
-
Fork the Repository
# Click "Fork" on GitHub, then: git clone https://github.com/YOUR_USERNAME/website_guide.git cd website_guide git remote add upstream https://github.com/raviycoder/website_guide.git
-
Create a Branch
git checkout -b feature/your-feature-name
-
Make Changes
- Follow existing code style
- Add comments for complex logic
- Update TypeScript types as needed
-
Test Thoroughly
- Test in light and dark modes
- Test all three user categories
- Test on multiple websites
- Check for console errors
-
Commit with Conventional Commits
git commit -m "feat: add voice narration option" git commit -m "fix: resolve PNG download issue" git commit -m "docs: update installation instructions"
-
Push and Create PR
git push origin feature/your-feature-name
Then create a Pull Request on GitHub
- Use TypeScript strict mode
- Follow existing naming conventions
- Use functional components with hooks
- Add prop types and interfaces
- Comment complex algorithms
- Keep components small and focused
- Use composition over inheritance
- Extract reusable logic to hooks
- Support dark mode in all new components
- Follow shadcn/ui patterns
<type>(<scope>): <subject>
<body>
<footer>
Types: feat, fix, docs, style, refactor, test, chore
Examples:
feat(export): add PDF export optionfix(ai): handle AI timeout gracefullydocs(readme): update troubleshooting sectionstyle(theme): improve dark mode contrast
- 🎨 UI/UX Design: Improve visual design, animations
- 📝 Documentation: Tutorials, video guides, translations
- 🧪 Testing: Write tests, report bugs, edge case testing
- 🌍 Localization: Translate to other languages
- 💡 Features: Implement roadmap features
- 🐛 Bug Fixes: Resolve GitHub issues
- Chrome AI Team - For building Gemini Nano and prompt API
- shadcn - For the amazing UI component library
- Radix UI - For accessible primitives
- Vite Team - For lightning-fast build tooling
- CRXJS Team - For seamless Chrome extension development
- Tailwind Labs - For Tailwind CSS v4
- Lucide - For beautiful open-source icons
- Author: Ravi Yadav
- GitHub: @raviycoder
- Repository: website_guide
- Issues: Bug Reports
- Discussions: Q&A Forum
If you find this project helpful, please consider:
- ⭐ Starring the repository on GitHub
- 🐛 Reporting bugs you encounter
- 💡 Suggesting features you'd like to see
- 🤝 Contributing code or documentation
- 📢 Sharing with others who might find it useful
Made with ❤️ by Ravi Yadav
Built with React • TypeScript • Chrome AI • Tailwind CSS
Happy coding! 🚀
Last updated: October 26, 2025