Skip to content

Commit 7e068d2

Browse files
lazarvlazarv
authored
feat: skill for coding agents (#365)
## Summary - Add installable Claude Code skill (`skills/react-server/SKILL.md`) covering all core APIs, use directives, file-system router conventions, component patterns, and deployment adapters - Add Claude Code integration docs page (English + Japanese) with `npx skills add lazarv/react-server` installation instructions - Add root `CLAUDE.md` for repository contributors - Allow `$schema` field in `react-server.config.json` by skipping it during validation and stripping it on config load
1 parent 90a4486 commit 7e068d2

6 files changed

Lines changed: 764 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# @lazarv/react-server — Contributor Guide
2+
3+
This is the monorepo for `@lazarv/react-server`, an open React Server Components runtime built on the Vite Environment API.
4+
5+
## Monorepo Structure
6+
7+
```
8+
packages/
9+
react-server/ # Core runtime (@lazarv/react-server)
10+
rsc/ # RSC serialization (@lazarv/rsc)
11+
create-react-server/ # Project scaffold CLI (@lazarv/create-react-server)
12+
docs/ # Documentation site (react-server.dev), built with react-server itself
13+
examples/ # 33+ example applications
14+
test/ # Integration tests (Vitest + Playwright)
15+
```
16+
17+
Package manager: **pnpm** (enforced via `preinstall` check).
18+
19+
## Key Commands
20+
21+
```sh
22+
# Install dependencies
23+
pnpm install
24+
25+
# Run docs dev server
26+
pnpm docs
27+
28+
# Build docs
29+
pnpm docs-build
30+
31+
# Run all tests (from root)
32+
pnpm test
33+
34+
# Run tests from test/ directory
35+
cd test
36+
pnpm test-dev-base # Dev mode tests (excludes app tests)
37+
pnpm test-dev-apps # Dev mode app tests
38+
pnpm test-build-start # Build + start mode tests
39+
pnpm test-dev # All dev mode tests
40+
41+
# Format code
42+
pnpm format # Uses oxfmt
43+
44+
# Lint
45+
pnpm lint # Uses oxlint
46+
```
47+
48+
## Coding Conventions
49+
50+
- **ESM only** — all packages use `"type": "module"`
51+
- **No TypeScript in core packages** — pure JavaScript with `.d.ts` type definitions
52+
- **JSX file extensions** — use `.jsx` for React components
53+
- **Config/server files** — use `.mjs` extension
54+
- **Commit messages** — conventional commits (`feat:`, `fix:`, `docs:`, `chore:`, `perf:`, `refactor:`, `test:`, `build:`, `ci:`)
55+
- Format: `type(scope): subject` (e.g., `feat(router): add catch-all routes`)
56+
- Imperative, present tense, no capitalization, no period at end
57+
- Enforced by commitlint
58+
59+
## Docs Site
60+
61+
- Built with `@lazarv/react-server` itself (dogfooding)
62+
- MDX pages in `docs/src/pages/en/(pages)/`
63+
- Bilingual: English (`en/`) and Japanese (`ja/`)
64+
- Deployed to Cloudflare
65+
- All pages exported as `.md` for AI consumption
66+
- Config: `docs/react-server.config.mjs`
67+
68+
## Test Infrastructure
69+
70+
- **Vitest** for test runner
71+
- **Playwright (Chromium)** for browser-based integration tests
72+
- Two configs: `vitest.config.mjs` (dev mode) and `vitest.config.build.mjs` (build+start mode)
73+
- Test fixtures in `test/fixtures/`
74+
- Test specs in `test/__test__/`
75+
76+
## Package Exports
77+
78+
The main `@lazarv/react-server` package has many subpath exports:
79+
`/client`, `/server`, `/config`, `/router`, `/navigation`, `/error-boundary`, `/remote`, `/worker`, `/mcp`, `/cache`, and more. Check `packages/react-server/package.json` exports field for the full list.

‎docs/src/pages/en/(pages)/integrations/claude-code.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Claude Code
3+
category: Integrations
4+
order: 7
5+
---
6+
7+
import Link from "../../../../components/Link.jsx";
8+
9+
# Claude Code
10+
11+
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's official CLI tool for AI-assisted coding. `@lazarv/react-server` provides an installable Claude Code skill that gives Claude deep knowledge of the runtime's APIs, conventions, and patterns — so you can build react-server applications using agentic coding.
12+
13+
<Link name="install-skill">
14+
## Install the skill
15+
</Link>
16+
17+
Install the skill into your project using `npx skills`:
18+
19+
```sh
20+
npx skills add lazarv/react-server
21+
```
22+
23+
This installs the `react-server` skill from the repository's `skills/` directory into your project's `.claude/skills/` folder. Once installed, the `/react-server` slash command becomes available in Claude Code.
24+
25+
To install it globally so it's available across all your projects:
26+
27+
```sh
28+
npx skills add lazarv/react-server --global
29+
```
30+
31+
<Link name="usage">
32+
## Usage
33+
</Link>
34+
35+
Start Claude Code in your project directory and use the `/react-server` slash command to give Claude the full context of the runtime. You can pass additional instructions as arguments:
36+
37+
```sh
38+
# General react-server context
39+
/react-server
40+
41+
# With specific instructions
42+
/react-server add a new /api/users route that returns a list of users from the database
43+
44+
# Scaffold a new feature
45+
/react-server create a live component that streams stock prices
46+
```
47+
48+
The skill loads all core patterns, file-system router conventions, use directives, import paths, and component patterns into Claude's context automatically.
49+
50+
<Link name="docs-as-context">
51+
## Using docs as context
52+
</Link>
53+
54+
Every page on this documentation site is also available as plain markdown. You can paste these URLs directly in a Claude Code conversation for detailed, up-to-date reference on specific features:
55+
56+
| Topic | URL |
57+
|---|---|
58+
| Server Components | `https://react-server.dev/guide/server-components.md` |
59+
| Client Components | `https://react-server.dev/guide/client-components.md` |
60+
| Server Functions | `https://react-server.dev/guide/server-functions.md` |
61+
| File Router | `https://react-server.dev/router/file-router.md` |
62+
| Configuration | `https://react-server.dev/features/configuration.md` |
63+
| Caching | `https://react-server.dev/features/caching.md` |
64+
| HTTP | `https://react-server.dev/features/http.md` |
65+
| Live Components | `https://react-server.dev/features/live-components.md` |
66+
| Workers | `https://react-server.dev/features/workers.md` |
67+
| MCP | `https://react-server.dev/features/mcp.md` |
68+
| Error Handling | `https://react-server.dev/features/error-handling.md` |
69+
| API Routes | `https://react-server.dev/router/api-routes.md` |
70+
| Middlewares | `https://react-server.dev/router/middlewares.md` |
71+
| Outlets | `https://react-server.dev/router/outlets.md` |
72+
| CLI | `https://react-server.dev/features/cli.md` |
73+
74+
<Link name="whats-included">
75+
## What's included
76+
</Link>
77+
78+
The skill provides Claude Code with comprehensive knowledge of:
79+
80+
- **Use directives** — `"use client"`, `"use server"`, `"use live"`, `"use worker"`, `"use cache"`, `"use dynamic"`, `"use static"` and their semantics including inline (lexically scoped) usage
81+
- **File-system router** — page, layout, dynamic route, catch-all, outlet, middleware, API route, and MCP endpoint conventions
82+
- **Import paths** — all `@lazarv/react-server/*` subpath exports and their key APIs
83+
- **Component patterns** — server components, client components, server functions, live components, workers, and lexically scoped RSC with arbitrary server/client nesting
84+
- **HTTP hooks** — `useUrl`, `usePathname`, `headers`, `cookie`, `redirect`, `rewrite`, `status`, `after`, and more
85+
- **Caching** — response cache, in-memory cache, cache directive with TTL/tags/profiles, revalidation
86+
- **Configuration** — `defineConfig`, extension configs, mode-specific configs, JSON schema, env variables
87+
- **Navigation** — `Link`, `Refresh`, `ReactServerComponent`, programmatic navigation via `useClient`
88+
- **Error handling** — `ErrorBoundary` component and file-router error/loading conventions
89+
- **Deployment** — all 11 adapter targets (Vercel, Netlify, Cloudflare, AWS, Azure, Bun, Deno, Docker, Firebase, etc.)
90+
- **Advanced features** — micro-frontends with `RemoteComponent`, MCP server with `createServer`/`createTool`/`createResource`/`createPrompt`, MDX support
91+
92+
<Link name="updating">
93+
## Updating the skill
94+
</Link>
95+
96+
To update to the latest version of the skill:
97+
98+
```sh
99+
npx skills add lazarv/react-server
100+
```
101+
102+
The skill is maintained alongside the documentation and updated with each release.

‎docs/src/pages/ja/(pages)/integrations/claude-code.mdx‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
title: Claude Code
3+
category: Integrations
4+
order: 7
5+
---
6+
7+
import Link from "../../../../components/Link.jsx";
8+
9+
# Claude Code
10+
11+
[Claude Code](https://docs.anthropic.com/en/docs/claude-code)はAnthropicが提供するAIコーディング支援の公式CLIツールです。`@lazarv/react-server`はインストール可能なClaude Codeスキルを提供しており、ランタイムのAPI、規約、パターンに関する深い知識をClaudeに与えることで、エージェントコーディングによるreact-serverアプリケーションの構築を支援します。
12+
13+
<Link name="install-skill">
14+
## スキルのインストール
15+
</Link>
16+
17+
`npx skills`を使用してプロジェクトにスキルをインストールします：
18+
19+
```sh
20+
npx skills add lazarv/react-server
21+
```
22+
23+
これにより、リポジトリの`skills/`ディレクトリから`react-server`スキルがプロジェクトの`.claude/skills/`フォルダにインストールされます。インストール後、Claude Codeで`/react-server`スラッシュコマンドが利用可能になります。
24+
25+
すべてのプロジェクトで利用できるようにグローバルにインストールする場合：
26+
27+
```sh
28+
npx skills add lazarv/react-server --global
29+
```
30+
31+
<Link name="usage">
32+
## 使い方
33+
</Link>
34+
35+
プロジェクトディレクトリでClaude Codeを起動し、`/react-server`スラッシュコマンドを使用してClaudeにランタイムの完全なコンテキストを提供します。引数として追加の指示を渡すことができます：
36+
37+
```sh
38+
# react-serverの一般的なコンテキスト
39+
/react-server
40+
41+
# 具体的な指示を付けて
42+
/react-server データベースからユーザー一覧を返す /api/users ルートを追加して
43+
44+
# 新機能のスキャフォールド
45+
/react-server 株価をストリーミングするライブコンポーネントを作成して
46+
```
47+
48+
スキルはすべてのコアパターン、ファイルシステムルーターの規約、useディレクティブ、インポートパス、コンポーネントパターンをClaudeのコンテキストに自動的に読み込みます。
49+
50+
<Link name="docs-as-context">
51+
## ドキュメントをコンテキストとして使用
52+
</Link>
53+
54+
このドキュメントサイトのすべてのページは、プレーンマークダウンとしても利用できます。特定の機能に関する詳細で最新のリファレンスとして、これらのURLをClaude Codeの会話に直接貼り付けることができます：
55+
56+
| トピック | URL |
57+
|---|---|
58+
| サーバーコンポーネント | `https://react-server.dev/guide/server-components.md` |
59+
| クライアントコンポーネント | `https://react-server.dev/guide/client-components.md` |
60+
| サーバー関数 | `https://react-server.dev/guide/server-functions.md` |
61+
| ファイルルーター | `https://react-server.dev/router/file-router.md` |
62+
| 設定 | `https://react-server.dev/features/configuration.md` |
63+
| キャッシュ | `https://react-server.dev/features/caching.md` |
64+
| HTTP | `https://react-server.dev/features/http.md` |
65+
| ライブコンポーネント | `https://react-server.dev/features/live-components.md` |
66+
| ワーカー | `https://react-server.dev/features/workers.md` |
67+
| MCP | `https://react-server.dev/features/mcp.md` |
68+
| エラーハンドリング | `https://react-server.dev/features/error-handling.md` |
69+
| APIルート | `https://react-server.dev/router/api-routes.md` |
70+
| ミドルウェア | `https://react-server.dev/router/middlewares.md` |
71+
| アウトレット | `https://react-server.dev/router/outlets.md` |
72+
| CLI | `https://react-server.dev/features/cli.md` |
73+
74+
<Link name="whats-included">
75+
## 含まれる内容
76+
</Link>
77+
78+
このスキルはClaude Codeに以下の包括的な知識を提供します：
79+
80+
- **useディレクティブ** — `"use client"`、`"use server"`、`"use live"`、`"use worker"`、`"use cache"`、`"use dynamic"`、`"use static"`のセマンティクスとインライン（レキシカルスコープ）での使用方法
81+
- **ファイルシステムルーター** — ページ、レイアウト、動的ルート、キャッチオール、アウトレット、ミドルウェア、APIルート、MCPエンドポイントの規約
82+
- **インポートパス** — すべての`@lazarv/react-server/*`サブパスエクスポートとその主要API
83+
- **コンポーネントパターン** — サーバーコンポーネント、クライアントコンポーネント、サーバー関数、ライブコンポーネント、ワーカー、およびサーバー/クライアントの任意のネストが可能なレキシカルスコープRSC
84+
- **HTTPフック** — `useUrl`、`usePathname`、`headers`、`cookie`、`redirect`、`rewrite`、`status`、`after`など
85+
- **キャッシュ** — レスポンスキャッシュ、インメモリキャッシュ、TTL/タグ/プロファイル付きキャッシュディレクティブ、再検証
86+
- **設定** — `defineConfig`、拡張設定、モード別設定、JSONスキーマ、環境変数
87+
- **ナビゲーション** — `Link`、`Refresh`、`ReactServerComponent`、`useClient`によるプログラムナビゲーション
88+
- **エラーハンドリング** — `ErrorBoundary`コンポーネントとファイルルーターのerror/loading規約
89+
- **デプロイ** — 全11アダプターターゲット（Vercel、Netlify、Cloudflare、AWS、Azure、Bun、Deno、Docker、Firebaseなど）
90+
- **高度な機能** — `RemoteComponent`によるマイクロフロントエンド、`createServer`/`createTool`/`createResource`/`createPrompt`によるMCPサーバー、MDXサポート
91+
92+
<Link name="updating">
93+
## スキルの更新
94+
</Link>
95+
96+
最新バージョンのスキルに更新するには：
97+
98+
```sh
99+
npx skills add lazarv/react-server
100+
```
101+
102+
スキルはドキュメントと同時にメンテナンスされ、各リリースで更新されます。

‎packages/react-server/config/index.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -175,6 +175,9 @@ export async function loadConfig(initialConfig, options = {}) {
175175
config[root]
176176
);
177177

178+
// Remove $schema (JSON Schema reference for IDE validation, not a runtime option)
179+
delete config[CONFIG_ROOT].$schema;
180+
178181
for (const key of configKeys) {
179182
if (key === CONFIG_ROOT || key === root) continue;
180183
merge(

‎packages/react-server/config/validate.mjs‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -683,6 +683,9 @@ function validateObject(config, schema, prefix = "") {
683683
// Skip symbol keys (like CONFIG_ROOT, CONFIG_PARENT)
684684
if (typeof key === "symbol") continue;
685685

686+
// Skip $schema (JSON Schema reference for IDE validation)
687+
if (key === "$schema") continue;
688+
686689
const path = prefix ? `${prefix}.${key}` : key;
687690
const validator = schema[key];
688691

0 commit comments

Comments
 (0)