@amazon/vinyl-tsx

中文文档
5.0.0发布于 2026/11/16Apache-2.0TypeScriptESM + CJS构建来源已验证近 30 天下载 2062

TSX declarative markup for creating UI

原始使用文档
文档目录18 节
  1. Features
  2. Install
  3. Basic Usage
  4. Setting up JSX
  5. Creating Elements
  6. Children
  7. Reactive Properties
  8. Hook Extensions
  9. Style Hook
  10. Visibility Hook
  11. ClassList Hook
  12. Connection Hook
  13. Event Handlers
  14. Fragments
  15. Custom Components
  16. Conditional Rendering
  17. Best Practices
  18. License

@amazon/vinyl-tsx

Website npm size

A lightweight, reactive JSX runtime for creating dynamic DOM elements with TypeScript support. Provides a declarative way to build user interfaces with reactive data binding via @amazon/vinyl-observable.

Features

  • Reactive properties — bind observable values to DOM properties that update automatically.
  • Hook extensions — enhanced DOM manipulation through custom hooks (style, visible, classList).
  • Lifecycle management — automatic cleanup and connection tracking for DOM elements.
  • TypeScript support — full type safety with utility types for property extraction.
  • Zero dependencies — lightweight runtime with no external framework dependencies.
  • Performance optimized — efficient updates with passive event handlers and selective rendering.

Install

npm install @amazon/vinyl-tsx @amazon/vinyl-util @amazon/vinyl-observable

Basic Usage

Setting up JSX

Configure your TypeScript compiler to use the vinyl-tsx JSX factory:

// tsconfig.json
{
    "compilerOptions": {
        "jsx": "preserve",
        "jsxFactory": "jsx",
        "jsxFragmentFactory": "Fragment"
    }
}

Creating Elements

import { jsx } from '@amazon/vinyl-tsx'

// Basic element creation
const button = <button>Click me</button>

// With properties
const input = <input type="text" placeholder="Enter text" disabled={false} />

// With children
const container = (
    <div className="container">
        <h1>Title</h1>
        <p>Content goes here</p>
    </div>
)

Children

A child can be a Node, a string, an observable of either, or an array of children. Arrays, including nested arrays, are flattened, so lists don't need to be spread:

const items = ['One', 'Two', 'Three']

const list = (
    <ul>
        {items.map((item) => (
            <li>{item}</li>
        ))}
    </ul>
)

null, undefined, and false children are omitted and create no node, so optional content can be written inline:

function Greeting(props: { readonly user?: { readonly name: string } }) {
    return (
        <p>
            Hello{props.user && `, ${props.user.name}`}
            {props.user === undefined && <a href="/login">Sign in</a>}
        </p>
    )
}

Children are type-checked. true, numbers, and other values are compile errors; convert them explicitly:

const count = 3
const enabled = false as boolean

<p>{count}</p> // Error: number is not a valid child
<p>{String(count)}</p> // OK
<p>{enabled}</p> // Error: boolean may be true
<p>{enabled && 'Enabled'}</p> // OK

TypeScript widens a literal false written directly as a child to boolean, so <p>{false}</p> is also an error.

Reactive Properties

Use @amazon/vinyl-observable to create reactive properties that automatically update the DOM:

import { data } from '@amazon/vinyl-observable'
import { jsx } from '@amazon/vinyl-tsx'

const count = data(0)
const isVisible = data(true)

const counter = (
    <div>
        <span>Count: {count}</span>
        <button onclick={() => count.value++}>Increment</button>
        <button visible={isVisible}>Toggle me</button>
    </div>
)

count.value = 5 // DOM updates to show "Count: 5"
isVisible.value = false // Button becomes hidden

Hook Extensions

Style Hook

Apply CSS styles with support for both static and observable values:

import { data } from '@amazon/vinyl-observable'

const color = data('red')
const fontSize = data('16px')

const styledDiv = (
    <div
        style={{
            color, // Observable value
            fontSize, // Observable value
            backgroundColor: 'blue', // Static value
            padding: '10px', // Static value
        }}
    >
        Styled content
    </div>
)

color.value = 'green' // Text color changes to green

Visibility Hook

Control element visibility with the visible property:

const isVisible = data(true)

const conditionalElement = (
    <div visible={isVisible}>This element can be hidden/shown</div>
)

isVisible.value = false // Sets display: none
isVisible.value = true // Removes display property

ClassList Hook

Manage CSS classes dynamically with an array of static strings and/or observable values:

const theme = data<string | null>('dark')

const element = <div classList={['base-class', theme]}>Content</div>

// Element has classes: base-class dark
theme.value = 'light' // Updates to: base-class light
theme.value = null // Updates to: base-class

Connection Hook

