Skip to main content
Thanks for your interest in contributing! This guide covers everything you need to know about development setup, testing, and submitting contributions.

​
Development Setup

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18+ or Bun 1.0+ (Bun is recommended for faster builds)
  • Chrome 138+ for testing the extension
  • Git for version control

​
Getting Started

1

Clone the repository

git clone https://github.com/b1ink0/vassist.git
cd vassist
2

Install dependencies

bun install
3

Start development

Choose your development mode:
bun run dev

​
Available Commands

​
Development Commands

bun run dev
# Starts dev server at http://localhost:5173

​
Production Commands

bun run build
# Production build for demo site

​
Utility Commands

bun run lint
# Run ESLint checks

​
Testing Your Changes

​
Manual Testing Checklist

Before submitting a pull request, test in both modes: Demo Mode Testing:
  • bun run dev starts without errors
  • Feature works as expected
  • No console errors
  • Performance is acceptable
  • Hot reload works correctly
Extension Mode Testing:
  • bun run build:extension completes successfully
  • Extension loads in Chrome without errors
  • Feature works on multiple websites (YouTube, Twitter, Gmail, GitHub)
  • No CSS conflicts with host pages
  • Multi-tab behavior is correct (if applicable)
  • Shadow DOM isolation is maintained
Cross-browser Testing:
  • Test in Chrome stable
  • Test in Chrome Canary (for new APIs)
Focus testing on both demo and extension modes since they share 95% of the code. A bug in one mode likely affects both.

​
Debugging

​
Demo Mode Debugging

  1. Open DevTools (F12) and check the Console tab
  2. Use React DevTools for component debugging
  3. Monitor Network tab for API calls
  4. Enable Debug Panel in Settings → UI to see FPS, memory, and animation state

​
Extension Mode Debugging

Content Script:
  • Open DevTools (F12) on the webpage
  • Look for [Content] prefixed logs
Background Service Worker:
  • Right-click extension icon → “Inspect service worker”
  • Look for [Background] prefixed logs
Offscreen Document:
  • Check background console for [Offscreen] logs
  • Used for heavy audio processing and Kokoro TTS
Main World (React App):
  • Open DevTools on the webpage
  • React app runs in main world but renders in Shadow DOM
Each layer has distinct logging prefixes to help you trace message flow through the architecture.

​
Adding Features

​
Adding a New AI Provider

1

Create demo service

Create service class in src/services/ for direct API calls in demo mode.
2

Create background service

Create background service in extension/background/services/ for extension mode.
3

Add proxy

Create proxy in src/services/proxies/ to automatically route between demo and extension modes.
4

Register provider

Add provider configuration to src/config/aiConfig.js.

​
Adding UI Components

Components in src/components/ automatically work in both modes. Just create your component and import it where needed. 
// Components work identically in both modes
import MyComponent from './components/MyComponent';

​
Adding Settings

1

Add default value

Update src/config/uiConfig.js with the new setting’s default value.
2

Create settings panel

Add a settings panel component in src/components/settings/.
3

Use in components

Use the useConfig hook to read and update the setting:
const { config, updateConfig } = useConfig();
const mySetting = config.mySetting;

​
Pull Request Process

1

Fork and create branch

Fork the repository and create a feature branch:
git checkout -b feature/my-new-feature
2

Make your changes

  • Follow existing code style and conventions
  • Keep changes focused on a single feature or fix
  • Add comments for complex logic
3

Test thoroughly

Complete the testing checklist above for both demo and extension modes.
4

Commit with clear messages

git commit -m "Add: New feature description"
git commit -m "Fix: Bug description"
git commit -m "Update: Enhancement description"
5

Push and create PR

git push origin feature/my-new-feature
Then create a pull request on GitHub.
6

Describe your changes

In your PR description, include:
  • What changed and why
  • How you tested it (demo mode, extension mode, specific sites)
  • Screenshots or videos if UI changes are involved
  • Any breaking changes or migration notes

​
Code Style Guidelines

  • Use ES6+ features (async/await, arrow functions, destructuring)
  • Component structure: Functional components with hooks
  • File naming: PascalCase for components, camelCase for utilities
  • Imports: Group by external, internal, relative
  • Logging: Use Logger.log() with appropriate prefixes

​
Resources

​
External Documentation

​
Getting Help

​
What to Contribute

​
Good First Issues

  • Documentation improvements
  • UI/UX enhancements
  • Bug fixes
  • Test coverage
  • Performance optimizations

​
Feature Ideas

  • New AI provider integrations
  • Additional animation types
  • Voice/TTS provider options
  • Accessibility improvements
  • Internationalization (i18n)
Thank you for contributing to VAssist!

Build docs developers (and LLMs) love

Get started for freeTalk to us