ripple-ts

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RippleTS Skill

This skill helps you work with RippleTS, a TypeScript UI framework that combines the best parts of React, Solid, and Svelte.

这款Skill可帮助你使用RippleTS——一款融合了React、Solid和Svelte优势的TypeScript UI框架。

Documentation Links

文档链接

AI/LLM Documentation: https://www.ripple-ts.com/llms.txt (comprehensive reference, read this)
Official Docs: https://www.ripple-ts.com/docs
GitHub: https://github.com/Ripple-TS/ripple

AI/LLM文档：https://www.ripple-ts.com/llms.txt（综合性参考文档，建议阅读）
官方文档：https://www.ripple-ts.com/docs
GitHub仓库：https://github.com/Ripple-TS/ripple

Key Concepts for LLMs

面向LLM的核心概念

File Extension

文件扩展名

RippleTS uses

.ripple

files with TypeScript-first JSX-like syntax.

RippleTS使用

.ripple

文件，采用TypeScript优先类JSX语法。

Component Definition

组件定义

Components use the

component

keyword, NOT functions returning JSX:

ripple

component Button(props: { text: string, onClick: () => void }) {
  <button onClick={props.onClick}>
    {props.text}
  </button>
}

组件使用

component

关键字定义，而非返回JSX的函数：

ripple

component Button(props: { text: string, onClick: () => void }) {
  <button onClick={props.onClick}>
    {props.text}
  </button>
}

CRITICAL RULES

重要规则

Text Must Be in Expressions: Unlike HTML/JSX, raw text is NOT allowed. Always wrap text in curly braces:
- ❌
```
<div>Hello</div>
```
- ✅
```
<div>{"Hello"}</div>
```
Templates Only Inside Components: JSX-like elements can ONLY exist inside
```
component
```
function bodies, not in regular functions or variables.

文本必须放在表达式中：与HTML/JSX不同，RippleTS不允许直接使用原始文本，必须将文本放在大括号
```
{}
```
中：
- ❌
```
<div>Hello</div>
```
- ✅
```
<div>{"Hello"}</div>
```
模板仅能在组件内部使用：类JSX元素只能存在于
```
component
```
函数体内，不能在普通函数或变量中定义。

Reactivity

响应式特性

Use

track()

to create reactive values and

to access them:

ripple

import { track } from 'ripple';

export component Counter() {
  let count = track(0);
  
  <div>
    <p>{"Count: "}{@count}</p>
    <button onClick={() => @count++}>{"Increment"}</button>
  </div>
}

使用

track()

创建响应式值，通过

访问这些值：

ripple

import { track } from 'ripple';

export component Counter() {
  let count = track(0);
  
  <div>
    <p>{"Count: "}{@count}</p>
    <button onClick={() => @count++}>{"Increment"}</button>
  </div>
}

Reactive Collections

响应式集合

Use special syntax for fully reactive collections:

Arrays:
```
#[1, 2, 3]
```
or
```
new TrackedArray(1, 2, 3)
```
Objects:
```
#{a: 1, b: 2}
```
or
```
new TrackedObject({a: 1})
```

针对完全响应式集合，可使用以下特殊语法：

数组：
```
#[1, 2, 3]
```
或
```
new TrackedArray(1, 2, 3)
```
对象：
```
#{a: 1, b: 2}
```
或
```
new TrackedObject({a: 1})
```

Control Flow

控制流

Templates support inline control flow:

ripple

component App(props: { items: string[] }) {
  <div>
    if (props.items.length > 0) {
      <ul>
        for (const item of props.items; index i) {
          <li>{item}</li>
        }
      </ul>
    } else {
      <p>{"No items"}</p>
    }
  </div>
}

模板支持内联控制流：

ripple

component App(props: { items: string[] }) {
  <div>
    if (props.items.length > 0) {
      <ul>
        for (const item of props.items; index i) {
          <li>{item}</li>
        }
      </ul>
    } else {
      <p>{"No items"}</p>
    }
  </div>
}

Scoped CSS

作用域CSS

Add

<style>

elements directly in components for scoped styles:

ripple

component StyledComponent() {
  <div class="container">
    <h1>{"Styled Content"}</h1>
  </div>
  <style>
    .container {
      background: blue;
      padding: 1rem;
    }
  </style>
}

可在组件内直接添加

<style>

元素以实现作用域样式：

ripple

component StyledComponent() {
  <div class="container">
    <h1>{"Styled Content"}</h1>
  </div>
  <style>
    .container {
      background: blue;
      padding: 1rem;
    }
  </style>
}

Dynamic Classes

动态类名

Use object/array syntax for conditional classes (powered by clsx):

ripple

let includeBaz = track(true);
<div class={{ foo: true, bar: false, baz: @includeBaz }}></div>

可使用对象/数组语法实现条件类名（基于clsx）：

ripple

let includeBaz = track(true);
<div class={{ foo: true, bar: false, baz: @includeBaz }}></div>

Installation & Setup

安装与配置

bash

undefined

bash

undefined

Create new project from template

从模板创建新项目

npx degit Ripple-TS/ripple/templates/basic my-app cd my-app npm i && npm run dev

Or install in existing project

或在现有项目中安装

npm install ripple npm install --save-dev '@ripple-ts/vite-plugin'

undefined

npm install ripple npm install --save-dev '@ripple-ts/vite-plugin'

undefined

VSCode Extension

VSCode扩展

Name: "Ripple for VS Code"
ID:
```
Ripple-TS.ripple-ts-vscode-plugin
```

名称："Ripple for VS Code"
ID：
```
Ripple-TS.ripple-ts-vscode-plugin
```

React Compatibility

React兼容性

Ripple supports embedding React components using

<tsx:react>

blocks. Requires

@ripple-ts/compat-react

package and configuration in

mount()

Ripple支持通过

<tsx:react>

块嵌入React组件。需要安装

@ripple-ts/compat-react

包并在

mount()

中进行配置。

Best Practices

最佳实践

Use
```
track()
```
for reactive state
Wrap all text content in expressions
```
{}
```
Use scoped
```
<style>
```
elements for component styling
Use
```
effect()
```
for side effects, not direct reactive access
Keep components focused with TypeScript interfaces for props

使用
```
track()
```
管理响应式状态
将所有文本内容放在表达式
```
{}
```
中
使用作用域
```
<style>
```
元素进行组件样式设计
使用
```
effect()
```
处理副作用，而非直接访问响应式值
为组件Props定义TypeScript接口，保持组件职责单一

Limitations

局限性

Currently SPA-only (SSR coming soon)
No hydration support yet
Tracked objects cannot be created at module/global scope

目前仅支持单页应用（SSR功能即将推出）
暂不支持水合（hydration）功能
无法在模块/全局作用域创建Tracked对象