Skip to content

AGENTS.md

Latest commit

 

History

History
136 lines (94 loc) · 5.49 KB

AGENTS.md

File metadata and controls

136 lines (94 loc) · 5.49 KB
Raw

AGENTS.md

This file provides guidance for coding agents working with this repository.

Project Overview

Bypass Links is an open-source browser extension (Chrome) that bypasses intermediary links on various websites, avoiding reCaptchas, timers, ads, and pop-ups. It also includes utility features like history monitoring and bookmarks with person tagging.

Package Manager

pnpm - This project uses pnpm for package management and workspace orchestration.

Common Commands

# Install dependencies
pnpm install

# Development
pnpm dev              # Start all dev servers
pnpm run env          # Pull Vercel environment variables to .env

# Building (turbo orchestrates with dependency graph)
pnpm build            # Build all workspaces

# Extension-specific builds
cd apps/extension
pnpm build            # Build Chrome extension to .output/chrome-mv3
pnpm dev              # Chrome dev server with hot reload

# Code Quality
pnpm lint             # Lint all files (oxlint, type-aware) with autofix
pnpm lint:ci          # Lint without autofix (CI)
pnpm format           # Format all files (oxfmt)
pnpm format:check     # Check formatting without writing (oxfmt --check)
pnpm typecheck        # Type check root only
pnpm typecheck:all    # Type check all workspaces

# Testing
pnpm e2e              # Run Playwright E2E tests
pnpm e2e:report       # Open the HTML report; its Speedboard tab ranks tests by duration

Architecture

This is a Turbo + pnpm monorepo with the following structure:

  • apps/extension - Browser extension (WXT, React, Wouter for routing)
  • apps/web - Next.js web interface for downloads and admin
  • packages/shared - Shared React components, types, utilities, and stores (Zustand)
  • packages/ui - Shared UI components using shadcn/ui Base UI + Tailwind CSS
  • packages/configs - Shared TypeScript and build configs
  • packages/trpc - tRPC router with Firebase backend (type-safe API)

Build System

Turbo manages task dependencies defined in turbo.json:

  • build tasks depend on //#lint:ci and //#typecheck completing first

E2E Testing

Playwright projects:

  1. auth-setup (apps/*/tests/auth.setup.ts) - Runs once per test run; caches web storageState and the authenticated extension Chrome profile under .playwright/.cache
  2. @bypass/web-with-auth (apps/web/tests/specs/) - Web specs, authenticated via the project's storageState
  3. @bypass/extension (apps/extension/tests/specs/) - Parallel extension tests, each worker on a copy of the cached Chrome profile

tests/coverage-report.ts is the global teardown: it writes the coverage report (CI only) and removes .playwright/.cache. Shared page-object bases live in packages/shared/src/utils/test-poms.ts.

Key Technologies

  • Frontend: React, Next.js (web)
  • React Compiler: Enabled in both apps (reactCompiler: true in web, reactCompilerPreset() in extension); enforced by the react/react-compiler oxlint rule — avoid manual useMemo/useCallback unless needed
  • UI: shadcn/ui (Base UI) via packages/ui and @bypass/ui
  • Styling: Tailwind CSS v4
  • Icons: Hugeicons (@hugeicons/core-free-icons, @hugeicons/react)
  • Forms: TanStack React Form + zod/mini validation
  • State: Zustand
  • API: tRPC for type-safe client-server communication
  • Backend: Firebase with Admin SDK
  • Testing: Playwright
  • Linting: oxlint (type-aware via oxlint-tsgolint), config in .oxlintrc.json
  • Formatting: oxfmt, config in .oxfmtrc.json
  • Tailwind linting: oxlint-tailwindcss (native oxlint plugin)

Code Patterns

  • Use workspace protocol (workspace:*) for internal dependencies
  • Shared types and utilities go in packages/shared
  • tRPC procedures are defined in packages/trpc
  • CRITICAL — Minimize comments. This is non-negotiable. Do NOT add comments by default. Add a comment ONLY when it is absolutely necessary AND conveys meaningful information that the code itself cannot express. When a comment is truly justified, keep it concise and short — explain the reasoning (the "why"), never what the code does. Elaborate ONLY for edge cases or genuinely tricky, hard-to-follow logic. If in doubt, leave the comment out.

shadcn/ui Components

shadcn/ui components are managed in the packages/ui workspace. This project uses the Base UI version of shadcn, not the Radix UI primitives.

For the latest shadcn documentation and component reference, see: https://ui.shadcn.com/llms.txt

# Add a new shadcn component
cd packages/ui
pnpm dlx shadcn@latest add [component-name]

# Example: add button component
pnpm dlx shadcn@latest add button

All new UI components should be added to packages/ui and exported from packages/ui/src/index.ts for use across apps.

IMPORTANT: Never modify files inside packages/ui unless explicitly asked. The UI package contains shadcn/ui components that should remain unchanged unless adding new components or making approved modifications.

IMPORTANT: Development Guidelines

  • Ask any questions instead of assuming things when in plan mode
  • Never automatically commit or push changes unless explicitly asked

Specialized Skills

  • Domain-specific agent skills live in .agents/skills/

Post-Change Verification

Always after making changes, run the following commands:

pnpm lint
pnpm format:check
pnpm typecheck:all

Optionally, run E2E tests only when the user explicitly asks, or when the changes affect behavior covered by E2E tests:

pnpm e2e <relative-filepath>