Back to Skills
AI

Agentation

A desktop development tool that enables developers to annotate UI elements and generate structured feedback for AI coding agents.

by Benji Taylor, Dennis Jin, Alex Vanderzon | v1.0.0 | View Repository
ai-tool ui-annotation react developer-tools ai-agent feedback

Installation

npm install agentation

Add <Agentation /> component to your React app

Compatibility

React 18+ Claude Code Cursor Windsurf

Agentation

Agentation bridges the gap between visual design issues and code-level fixes. Instead of describing UI elements vaguely (“the blue button in the sidebar”), it provides precise CSS selectors that AI agents can grep directly in your codebase.

Hướng dẫn tích hợp Agentation vào Next.js

Bước 1: Cài đặt

npm install agentation

Bước 2: Tích hợp

Cách 1: App Router (Next.js 13+)

Thêm vào app/layout.tsx hoặc app/layout.js:

import { Agentation } from "agentation";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="vi">
      <body>
        {children}
        {process.env.NODE_ENV === "development" && <Agentation />}
      </body>
    </html>
  );
}

Nếu gặp lỗi hydration, tạo client component riêng:

// components/AgentationWrapper.tsx
"use client";

import { Agentation } from "agentation";

export default function AgentationWrapper() {
  if (process.env.NODE_ENV !== "development") return null;
  return <Agentation />;
}

Rồi import vào layout:

// app/layout.tsx
import AgentationWrapper from "@/components/AgentationWrapper";

export default function RootLayout({ children }) {
  return (
    <html lang="vi">
      <body>
        {children}
        <AgentationWrapper />
      </body>
    </html>
  );
}

Cách 2: Pages Router

Thêm vào pages/_app.tsx hoặc pages/_app.js:

import type { AppProps } from "next/app";
import { Agentation } from "agentation";

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      {process.env.NODE_ENV === "development" && <Agentation />}
    </>
  );
}

Hướng dẫn tích hợp Agentation vào Astro

Bước 1: Cài đặt React integration cho Astro

Astro cần React integration để hiểu file .jsx. Chạy lệnh trong thư mục gốc project:

pnpm add @astrojs/react react react-dom

Hoặc dùng npm/yarn:

npm install @astrojs/react react react-dom
# hoặc
yarn add @astrojs/react react react-dom

Bước 2: Cấu hình Astro

Mở file astro.config.mjs và thêm React integration:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';

export default defineConfig({
  integrations: [react()]
});

Nếu đã có các integration khác, thêm react() vào mảng:

import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
import tailwind from '@astrojs/tailwind'; // ví dụ

export default defineConfig({
  integrations: [react(), tailwind()]
});

Bước 3: Cài đặt Agentation

pnpm add agentation

Hoặc:

npm install agentation
# hoặc
yarn add agentation

Bước 4: Tạo component wrapper

Tạo file src/components/AgentationWrapper.jsx:

import { Agentation } from "agentation";

export default function AgentationWrapper() {
  return <Agentation />;
}

Bước 5: Thêm vào Layout hoặc Page

Cách 1: Thêm vào Layout (khuyến khích)

Mở file src/layouts/Layout.astro (hoặc tạo mới nếu chưa có):

---
import AgentationWrapper from '../components/AgentationWrapper.jsx';
const isDev = import.meta.env.DEV;
---

<html lang="vi">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width" />
    <title>My Astro Site</title>
  </head>
  <body>
    <slot />
    
    {isDev && <AgentationWrapper client:only="react" />}
  </body>
</html>

Cách 2: Thêm trực tiếp vào Page

---
// src/pages/index.astro
import AgentationWrapper from '../components/AgentationWrapper.jsx';
const isDev = import.meta.env.DEV;
---

<html lang="vi">
  <head>
    <meta charset="UTF-8" />
    <title>Trang chủ</title>
  </head>
  <body>
    <h1>Xin chào</h1>
    <p>Nội dung trang</p>
    
    {isDev && <AgentationWrapper client:only="react" />}
  </body>
</html>

Bước 6: Xóa cache và khởi động lại

rm -rf node_modules/.astro
pnpm dev

Lưu ý quan trọng

Lưu ýGiải thích
client:only="react"Bắt buộc - Agentation cần DOM, chỉ chạy ở client
import.meta.env.DEVChỉ hiển thị trong môi trường development
Desktop onlyAgentation không hoạt động trên mobile
Không gửi dữ liệuMọi thứ xử lý local, bạn tự copy/paste

Kiểm tra hoạt động

Môi trườngHoạt động?
pnpm dev (localhost)✅ Có
pnpm build + pnpm preview❌ Không
Deploy Vercel/Netlify❌ Không

Xử lý lỗi thường gặp

Lỗi: “No valid renderer was found for .jsx”

Kiểm tra đã cài đủ package:

pnpm list @astrojs/react react react-dom

Nếu thiếu, cài lại:

pnpm add @astrojs/react react react-dom

Lỗi: Component không hiển thị

Đảm bảo có client:only="react" trong thẻ component:

<!-- ❌ Sai -->
<AgentationWrapper />

<!-- ✅ Đúng -->
<AgentationWrapper client:only="react" />

Lỗi: Xung đột npm/pnpm

Nếu project dùng pnpm, luôn dùng pnpm add thay vì npm install.

Lưu ý

  • Component sẽ tự động ẩn ở production
  • Chỉ hoạt động trên desktop
  • Không gửi dữ liệu đi đâu, mọi thứ xử lý local
Browse All Skills