Skip to content

AGENTS.md

Latest commit

 

History

History
151 lines (108 loc) · 8.2 KB

AGENTS.md

File metadata and controls

151 lines (108 loc) · 8.2 KB
Raw

Project Overview

小红 — RedNote Tweakis a cross-browser extension (Chrome, Firefox, Edge) that enhances the Xiaohongshu (小红书) web experience with search improvements and UI cleanup. Features include keyboard shortcuts for search, right-click context menu search, tab placement control, and toggles for hiding feed content, sidebar elements, and notifications — all configurable from the popup. Built with WXT on top of Vite.

Tech Stack

  • Framework: WXT — browser extension framework with Vite under the hood
  • UI (Popup): Vue 3 Composition API + <script setup> + TypeScript
  • Components: shadcn-vue (New York style) + reka-ui + Lucide icons
  • Styling: UnoCSS (Preset Wind 3) + unocss-preset-shadcn
  • State: wxt/storage wrapped in Vue composables (useStoredValue, useFeature, useFeatureMap)
  • i18n: vue-i18n with JSON locale files in assets/locales/ and extension manifest messages in public/_locales/
  • Tooling: Vite+ (vp) — see section below
  • Package Manager: pnpm (via Vite+ vp add / vp install)

Data Flow

Popup (Vue) ──write──> wxt/storage <──watch── Content Script
                           │
                     Feature toggle changes
                     trigger onFeatureChange
                     callbacks that apply/remove
                     DOM mutations

Background (Vue) ──watch──> wxt/storage (contextMenuSearch, useIntlSearch)

Conventions

  • Auto-imports: This project uses unimport (via WXT) to handle auto-imports.

    By default, WXT sets up auto-imports for its own APIs as well as selected project directories, including:

    <srcDir>/components/*
<srcDir>/composables/*
<srcDir>/utils/*

    Vue APIs (ref, computed, watch, etc.) are automatically handled via @wxt-dev/module-vue.

    In addition, shared modules in shared/ are auto-imported via imports.dirs, and components in components/ are auto-registered via unplugin-vue-components.

    As a result, all named and default exports from these locations are available globally across the project without explicit imports in .vue files.

    Do not import them manually. If you encounter type errors, run vp run postinstall (wxt prepare) to regenerate types, or restart the dev server. Only investigate further if the issue persists.

  • Use Standard Components: Prioritize provided components for consistency. As needed, add new ones to components/ui/ via shadcn-vue. You can retrieve shadcn-vue skills from .agents/skills/shadcn-vue or utilize its MCP server.

  • Adding a feature:

    1. Define the feature key and metadata in shared/const.ts under a FEATURE_GROUPS entry
    2. Create an implementation file in entrypoints/rednote.content/impl/
    3. Export it from impl/index.ts
    4. Add it to the featureRegistrations array in entrypoints/rednote.content/features.ts
    5. Add i18n keys to assets/locales/*.json
    6. If the feature needs a popup toggle, add the corresponding UI

  • Utility helpers:

    • utils/index.ts exports cn() — a clsx + tailwind-merge helper for merging CSS classes.
    • State composables are in composables/: useStoredValue (generic wxt/storage wrapper with async init) and useFeature/useFeatureMap (typed feature-flag composables).

  • Commit messages: Use two Conventional Commit sections separated by blank lines: an English subject and description first, followed by a Chinese subject with the same type/scope and its Chinese description. This lets release-please extract both language subjects into the changelog.

Build & Development

vp install          # Install dependencies
vp run dev          # Start WXT dev server (Chromium)
vp run dev:firefox  # Start WXT dev server (Firefox)
vp run build        # Production build
vp run compile      # Type-check with vue-tsc

Use vp check to run format, lint, and type checks together.

vpr is an alias for vp run and can be used to run any script defined in package.json.

Using Vite+, the Unified Toolchain for the Web

This project is using Vite+, a unified toolchain built on top of Vite, Rolldown, Vitest, tsdown, Oxlint, Oxfmt, and Vite Task. Vite+ wraps runtime management, package management, and frontend tooling in a single global CLI called vp. Vite+ is distinct from Vite, but it invokes Vite through vp dev and vp build.

Vite+ Workflow

vp is a global binary that handles the full development lifecycle. Run vp help to print a list of commands and vp <command> --help for information about a specific command.

Start

  • create - Create a new project from a template
  • migrate - Migrate an existing project to Vite+
  • config - Configure hooks and agent integration
  • staged - Run linters on staged files
  • install (i) - Install dependencies
  • env - Manage Node.js versions

Develop

  • dev - Run the development server
  • check - Run format, lint, and TypeScript type checks
  • lint - Lint code
  • fmt - Format code
  • test - Run tests

Execute

  • run - Run monorepo tasks
  • exec - Execute a command from local node_modules/.bin
  • dlx - Execute a package binary without installing it as a dependency
  • cache - Manage the task cache

Build

  • build - Build for production
  • pack - Build libraries
  • preview - Preview production build

Manage Dependencies

Vite+ automatically detects and wraps the underlying package manager such as pnpm, npm, or Yarn through the packageManager field in package.json or package manager-specific lockfiles.

  • add - Add packages to dependencies
  • remove (rm, un, uninstall) - Remove packages from dependencies
  • update (up) - Update packages to latest versions
  • dedupe - Deduplicate dependencies
  • outdated - Check for outdated packages
  • list (ls) - List installed packages
  • why (explain) - Show why a package is installed
  • info (view, show) - View package information from the registry
  • link (ln) / unlink - Manage local package links
  • pm - Forward a command to the package manager

Maintain

  • upgrade - Update vp itself to the latest version

These commands map to their corresponding tools. For example, vp dev --port 3000 runs Vite's dev server and works the same as Vite. vp test runs JavaScript tests through the bundled Vitest. The version of all tools can be checked using vp --version. This is useful when researching documentation, features, and bugs.

Common Pitfalls

  • Using the package manager directly: Do not use pnpm, npm, or Yarn directly. Vite+ can handle all package manager operations.
  • Always use Vite commands to run tools: Don't attempt to run vp vitest or vp oxlint. They do not exist. Use vp test and vp lint instead.
  • Running scripts: Vite+ built-in commands (vp dev, vp build, vp test, etc.) always run the Vite+ built-in tool, not any package.json script of the same name. To run a custom script that shares a name with a built-in command, use vp run <script>. For example, if you have a custom dev script that runs multiple services concurrently, run it with vp run dev, not vp dev (which always starts Vite's dev server).
  • Do not install Vitest, Oxlint, Oxfmt, or tsdown directly: Vite+ wraps these tools. They must not be installed directly. You cannot upgrade these tools by installing their latest versions. Always use Vite+ commands.
  • Use Vite+ wrappers for one-off binaries: Use vp dlx instead of package-manager-specific dlx/npx commands.
  • Import JavaScript modules from vite-plus: Instead of importing from vite or vitest, all modules should be imported from the project's vite-plus dependency. For example, import { defineConfig } from 'vite-plus'; or import { expect, test, vi } from 'vite-plus/test';. You must not install vitest to import test utilities.
  • Type-Aware Linting: There is no need to install oxlint-tsgolint, vp lint --type-aware works out of the box.