Execute code when elements are connected to or disconnected from the DOM:

const element = (
    <div
        onConnect={(el) => {
            console.log('Element connected:', el)
            return () => {
                console.log('Element disconnected:', el)
            }
        }}
    >
        Content
    </div>
)

The callback receives the element typed by its tag, so element-specific APIs are available without a cast:

const player = <video onConnect={(el) => void el.play()} /> // el: HTMLVideoElement

A JSX expression itself is always typed JSX.Element (HTMLElement); TypeScript can't type it per tag. Use onConnect, or call jsx('video', {}) directly, when you need the specific element type.

Event Handlers

Touch and scroll events use passive listeners automatically:

const element = (
    <div
        ontouchstart={(e) => console.log('Touch start')}
        ontouchmove={(e) => console.log('Touch move')}
        onwheel={(e) => console.log('Wheel')}
        onmousedown={(e) => console.log('Mouse down')}
    >
        Interactive content
    </div>
)

Fragments

Use fragments to group elements with a wrapper div using display: contents:

import { Fragment } from '@amazon/vinyl-tsx'

const list = (
    <Fragment>
        <li>Item 1</li>
        <li>Item 2</li>
    </Fragment>
)

const list2 = (
    <>
        <li>Item 1</li>
        <li>Item 2</li>
    </>
)

Custom Components

interface ButtonProps {
    text: string
    onClick: () => void
    variant?: 'primary' | 'secondary'
}

function Button({ text, onClick, variant = 'primary' }: ButtonProps) {
    return (
        <button className={`btn btn-${variant}`} onclick={onClick}>
            {text}
        </button>
    )
}

const myButton = <Button text="Click me" onClick={() => alert('Clicked!')} />

Components receive their children as the second argument, as written, without flattening. The type of that parameter determines which children the component accepts in markup; a component without one accepts none:

import { type JsxChild } from '@amazon/vinyl-tsx'

function Card(props: { readonly title: string }, children: JsxChild[]) {
    return (
        <section className="card">
            <h2>{props.title}</h2>
            {children}
        </section>
    )
}

const card = (
    <Card title="Details">
        <p>Body</p>
    </Card>
)

<Button text="Hi" onClick={() => {}}>Child</Button> // Error: Button takes no children

Conditional Rendering

Unlike React, vinyl-tsx does not re-render — JSX expressions are evaluated once at creation time. Use the visible hook to reactively show or hide content:

const showDetails = data(false)

const userCard = (
    <div>
        <h3>John</h3>
        <div visible={showDetails}>
            <p>Email: [email protected]</p>
        </div>
        <button onclick={() => (showDetails.value = !showDetails.value)}>
            Toggle Details
        </button>
    </div>
)

Best Practices

  1. Initialize the connected observer once in your application to enable lifecycle management:

    import { initializeConnectedObserver } from '@amazon/vinyl-tsx'
    
    const cleanup = initializeConnectedObserver()
    
  2. Use observables for dynamic content — prefer observable values for properties that change over time.

  3. Leverage hook extensions — style, visible, and classList cover most common DOM manipulations.

  4. Type safety — let TypeScript check your props and children.

  5. Memory management — observable subscriptions are cleaned up automatically when elements are disconnected.

License

Apache-2.0

版本与发布记录

@amazon/vinyl-tsx 共发布 44 个版本,首次发布于 2026/05/28;过去 12 个月发布了 44 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
5.0.0latest2026/11/16今天
4.1.1-next.20261115174554next2026/11/16今天
4.1.1-next.202611151724472026/11/16今天
4.1.1-next.202611151644392026/11/16今天
4.1.1-next.202611150013552026/11/151 天前
4.1.1-next.202611131749092026/11/142 天前

其他发布通道:hotfix-chromos → 1.2.1,hotfix-close-drm-sessions → 1.2.2,next → 4.1.1-next.20261115174554。

关于 @amazon/vinyl-tsx 的常见问题

@amazon/vinyl-tsx 是什么?

TSX declarative markup for creating UI

如何安装 @amazon/vinyl-tsx?

在项目目录运行 npm install @amazon/vinyl-tsx,或使用 pnpm add / yarn add / bun add。

@amazon/vinyl-tsx 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@amazon/vinyl-tsx 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@amazon/vinyl-tsx 可以商用吗?

@amazon/vinyl-tsx 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@amazon/vinyl-tsx 的下载量有多少?

根据 npm 官方下载统计,@amazon/vinyl-tsx 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,062 次,日均约 69 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@amazon/vinyl-tsx 还在维护吗?

最新版本 5.0.0 发布于 2026/11/16(今天);至今共发布 44 个版本,其中过去 12 个月发布了 44 个;首次发布于 2026/05/28。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。