菜单
Port a React ecosystem library to an @octanejs/* binding. Use when adding a new binding package or bringing an existing one closer to upstream parity.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/octanejs/octane --skill react-library-port命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
Port a React ecosystem library to an @octanejs/* binding. Use when adding a new binding package or bringing an existing one closer to upstream parity.
Port a React ecosystem library to an @octanejs/* binding. Use when adding a new binding package or bringing an existing one closer to upstream parity.
Octane bindings for TanStack DB. useLiveQuery hook with dependency arrays (8 overloads: query function, config object, pre-created collection, disabled state via returning undefined/null). useLiveSuspenseQuery for Octane Suspense with Error Boundaries (data always defined). useLiveInfiniteQuery for cursor-based pagination (pageSize, fetchNextPage, hasNextPage, isFetchingNextPage). usePacedMutations for debounced Octane state updates. Return shape: data, state, collection, status, isLoading, isReady, isError. Import from @octanejs/tanstack-db (re-exports all of @tanstack/db).
基于 SOC 职业分类
正在显示 SKILL.md
| targets | ["*"] |
| name | react-library-port |
| description | Port a React ecosystem library to an @octanejs/* binding. Use when adding a new binding package or bringing an existing one closer to upstream parity. |
Use this when asked to port or bridge a React ecosystem package into Octane, add an @octanejs/* binding, or evaluate whether a React package can run on Octane.
Do not assume React component code can run unchanged. Octane is compiler-first:
.tsrx and compare behavior to React when possible.A binding is a port of a specific upstream release, not an Octane-flavored library that borrows the name. Work from the upstream source at a pinned version, module by module, and account for every export it publishes. A subset that covers the demo path is not a port, and neither is a rewrite from memory of the README.
Read first:
AGENTS.mddocs/react-library-compat-plan.mddocs/react-parity-testing.mddocs/differences-from-react.mdpackages/{zustand,query,motion,stylex,router,lexical,floating-ui,radix}/packages/three/UPSTREAM.md for the pin, source-boundary, and crosswalk formatvitest.config.js aliases/exclusions for existing binding packagesClassify the target library
forwardRef, synthetic events, React-style text onChange, StrictMode-only behavior, React internals. Controlled value/checked itself is supported.Pin the upstream release and bring its source into the repository
npm pack --dry-run or the equivalent) and the canonical repository at the release tag. Do not assume the registry artifact contains source, tests, build scripts, or even the same file layout as the repository. If source or tests are absent from the package, fetch them from the canonical tagged repository and record which artifact supplied each boundary.packages/<name>/UPSTREAM.md: package, exact version, tag commit SHA, the supported upstream range the port advertises, and any peer or oracle versions (packages/three/UPSTREAM.md is the model).packages/<name>/upstream/, byte-exact and unmodified, keeping the upstream directory layout, its LICENSE, and its copyright headers. .prettierignore already covers packages/*/upstream/, so vendored bytes stay unformatted; leave the directory out of the package's published files so it remains development evidence rather than shipped code.UPSTREAM.md; everything below still applies.src/, so each Octane module sits at the path of the upstream module it replaces and a reviewer can read the two side by side. Where a framework-neutral core is reused verbatim, say so in the crosswalk instead of vendoring it.Create or update package shape
packages/<name>/ with , , , , , and README.packages/<name>/upstream/*: the pinned upstream source, byte-exact, with its
LICENSE, prettier-ignored, and unpublished.packages/<name>/UPSTREAM.md: the pin (package, version, tag commit,
advertised range, oracle versions), the source boundary, the export crosswalk
with evidence, and the disposition of every upstream test file.packages/<name>/src/* binding implementation, laid out to mirror the upstream
modules it replaces.status.json whose surface and divergences match the crosswalk.react-parity:check and the generic React parity
execution group.docs/react-library-compat-plan.md scorecard.Existing bindings predate this requirement and are not all pinned and vendored yet. Bring a package up to it when you next touch it, and say in the handoff which exports the crosswalk still leaves open.
package.jsonsrc/tests/tsconfig.jsonUPSTREAM.md@octanejs/<name>.vitest.config.js following existing packages.docs/react-parity-testing.md: use
testExecution: { group: 'react-parity' } when the dedicated runner owns
the complete project, or add testExecution.include containing only the
parity-owned patterns when ordinary package tests share that project. The
base test.include remains the complete local project.ci.yml, a package-specific parity job or
exclusion environment variable, or shard/Node/job details to
testExecution. vitest.ci-sharded.config.js derives the ordinary-shard
complement from the ownership metadata.pnpm-workspace.yaml only when needed.Reuse core, reimplement binding
useSyncExternalStore, useState, useReducer, useEffect, useLayoutEffect, useMemo, useCallback, useRef, useContext, createContext, createPortal, flushSync, use.useDebugValue can be a no-op shim unless devtools behavior is explicitly in scope.forwardRef to React 19 refs-as-props (ref is a prop in Octane)..tsrx, check whether the compiler must auto-slot them or whether the package source should be excluded and forward slots via subSlot like floating-ui.Crosswalk every upstream export
UPSTREAM.md carries a row for every export of the pinned upstream React entry points, classified as ported, reused verbatim from a framework-neutral core, divergence, or not applicable, each with its evidence (the test that proves it, or the reason it cannot apply to Octane).status.json must agree with the crosswalk: surface describes what is covered, and divergences lists what a consumer would notice. pnpm bindings:status regenerates docs/bindings-status.md from it.Run the pinned release's own tests
.tsrx, swap @testing-library/react for @octanejs/testing-library, keep the upstream case name, and cite the origin like the conformance suite does (// Per <upstream path>:<line>). node scripts/scaffold-react-port.mjs <react-test-file> emits a triage checklist to work from.UPSTREAM.md records the disposition of every upstream test file: run as-is, ported (and where it now lives), or out of scope with the reason (React internals, react-test-renderer, StrictMode double-invoke, an API Octane does not expose). Vendor the upstream tests alongside the source when their license allows it, so the next pin is a diff there too..skip, it.todo, and expected-failure markers are not how an unported case is tracked; the crosswalk is (pnpm test:markers:check).// OCTANE DIVERGENCE: rationale..tsx/.tsrx component paths, or a documented event-name mapping), reject every other structural change, and add negative controls for a skipped file, deleted assertion, and removed @ts-expect-error.packages/<name>/audit/react-parity.json. react-parity:check discovers
package manifests automatically; do not create a package-specific CI entry
point. A locally runnable helper that the generic React parity job never
invokes is not parity evidence.lane.project match a project name in
vitest.config.js. Keep parity lane files inside testExecution.include
for a mixed project, and keep Octane-only conformance/framework-contract
files outside it so the general shards still execute them.Build test strategy for what upstream does not cover
.tsrx fixture runs in Octane and React.innerHTML.Triage divergence
UPSTREAM.md and status.json with the reason,
what a consumer should do instead, and a passing behavioral test that pins
the Octane behavior. An unreachable API is never a reason to quietly drop
the export.onChange. Rewrite only standard
text-host wiring that means “every edit” to onInput; keep select and
checkbox/radio native change handlers. A real text commit may use
suppressNativeChangeWarning with a behavioral test.Validate
docs/react-parity-testing.md; the latter must execute only the
non-parity complement.packages/octane.pnpm typecheck for API/package changes.pnpm react-parity:check for binding work and confirm every required manifest lane executes rather than only validates metadata.pnpm format:files <path...> while iterating and
pnpm format:files:check <path...> for a scoped check. Use the repo-wide
pnpm format:check for the final gate.