{"id":50408042,"url":"https://github.com/pace11/blamescope","last_synced_at":"2026-05-31T02:30:21.717Z","repository":{"id":359940028,"uuid":"1247792958","full_name":"pace11/blamescope","owner":"pace11","description":"Component-level git blame overlay for React + Vite projects","archived":false,"fork":false,"pushed_at":"2026-05-24T07:13:44.000Z","size":16618,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-24T09:16:32.403Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@pace11/blamescope","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pace11.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T19:38:27.000Z","updated_at":"2026-05-24T07:13:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pace11/blamescope","commit_stats":null,"previous_names":["pace11/blamescope"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/pace11/blamescope","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pace11%2Fblamescope","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pace11%2Fblamescope/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pace11%2Fblamescope/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pace11%2Fblamescope/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pace11","download_url":"https://codeload.github.com/pace11/blamescope/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pace11%2Fblamescope/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33717415,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-05-31T02:30:19.106Z","updated_at":"2026-05-31T02:30:21.711Z","avatar_url":"https://github.com/pace11.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 👉 Blamescope\n\n\u003cdiv align=\"center\"\u003e\n\u003cimg src=\"./public//blamescop.png\" alt=\"app-icon\" style=\"text-align:center\" /\u003e\n\u003c/div\u003e\n\nComponent-level git blame overlay for React projects (Vite \u0026 Next.js).\n\nEver stared at a broken component and thought *\"who wrote this??\"* — only to realize it was you, three weeks ago? Blamescope has your back (and your receipts). Hover over any React component during development to instantly see who last touched it, when, and what the commit message said — all without leaving your browser. Use it for context, not for pointing fingers. 🙂\n\n[![npm version](https://img.shields.io/npm/v/%40pace11%2Fblamescope.svg?style=flat-square)](https://www.npmjs.com/package/@pace11/blamescope)\n[![Build status](https://github.com/pace11/blamescope/actions/workflows/publish.yml/badge.svg)](https://github.com/pace11/blamescope/actions/workflows/publish.yml)\n[![npm downloads](https://img.shields.io/npm/dm/%40pace11%2Fblamescope.svg?style=flat-square)](https://npm-stat.com/charts.html?package=%40pace11%2Fblamescope)\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"./public/blamescope.gif\" alt=\"Blamescope demo\" width=\"700\" /\u003e\n\u003c/div\u003e\n\n## How it works\n\n1. **Vite plugin** — auto-injects a `data-blamescope` attribute onto the root JSX element of every React component at build time (dev only).\n2. **Local server** — a small Express server on port `4317` queries `git log` for a given file and returns blame metadata.\n3. **`\u003cBlameOverlay /\u003e`** — a React component that listens to `mousemove`, finds the nearest `data-blamescope` element, calls the local server, and renders a tooltip with author, date, commit message, contributor list, and a clickable commit hash that links to the remote commit.\n\n## Installation\n\n```bash\n# npm\nnpm install -D @pace11/blamescope\n\n# pnpm\npnpm install -D @pace11/blamescope\n\n# yarn\nyarn add -D @pace11/blamescope\n```\n\n\u003e **Peer requirements:** React ≥ 18. Vite ≥ 5 **or** Next.js ≥ 13. Your project must be a git repository.\n\n## Setup\n\nChoose the setup guide for your framework:\n\n- [Vite + React](#vite--react)\n- [Next.js (App Router)](#nextjs-app-router)\n- [Next.js (Pages Router)](#nextjs-pages-router)\n\n---\n\n## Vite + React\n\n### 1. Add the Vite plugin\n\nIn `vite.config.ts`, add `blameScopePlugin()` **before** the React plugin:\n\n```ts\n// vite.config.ts\nimport { defineConfig } from 'vite'\nimport react from '@vitejs/plugin-react'\nimport { blameScopePlugin } from '@pace11/blamescope/plugin'\n\nexport default defineConfig({\n  plugins: [blameScopePlugin(), react()],\n})\n```\n\n### 2. Mount `\u003cBlameOverlay /\u003e`\n\nRender `\u003cBlameOverlay /\u003e` once near the root of your app (e.g. in `App.tsx`):\n\n```tsx\nimport { BlameOverlay } from '@pace11/blamescope'\n\nexport default function App() {\n  return (\n    \u003c\u003e\n      {/* your app ... */}\n      {import.meta.env.DEV \u0026\u0026 \u003cBlameOverlay /\u003e}\n    \u003c/\u003e\n  )\n}\n```\n\nWrapping it in `import.meta.env.DEV` ensures it is never shipped to production.\n\n### 3. Start the blame server\n\nRun the blamescope server alongside your Vite dev server:\n\n```bash\n# in one terminal\nnpx blamescope\n\n# in another terminal\nvite\n```\n\nOr add both to a single npm script:\n\n```json\n\"scripts\": {\n  \"dev\": \"blamescope \u0026 vite\"\n}\n```\n\n---\n\n## Next.js (App Router)\n\n### 1. Wrap your Next.js config\n\n```ts\n// next.config.ts\nimport type { NextConfig } from 'next'\nimport { withBlamescope } from '@pace11/blamescope/next'\n\nconst nextConfig: NextConfig = { /* your existing config */ }\n\nexport default withBlamescope(nextConfig)\n```\n\nCJS (`next.config.js`) works too:\n\n```js\n// next.config.js\nconst { withBlamescope } = require('@pace11/blamescope/next')\n\nmodule.exports = withBlamescope({ /* your existing config */ })\n```\n\n### 2. Mount `\u003cBlameOverlay /\u003e` in your root layout\n\nBecause `BlameOverlay` uses browser APIs, create a thin client wrapper and render it from your root layout:\n\n```tsx\n// app/BlameOverlayClient.tsx\n'use client'\nimport { BlameOverlay } from '@pace11/blamescope'\nexport default BlameOverlay\n```\n\n```tsx\n// app/layout.tsx\nimport BlameOverlayClient from './BlameOverlayClient'\n\nexport default function RootLayout({ children }: { children: React.ReactNode }) {\n  return (\n    \u003chtml lang=\"en\"\u003e\n      \u003cbody\u003e\n        {children}\n        {process.env.NODE_ENV === 'development' \u0026\u0026 \u003cBlameOverlayClient /\u003e}\n      \u003c/body\u003e\n    \u003c/html\u003e\n  )\n}\n```\n\n### 3. Start the blame server\n\n```bash\n# in one terminal\nnpx blamescope\n\n# in another terminal\nnext dev\n```\n\nOr in a single npm script:\n\n```json\n\"scripts\": {\n  \"dev\": \"blamescope \u0026 next dev\"\n}\n```\n\n---\n\n## Next.js (Pages Router)\n\n### 1. Wrap your Next.js config\n\nSame as App Router — use `withBlamescope` in `next.config.ts/js` (see above).\n\n### 2. Mount `\u003cBlameOverlay /\u003e` in `_app.tsx`\n\n```tsx\n// pages/_app.tsx\nimport type { AppProps } from 'next/app'\nimport { BlameOverlay } from '@pace11/blamescope'\n\nexport default function App({ Component, pageProps }: AppProps) {\n  return (\n    \u003c\u003e\n      \u003cComponent {...pageProps} /\u003e\n      {process.env.NODE_ENV === 'development' \u0026\u0026 \u003cBlameOverlay /\u003e}\n    \u003c/\u003e\n  )\n}\n```\n\n### 3. Start the blame server\n\n```bash\nnpx blamescope \u0026 next dev\n```\n\n---\n\n## Usage\n\n- **Hover** over any component in the browser — a tooltip appears with:\n  - Latest commit message, author, and relative date\n  - Commit hash (clickable — opens the commit on GitHub/GitLab/Bitbucket in a new tab)\n  - Total commits and contributor breakdown\n- **Hold `Alt`** to pin the tooltip so you can select and copy text.\n- **Press `Escape`** to unpin.\n- A **status banner** is always visible at the bottom center of the window indicating blamescope is active.\n\n## Manual annotation with `withBlame`\n\nThe Vite plugin auto-detects named function components. For components it cannot reach (anonymous functions, `React.forwardRef`, etc.), use the `withBlame` HOC:\n\n```tsx\nimport { withBlame } from '@pace11/blamescope'\n\nconst Button = withBlame(\n  React.forwardRef\u003cHTMLButtonElement, ButtonProps\u003e((props, ref) =\u003e (\n    \u003cbutton ref={ref} {...props} /\u003e\n  )),\n  { file: 'src/components/Button.tsx', component: 'Button' }\n)\n```\n\n## API\n\n### `blameScopePlugin(root?: string)`\n\nVite plugin. Accepts an optional `root` path (defaults to `process.cwd()`). Must be placed **before** the React plugin in the `plugins` array.\n\n### `withBlamescope(nextConfig?)`\n\nNext.js config wrapper. Adds a webpack loader that injects `data-blamescope` during `next dev`. Supports both App Router and Pages Router. Import from `@pace11/blamescope/next`.\n\n### `\u003cBlameOverlay /\u003e`\n\nReact component. Renders the status banner and hover tooltip. Mount once per app.\n\n| Prop | Type | Default | Description |\n|---|---|---|---|\n| `theme` | `ThemeName \\| BlameTheme` | `\"default\"` | Preset theme name or a custom theme object |\n\n#### Preset themes\n\n| Name | Inspired by |\n|---|---|\n| `\"default\"` | Dark blue-grey |\n| `\"github\"` | GitHub dark |\n| `\"gitlab\"` | GitLab dark |\n| `\"bitbucket\"` | Bitbucket dark |\n| `\"aws\"` | AWS Console dark |\n| `\"google\"` | Google Material dark |\n\n```tsx\n// use a preset\n\u003cBlameOverlay theme=\"github\" /\u003e\n\n// or define a fully custom theme\nimport type { BlameTheme } from '@pace11/blamescope'\n\nconst myTheme: BlameTheme = {\n  background: '#1a1a1a',\n  backgroundSecondary: '#2a2a2a',\n  border: '#333',\n  borderPinned: '#ff6b6b',\n  text: '#fff',\n  textMuted: '#aaa',\n  textFaint: '#666',\n  accent: '#ff6b6b',\n  pinActive: '#ff6b6b',\n}\n\n\u003cBlameOverlay theme={myTheme} /\u003e\n```\n\n### `withBlame(Component, meta)`\n\nHigher-order component for manual annotation.\n\n| Param | Type | Description |\n|---|---|---|\n| `Component` | `ComponentType\u003cP\u003e` | The component to wrap |\n| `meta.file` | `string` | Relative path to the source file |\n| `meta.component` | `string` | Display name shown in the tooltip |\n\n### Blame server\n\nThe server listens on `http://localhost:4317` and exposes:\n\n```\nGET /ownership?file=\u003crelative-path\u003e\n```\n\nReturns JSON with `latestCommit`, `latestAuthor`, `latestDate`, `commitHash`, `commitUrl`, `latestEmail`, `totalCommits`, and `contributors`.\n\n- `commitUrl` — full URL to the commit on the remote (e.g. `https://github.com/user/repo/commit/\u003chash\u003e`). `null` if no remote is configured.\n\n## Notes\n\n- The overlay and plugin are intended for **development only**. Do not include them in production builds.\n- The project must have a git history; the server calls `git log` and `git shortlog` under the hood.\n- The server only accepts relative paths and rejects path-traversal attempts.\n\n## Current limitations\n\nBlamescope is intended for **development only** and currently supports React-based projects on Vite and Next.js (both App Router and Pages Router). Vue and Svelte support is not available yet.\n\n## Roadmap\n\nCurrent support status:\n- **Vite + React** — full support ✅\n- **Remix / React Router v7** — Vite-based projects supported ✅\n- **Next.js App Router** — webpack loader + `withBlamescope` wrapper supported ✅\n- **Next.js Pages Router** — webpack loader + `withBlamescope` wrapper supported ✅\n- **Vue 3** — Vite plugin for single-file components (`.vue`) ⏳\n- **Svelte** — preprocessor for component root nodes ⏳\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpace11%2Fblamescope","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpace11%2Fblamescope","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpace11%2Fblamescope/lists"}