# Technical Documentation: Ripple-TS/ripple

> ℹ️ **Provenance:** Hybrid Fusion: `Ripple-TS/ripple` (README + 10 In-Tree Chapters) · [CodeWiki Reference](https://codewiki.google/github.com/Ripple-TS/ripple) · Recency: Active (< 180 days)

## 1. Project Overview & Quickstart (Ripple-TS/ripple)

<a href="https://www.ripple-ts.com">
  
    
    
  
</a>

[](https://github.com/Ripple-TS/ripple/actions/workflows/ci.yml)
[](https://discord.gg/JBF2ySrh2W)
[](https://stackblitz.com/github/Ripple-TS/ripple/tree/main/templates/basic)

# Ripple TS

Ripple is a TypeScript-first UI framework built around `.tsrx` files, fine-grained
reactivity, scoped styles, and a small runtime. It pairs the authoring feel of JSX
with template-native control flow and TypeScript setup that can live right beside
the UI it feeds.

Created by [@trueadm](https://github.com/trueadm), who has contributed to
[Inferno](https://github.com/infernojs/inferno),
[React](https://github.com/facebook/react),
[Lexical](https://github.com/facebook/lexical), and
[Svelte 5](https://github.com/sveltejs/svelte).

> `.tsrx` is also a standalone language. The shared TSRX compiler stack can target
> React, Preact, Solid, Vue, and Ripple. Ripple is the runtime-focused target with
> `track()`, reactive collections, server modules, hydration, and DOM helpers.

**[Ripple Docs](https://www.ripple-ts.com/docs)** |
**[Ripple Playground](https://www.ripple-ts.com/playground)** |
**[TSRX Website](https://tsrx.dev)**

## Features

- Fine-grained reactivity with `track()` and lazy destructuring.
- Reactive `RippleArray`, `RippleObject`, `RippleMap`, and `RippleSet`.
- Template-native `@if`, `@for`, `@switch`, and `@try`.
- Local TypeScript setup with JSX statement containers (`@{...}`).
- Scoped `<style>` blocks with automatic class hashing.
- Vite, editor, Prettier, ESLint, SSR (buffered and streaming), and hydration
  support.

## Quick Start

### Using CLI

```bash
npx create-ripple
cd my-app
npm install
npm run dev
```

### Using Template

```bash
npx degit Ripple-TS/ripple/templates/basic my-app
cd my-app
npm install
npm run dev
```

### Add To Existing Project

```bash
npm install ripple @ripple-ts/vite-plugin
```

Use `npm`, `pnpm`, `yarn`, or `bun`, matching your project.

### Mounting

```ts
// index.ts
import { mount } from 'ripple';
import { App } from './App.tsrx';

mount(App, {
  props: { title: 'Hello world!' },
  target: document.getElementById('root'),
});
```

## Core Syntax

### Components

Components are ordinary TypeScript functions. Return a JSX element directly when
the component has one root, and use a JSX statement container (`@{...}`) when
setup statements or multiple rendered siblings belong next to the UI.

```tsx
type ButtonProps = {
  text: string;
  onClick: () => void;
};

export function Button({ text, onClick }: ButtonProps) {
  return {text};
}

export function App() {
  return  console.log('Clicked!')} />;
}
```

Fragments are still useful when the component really returns multiple siblings,
such as markup plus a scoped `<style>` block.

### Local TypeScript

Plain JSX children are text, elements, comments, and `{...}` expression
containers. When a scope needs TypeScript setup before rendering, use a JSX
statement container: `@{...}`. Setup comes first and the container finishes with
exactly one output node: a JSX element, JSX fragment, or JSX control-flow
expression. If the output needs text, expression containers, or multiple siblings
after setup, wrap them in a fragment.

Text such as `x = 123` between tags is JSX text, not JavaScript, unless it is
inside a statement container.

```tsx
import { track } from 'ripple';

export function Counter() @{
  let &[count] = track(0);
  const increment = () => count++;

  Count:{count}
}
```

The same rule applies in nested scopes:

```tsx
export function Cart({ items }: { items: Item[] }) @{
  @{
    const subtotal = items.reduce((sum, item) => sum + item.price, 0);
    const discount =
      subtotal > 100 ? 0.1 : 0;

    <>
      Subtotal: ${subtotal}
      Save: ${(subtotal * discount).toFixed(2)}
    </>
  }
}
```

JavaScript comments are allowed between template children and are not rendered.

### Text And Expressions

Static text is JSX text. Dynamic values use normal JSX expression containers.

```tsx
export function Greeting({ name }: { name?: string }) @{
  @if (name) {
    Hello,{name}
  } @else {
    Hello, stranger
  }
}
```

### Control Flow

Rendered control flow uses directive-prefixed expressions:

```tsx
import { RippleArray, track } from 'ripple';

type Item = { id: number; name: string; done?: boolean };

export function TodoList() @{
  const items = new RippleArray({ id: 1, name: 'Plan the work' }, {
    id: 2,
    name: 'Ship the work',
  });
  let &[showDone] = track(true);
  const visibleItems = () => items.filter((item) => showDone || !item.done);

  
    @for (const item of visibleItems(); index i; key item.id) {
      <li>
        {i + 1}
        .
        {item.name}
      </li>
    } @empty {
      <li>No todos to show</li>
    }
  
}
```

Use ordinary `return` for real function exits in TypeScript setup. Use `@if` for
conditional rendering; direct `return`, `continue`, and `break` statements are not
valid inside `@if` template branches.

```tsx
export function Dashboard({ user }: { user: User | null }) @{
  if (!user) {
    return null;
  }

  <>
    <h1>Welcome,{user.name}</h1>
    Here is your dashboard.
  </>
}
```

`@try` supports error and pending UI:

```tsx
export function ProfilePanel() @{
  @try {
    
  } @pending {
    Loading...
  } @catch (error, reset) {
    
      Error:{error.message}
       reset()}>Try again
    
  }
}
```

### Reactivity

Create state with `track()` and lazy destructuring. Reads of lazy bindings stay
reactive, and assignments write back to the tracked value.

```tsx
import { effect, track, type Tracked } from 'ripple';

export function Counter() @{
  let &[count, trackedCount] = track(0);
  let &[double] = track(() => count * 2);
  effect(() => {
    console.log('Count changed:', count);
  });

  <>
    Count:{count}
    Double:{double}
     count++}>Increment
    <CounterValue count={trackedCount} />
  </>
}

function CounterValue({ count }: { count: Tracked<number> }) {
  return Shared value:{count.value};
}
```

`Tracked<T>` objects can also be read and written through `.value`, which is
useful when passing reactive values through data structures or props.

### Reactive Collections

Use Ripple collections when collection operations should be reactive.

```tsx
import { RippleArray, RippleMap, RippleObject, RippleSet } from 'ripple';

export function Inventory() @{
  const items = new RippleArray({ id: 1, name: 'Jacket' });
  const totals = new RippleObject({ selected: 0 });
  const prices = new RippleMap([[1, 120]]);
  const selected = new RippleSet<number>();

  <>
    
      @for (const item of items; key item.id) {
        <li>{item.name}: ${prices.get(item.id)}</li>
      }
    
     selected.add(1)}>Select first item
    
      Selected:
      {selected.size + totals.selected}
    
  </>
}
```

### DOM Refs And Events

DOM refs use `ref`, and events use JSX-style event props.

```tsx
import { track } from 'ripple';

export function SearchBox() @{
  let &[value] = track('');
  let input: HTMLInputElement | undefined;

  <>
    <label>
      Search
       {
          value = event.currentTarget.value;
        }}
      />
    </label>
     input?.focus()}>Focus
  </>
}
```

### Scoped Styles

`<style>` blocks are static CSS and are scoped to the template. Use CSS custom
properties for runtime values.

```tsx
import { track } from 'ripple';

export function Notice() @{
  let &[tone] = track('rebeccapurple');

  <>
    Scoped text
     (tone = tone === 'rebeccapurple'
        ? 'tomato'
        : 'rebeccapurple')}
    >Toggle tone
    <style>
      .notice {
        color: var(--notice-color);
        font-weight: 700;
      }
    </style>
  </>
}
```

Module-scope style expressions can expose scoped class names:

```tsx
const styles = <style>
  .highlight {
    background: #e8f5e9;
  }
</style>;

export function Badge() {
  return New;
}
```

### Context And Portals

```tsx
import { Context, Portal, track, type Tracked } from 'ripple';

const ThemeContext = new Context>();

export function App() @{
  let &[theme, themeTracked] = track('light');
  ThemeContext.set(themeTracked);

  <>
    
     (theme = theme === 'light' ? 'dark' : 'light')}>
      Toggle theme
    
    
      Portal content
    
  </>
}

function ThemeLabel() @{
  const theme = ThemeContext.get();

  Theme:{theme.value}
}
```

### Server Modules

Ripple supports `module server` in `.tsrx` files for server-oriented exports.
Import from `server` inside the same file before calling the server function.

```tsx
module server {
  export async function loadMessage() {
    return 'Loaded on the server';
  }
}

import { loadMessage } from server;
import { effect, track } from 'ripple';

export function Page() @{
  let &[message] = track('Loading...');
  effect(() => {
    loadMessage().then((next) => {
      message = next;
    });
  });

  {message}
}
```

## Editor Support

Install the
[Ripple VSCode extension](https://marketplace.visualstudio.com/items?itemName=Ripple-TS.ripple-ts-vscode-plugin)
for syntax highlighting, diagnostics, TypeScript integration, and completions.

## Resources

- [Full Documentation](https://www.ripple-ts.com/docs)
- [Interactive Playground](https://www.ripple-ts.com/playground)
- [TSRX Website](https://tsrx.dev)
- [GitHub Issues](https://github.com/Ripple-TS/ripple/issues)
- [Discord Community](https://discord.gg/JBF2ySrh2W)
- [npm Package](https://www.npmjs.com/package/ripple)

## Contributing

Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT License - see [LICENSE](LICENSE) for details.

## 2. In-Tree Documentation Chapters (Ripple-TS/ripple)

## File: README.md

<a href="https://www.ripple-ts.com">
  
    
    
  
</a>

[](https://github.com/Ripple-TS/ripple/actions/workflows/ci.yml)
[](https://discord.gg/JBF2ySrh2W)
[](https://stackblitz.com/github/Ripple-TS/ripple/tree/main/templates/basic)

# Ripple TS

Ripple is a TypeScript-first UI framework built around `.tsrx` files, fine-grained
reactivity, scoped styles, and a small runtime. It pairs the authoring feel of JSX
with template-native control flow and TypeScript setup that can live right beside
the UI it feeds.

Created by [@trueadm](https://github.com/trueadm), who has contributed to
[Inferno](https://github.com/infernojs/inferno),
[React](https://github.com/facebook/react),
[Lexical](https://github.com/facebook/lexical), and
[Svelte 5](https://github.com/sveltejs/svelte).

> `.tsrx` is also a standalone language. The shared TSRX compiler stack can target
> React, Preact, Solid, Vue, and Ripple. Ripple is the runtime-focused target with
> `track()`, reactive collections, server modules, hydration, and DOM helpers.

**[Ripple Docs](https://www.ripple-ts.com/docs)** |
**[Ripple Playground](https://www.ripple-ts.com/playground)** |
**[TSRX Website](https://tsrx.dev)**

## Features

- Fine-grained reactivity with `track()` and lazy destructuring.
- Reactive `RippleArray`, `RippleObject`, `RippleMap`, and `RippleSet`.
- Template-native `@if`, `@for`, `@switch`, and `@try`.
- Local TypeScript setup with JSX statement containers (`@{...}`).
- Scoped `<style>` blocks with automatic class hashing.
- Vite, editor, Prettier, ESLint, SSR (buffered and streaming), and hydration
  support.

## Quick Start

### Using CLI

```bash
npx create-ripple
cd my-app
npm install
npm run dev
```

### Using Template

```bash
npx degit Ripple-TS/ripple/templates/basic my-app
cd my-app
npm install
npm run dev
```

### Add To Existing Project

```bash
npm install ripple @ripple-ts/vite-plugin
```

Use `npm`, `pnpm`, `yarn`, or `bun`, matching your project.

### Mounting

```ts
// index.ts
import { mount } from 'ripple';
import { App } from './App.tsrx';

mount(App, {
  props: { title: 'Hello world!' },
  target: document.getElementById('root'),
});
```

## Core Syntax

### Components

Components are ordinary TypeScript functions. Return a JSX element directly when
the component has one root, and use a JSX statement container (`@{...}`) when
setup statements or multiple rendered siblings belong next to the UI.

```tsx
type ButtonProps = {
  text: string;
  onClick: () => void;
};

export function Button({ text, onClick }: ButtonProps) {
  return {text};
}

export function App() {
  return  console.log('Clicked!')} />;
}
```

Fragments are still useful when the component really returns multiple siblings,
such as markup plus a scoped `<style>` block.

### Local TypeScript

Plain JSX children are text, elements, comments, and `{...}` expression
containers. When a scope needs TypeScript setup before rendering, use a JSX
statement container: `@{...}`. Setup comes first and the container finishes with
exactly one output node: a JSX element, JSX fragment, or JSX control-flow
expression. If the output needs text, expression containers, or multiple siblings
after setup, wrap them in a fragment.

Text such as `x = 123` between tags is JSX text, not JavaScript, unless it is
inside a statement container.

```tsx
import { track } from 'ripple';

export function Counter() @{
  let &[count] = track(0);
  const increment = () => count++;

  Count:{count}
}
```

The same rule applies in nested scopes:

```tsx
export function Cart({ items }: { items: Item[] }) @{
  @{
    const subtotal = items.reduce((sum, item) => sum + item.price, 0);
    const discount =
      subtotal > 100 ? 0.1 : 0;

    <>
      Subtotal: ${subtotal}
      Save: ${(subtotal * discount).toFixed(2)}
    </>
  }
}
```

JavaScript comments are allowed between template children and are not rendered.

### Text And Expressions

Static text is JSX text. Dynamic values use normal JSX expression containers.

```tsx
export function Greeting({ name }: { name?: string }) @{
  @if (name) {
    Hello,{name}
  } @else {
    Hello, stranger
  }
}
```

### Control Flow

Rendered control flow uses directive-prefixed expressions:

```tsx
import { RippleArray, track } from 'ripple';

type Item = { id: number; name: string; done?: boolean };

export function TodoList() @{
  const items = new RippleArray({ id: 1, name: 'Plan the work' }, {
    id: 2,
    name: 'Ship the work',
  });
  let &[showDone] = track(true);
  const visibleItems = () => items.filter((item) => showDone || !item.done);

  
    @for (const item of visibleItems(); index i; key item.id) {
      <li>
        {i + 1}
        .
        {item.name}
      </li>
    } @empty {
      <li>No todos to show</li>
    }
  
}
```

Use ordinary `return` for real function exits in TypeScript setup. Use `@if` for
conditional rendering; direct `return`, `continue`, and `break` statements are not
valid inside `@if` template branches.

```tsx
export function Dashboard({ user }: { user: User | null }) @{
  if (!user) {
    return null;
  }

  <>
    <h1>Welcome,{user.name}</h1>
    Here is your dashboard.
  </>
}
```

`@try` supports error and pending UI:

```tsx
export function ProfilePanel() @{
  @try {
    
  } @pending {
    Loading...
  } @catch (error, reset) {
    
      Error:{error.message}
       reset()}>Try again
    
  }
}
```

### Reactivity

Create state with `track()` and lazy destructuring. Reads of lazy bindings stay
reactive, and assignments write back to the tracked value.

```tsx
import { effect, track, type Tracked } from 'ripple';

export function Counter() @{
  let &[count, trackedCount] = track(0);
  let &[double] = track(() => count * 2);
  effect(() => {
    console.log('Count changed:', count);
  });

  <>
    Count:{count}
    Double:{double}
     count++}>Increment
    <CounterValue count={trackedCount} />
  </>
}

function CounterValue({ count }: { count: Tracked<number> }) {
  return Shared value:{count.value};
}
```

`Tracked<T>` objects can also be read and written through `.value`, which is
useful when passing reactive values through data structures or props.

### Reactive Collections

Use Ripple collections when collection operations should be reactive.

```tsx
import { RippleArray, RippleMap, RippleObject, RippleSet } from 'ripple';

export function Inventory() @{
  const items = new RippleArray({ id: 1, name: 'Jacket' });
  const totals = new RippleObject({ selected: 0 });
  const prices = new RippleMap([[1, 120]]);
  const selected = new RippleSet<number>();

  <>
    
      @for (const item of items; key item.id) {
        <li>{item.name}: ${prices.get(item.id)}</li>
      }
    
     selected.add(1)}>Select first item
    
      Selected:
      {selected.size + totals.selected}
    
  </>
}
```

### DOM Refs And Events

DOM refs use `ref`, and events use JSX-style event props.

```tsx
import { track } from 'ripple';

export function SearchBox() @{
  let &[value] = track('');
  let input: HTMLInputElement | undefined;

  <>
    <label>
      Search
       {
          value = event.currentTarget.value;
        }}
      />
    </label>
     input?.focus()}>Focus
  </>
}
```

### Scoped Styles

`<style>` blocks are static CSS and are scoped to the template. Use CSS custom
properties for runtime values.

```tsx
import { track } from 'ripple';

export function Notice() @{
  let &[tone] = track('rebeccapurple');

  <>
    Scoped text
     (tone = tone === 'rebeccapurple'
        ? 'tomato'
        : 'rebeccapurple')}
    >Toggle tone
    <style>
      .notice {
        color: var(--notice-color);
        font-weight: 700;
      }
    </style>
  </>
}
```

Module-scope style expressions can expose scoped class names:

```tsx
const styles = <style>
  .highlight {
    background: #e8f5e9;
  }
</style>;

export function Badge() {
  return New;
}
```

### Context And Portals

```tsx
import { Context, Portal, track, type Tracked } from 'ripple';

const ThemeContext = new Context>();

export function App() @{
  let &[theme, themeTracked] = track('light');
  ThemeContext.set(themeTracked);

  <>
    
     (theme = theme === 'light' ? 'dark' : 'light')}>
      Toggle theme
    
    
      Portal content
    
  </>
}

function ThemeLabel() @{
  const theme = ThemeContext.get();

  Theme:{theme.value}
}
```

### Server Modules

Ripple supports `module server` in `.tsrx` files for server-oriented exports.
Import from `server` inside the same file before calling the server function.

```tsx
module server {
  export async function loadMessage() {
    return 'Loaded on the server';
  }
}

import { loadMessage } from server;
import { effect, track } from 'ripple';

export function Page() @{
  let &[message] = track('Loading...');
  effect(() => {
    loadMessage().then((next) => {
      message = next;
    });
  });

  {message}
}
```

## Editor Support

Install the
[Ripple VSCode extension](https://marketplace.visualstudio.com/items?itemName=Ripple-TS.ripple-ts-vscode-plugin)
for syntax highlighting, diagnostics, TypeScript integration, and completions.

## Resources

- [Full Documentation](https://www.ripple-ts.com/docs)
- [Interactive Playground](https://www.ripple-ts.com/playground)
- [TSRX Website](https://tsrx.dev)
- [GitHub Issues](https://github.com/Ripple-TS/ripple/issues)
- [Discord Community](https://discord.gg/JBF2ySrh2W)
- [npm Package](https://www.npmjs.com/package/ripple)

## Contributing

Contributions are welcome. Please see [CONTRIBUTING.md](CONTRIBUTING.md).

## License

MIT License - see [LICENSE](LICENSE) for details.

---

## File: .changeset/README.md

# Changesets

Hello and welcome! This folder has been automatically generated by
`@changesets/cli`, a build tool that works with multi-package repos, or
single-package repos to help you version and publish your code. You can find the
full documentation for it
[in our repository](https://github.com/changesets/changesets)

We have a quick list of common questions to get you started engaging with this
project in
[our documentation](https://github.com/changesets/changesets/blob/main/docs/common-questions.md)

---

## File: assets/Ripple.tmbundle/README.md

This provides syntax highlighting for Ripple files in editors that support
TextMate grammars, such as WebStorm/IntelliJ and Sublime Text.

# Installation

1. Create a directory named `Ripple.tmbundle`.
2. Create a directory named `Syntaxes` inside the `Ripple.tmbundle` directory.
3. Save the [`ripple.tmLanguage`](./Syntaxes/ripple.tmLanguage) file into the
   `Syntaxes` directory.
4. Install it:
   - **WebStorm/IntelliJ**:
     1. Save the [`info.plist`](./info.plist) file into the `Ripple.tmbundle`
        directory.
     2. Go to `Settings` > `Editor` > `TextMate Bundles`, click the `+` icon, and
        select the `Ripple.tmbundle` directory.
     3. All `.tsrx` files should now have syntax highlighting.
   - **Sublime Text**:
     1. Go to `Preferences` > `Browse Packages`, and move the `Ripple.tmbundle`
        directory into the opened folder.
     2. You should now be able to select `Ripple` in `View` > `Syntax`.

---

## File: grammars/tree-sitter/README.md

# @ripple-ts/tree-sitter

Tree-sitter grammar for [Ripple](https://www.ripple-ts.com).

## Overview

Ripple is a JS/TS-first UI framework that extends TypeScript with native TSRX
markup syntax and reactive primitives. This Tree-sitter grammar provides parsing
support for it.

---

## File: packages/zed-plugin/README.md

# TSRX Extension for Zed

This extension provides TSRX language support for the
[Zed editor](https://zed.dev). TSRX is a TypeScript superset that compiles to
Ripple, React, Solid, and Preact. Handles `.tsrx` files.

## Installation

### From Zed Extensions

Once published to the Zed extensions registry:

1. Open Zed
2. Press `Cmd/Ctrl + Shift + X` to open extensions
3. Search for "TSRX"
4. Click "Install"

### Development Installation

1. Clone this repository
2. Install Rust with the wasm32-wasip1 target:
   ```bash
   rustup target add wasm32-wasip1
   ```
3. Open Zed
4. Press `Cmd/Ctrl + Shift + P`
5. Run "zed: install dev extension"
6. Select the `packages/zed-plugin` directory

## Language Server Setup

The extension looks for the language server `@ripple-ts/language-server` in this
order:

1. The local project that you have opened in Zed via the `package.json` and looks
   for `node_modules/.bin/ripple-language-server`. So make sure to install your
   dependencies first via:

   ```bash
   npm install
   ```

2. Globally installed:

   ```bash
   npm install @ripple-ts/language-server
   ```

3. The extension automatically downloads the Ripple Language Server the first time
   it runs. The version is pinned via the `config` entry for
   `@ripple-ts/language-server` in this package's `package.json`.

Project-local installations (`node_modules/.bin/ripple-language-server`) are also
detected automatically.

---

## File: packages/vscode-plugin/README.md

# Ripple for VS Code

Provides syntax highlighting and rich intellisense for `.tsrx` files in VS Code,
using the Ripple language server.

---

## File: packages/typescript-plugin/README.md

# @tsrx/typescript-plugin

[](https://www.npmjs.com/package/@tsrx/typescript-plugin)
[](https://www.npmjs.com/package/@tsrx/typescript-plugin)

TypeScript plugin for Ripple that provides language support for `.tsrx` files.

## Usage

### VS Code

**If you're using VS Code with the Ripple extension, you don't need to configure
this plugin!** The Ripple language server handles everything automatically.

### Other Editors or Standalone Usage

For editors that don't use the Ripple language server (like WebStorm, Sublime
Text, or command-line `tsc`), add this plugin to your `tsconfig.json`:

```json
{
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "ripple",
    "plugins": [
      {
        "name": "@tsrx/typescript-plugin"
      }
    ]
  }
}
```

## Compiler selection

All TSRX targets use the `.tsrx` extension. Normally, the compiler is detected
automatically from the installed target packages and the nearest `package.json`.
To remove ambiguity when multiple target compilers are installed, or to use a
third-party compiler, select one explicitly with the top-level `tsrx.compiler`
option:

```json
{
  "tsrx": {
    "compiler": "@tsrx/ripple"
  },
  "compilerOptions": {
    "jsx": "preserve",
    "jsxImportSource": "ripple",
    "plugins": [
      {
        "name": "@tsrx/typescript-plugin"
      }
    ]
  }
}
```

`compiler` must be a bare package specifier, such as `@tsrx/ripple`,
`@tsrx/react`, `@tsrx/solid`, `@tsrx/preact`, `@tsrx/vue`, `octane`, or a
third-party TSRX compiler package. Package subpaths are supported; relative and
absolute paths are not.

Compiler declarations follow the active TypeScript project's explicit `tsconfig`
inheritance graph:

- `extends` chains, arrays, JSONC files, and package-based configs are supported.
- Base configs are applied first. Child configs and later `extends` entries take
  precedence.
- The compiler package is resolved relative to the config that supplied the
  effective declaration.
- Nested projects do not inherit from unrelated ancestor configs.
- An invalid or unresolved effective declaration prevents automatic fallback. A
  valid declaration in a child config still overrides a failed lower-priority
  base.

The language server, tsserver plugin, and `tsrx-tsc` use the TypeScript project's
selected config. When that project context is unavailable, resolution starts at
the nearest `tsconfig.json`. If no `tsrx.compiler` value is declared, the plugin
falls back to installed target detection, using the nearest `package.json` to
disambiguate when multiple supported compiler packages are present.

## What it does

This plugin:

- Registers `.tsrx` files as recognized TypeScript languages
- Transforms Ripple syntax to TypeScript for type checking
- Integrates with Volar for virtual code generation and source mapping

## Architecture Note

This plugin uses Volar's TypeScript plugin system. When configured in
`tsconfig.json`, TypeScript's tsserver will load this plugin and create a language
service instance.

The Ripple VS Code extension uses a language server instead, which provides the
same functionality plus additional features like diagnostics and formatting. Both
can coexist (they create separate instances), but you only need one.

---

## File: packages/ripple/README.md

# What is Ripple?

[](https://www.npmjs.com/package/ripple)
[](https://www.npmjs.com/package/ripple)

Ripple is an elegant TypeScript UI framework. To find out more, view
[Ripple's Github README](https://github.com/Ripple-TS/ripple).

---

## File: packages/prettier-plugin/README.md

# @tsrx/prettier-plugin

[](https://www.npmjs.com/package/@tsrx/prettier-plugin)
[](https://www.npmjs.com/package/@tsrx/prettier-plugin)

A Prettier plugin for formatting [TSRX](https://tsrx.dev) files, with `.tsrx` as
the default extension.

---

## File: packages/nvim-plugin/README.md

# Ripple Neovim Plugin

Neovim integration for the [Ripple](https://github.com/trueadm/ripple) language.

## Requirements

- Neovim 0.11 or newer
- [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter)
- Node.js v18 or newer

## Installation


with lazy.nvim

```lua
{
  "Ripple-TS/ripple",
  config = function(plugin)
    vim.opt.rtp:append(plugin.dir .. "/packages/nvim-plugin")
    require("ripple").setup(plugin)
  end
}
```



If you're using another plugin manager and wish to share installation
instructions, please consider opening a PR.

### Tree-sitter

`require("ripple").setup()` registers the Ripple parser with `nvim-treesitter` and
points it at the bundled grammar source:

- Repository: `https://github.com/trueadm/ripple`
- Subdirectory: `grammars/tree-sitter`
- Files: `src/parser.c`, `src/scanner.c`

--- METRICS ---
- Files Extracted: 11
- Estimated Token Budget: ~6897 tokens
- Recency Window: Active (< 180 days)
- Canonical Reference: https://codewiki.google/github.com/Ripple-TS/ripple