DOM 组件源元素

一个用于从 DOM 元素中查找 React JSX 源上下文的 TypeScript 库 通过源图解决 React 服务器组件位置.

特征

• 将选定的JSX定义与React 所有人援引祖先区分开来.
• 保护客户端定义嵌入服务器所有者下方 .
• 支持动态回放纤维键和有边框的向外转动.
• 在一个操作中解决完整的服务器源上下文 .
• 支持 Turbopack, webpack, 文件 URL, 以及地图相对源路径.
• 返回结构化源解析失败 .

安装

yarn add dom-element-to-component-source

在 npm 发布之前, 安装精确的 Git 承诺 。 包裹 prepack 脚本构建每个声明 dist 安装时导出 .

yarn add dom-element-to-component-source@https://github.com/frontman-ai/dom-element-to-component-source.git#<full-commit-sha>

浏览器 API

import { getElementSourceContext } from 'dom-element-to-component-source'

const button = document.querySelector('button')
if (!button) throw new Error('Button not found')

const result = await getElementSourceContext(button, { maxDepth: 10 })
if (!result.success) {
  throw new Error(result.error)
}

const { definition, invocations } = result.data
if (definition) {
  console.log(`${definition.file}:${definition.line}:${definition.column}`)
}

for (const invocation of invocations) {
  console.log(`${invocation.file}:${invocation.line}:${invocation.column}`)
}

definition 是被选中元素的 JSX 定义 当反应曝光. invocations 包含所有者呼叫站点 。 反应服务器 仍保留构成部分地点 about://React/Server/... URL 直至解决 服务器 API.

浏览器类型

interface ElementSourceContext {
  definition?: SourceLocation
  invocations: SourceLocation[]
}

type ElementSourceContextResult =
  | { success: true; data: ElementSourceContext }
  | { success: false; error: string }

interface ElementSourceContextOptions {
  maxDepth?: number
}

组件名称发现

使用 getElementComponentName 当只有最近符合条件的 React 组件时 需要名称。 它检查所有者 纤维之前返回 纤维最多检查 默认情况下,每个有分界线的转弯处有10个节点.

import { getElementComponentName } from 'dom-element-to-component-source'

const name = getElementComponentName(element, {
  excludedNames: ['FrameworkWrapper'],
  includeUnderscorePrefixed: false,
})

interface ElementComponentNameOptions {
  maxDepth?: number
  excludedNames?: readonly string[]
  includeUnderscorePrefixed?: boolean
}

Fragment 财务报告和审定财务报表 Suspense 总是被忽略。 通知人除外情形被添加到 这些结构性排斥。 除非 includeUnderscorePrefixed 实值 false。 。 。 .

服务器 API

从专用服务器条目导入服务器功能 。 永远不要导入 输入浏览器代码.

import { resolveElementSourceContext } from 'dom-element-to-component-source/server'

const result = await resolveElementSourceContext(context, {
  projectRoot: '/absolute/path/to/project',
})

if (!result.success) {
  console.error(result.error.code, result.error.message)
  return
}

console.log(result.data.definition)
console.log(result.data.invocations)

解析器保存普通位置并解决每个 about://React/Server/file:///... 定义和援引。 生成的文件 和源地图必须在峡谷内解决 projectRoot 在他们之前 读取.

返回源路径是不可信的输出 。 原始源图条目可能 外部解决 projectRoot 并且不需要存在。 消费者必须批准 每一个返回的路径 之前揭露它或从它阅读。 消费者政策可以 包括允许的源根,存在检查, cononical symlink 封存, 并转换为相对路径.

Next.js 应用程序应该将这个软件包外部化. 私人活动 source-map 依赖性仍然是执行细节,可以装载相邻的 mappings.wasm 运行时的文件 :

module.exports = {
  serverExternalPackages: ['dom-element-to-component-source'],
}

服务器结果

type SourceResolutionResult =
  | { success: true; data: ElementSourceContext }
  | {
      success: false
      error: {
        code:
          | 'INVALID_REACT_URL'
          | 'GENERATED_FILE_NOT_FOUND'
          | 'SOURCE_MAP_NOT_FOUND'
          | 'POSITION_NOT_FOUND'
          | 'RESOLUTION_FAILED'
        message: string
      }
    }

来源位置

interface SourceLocation {
  file: string
  line: number
  column: number
  componentName?: string
  tagName?: string
  sourceCode?: string
  componentProps?: Record<string, SerializableValue>
}

所需资源

• 节点.js 20.19或服务器分辨率更新.
• 反应开发元数据用于浏览器提取.
• React 服务器组件分辨率的源地图.

发展

yarn install --immutable
yarn test:run
yarn type-check
yarn build
yarn pack --dry-run

许可证

麻省理工学院