---
name: ripple
description: Work with Ripple TS framework projects. Use when working with .ripple files or projects using the ripple or @ripple-ts/* packages.
---

# Ripple TS Framework Skill

Use this skill when working on Ripple TS projects. Ripple is a TypeScript UI framework combining the best parts of React, Solid, and Svelte.

## Activation

This skill activates when:
- Working with `.ripple` files
- User mentions "Ripple" in the context of a UI framework
- Project uses `ripple` or `@ripple-ts/*` packages

## Documentation Reference

**Always fetch the latest documentation before providing Ripple-specific guidance:**

```
https://www.ripple-ts.com/llms.txt
```

Use the `fetch_content` tool to retrieve this URL. The documentation is optimized for AI/LLM understanding and may be updated with new features and syntax changes.

## Quick Reference

### Key Syntax Patterns

- **Components**: Use `component` keyword (not functions returning JSX)
- **Text content**: Must be wrapped in expressions `{"text"}` - no raw text in templates
- **Reactivity**: Use `track()` to create reactive values, `@` to read/write them
- **Templates**: Only valid inside `component` function bodies
- **Early returns**: Use `return;` (no value) for guard clauses only

### Common Imports

```typescript
import { mount, track, effect, Context, untrack, flushSync, tick } from 'ripple';
import { TrackedArray, TrackedObject, TrackedSet, TrackedMap, TrackedDate } from 'ripple';
import type { Component, PropsWithChildren, Tracked } from 'ripple';
```

### Critical Mistakes to Avoid

1. **Raw text in templates** - Always use `{"text"}` not `text`
2. **Return statements with values** - Use `return;` only, no `return <JSX/>`
3. **Templates outside components** - JSX only valid inside `component {}` bodies
4. **Destructuring props without trackSplit** - Loses reactivity for non-tracked props

## When to Fetch Full Docs

Fetch the full documentation when:
- Implementing complex reactive patterns
- Using Context API
- Setting up SSR/hydration
- Integrating with React (compat layer)
- Working with reactive collections (TrackedArray, TrackedMap, etc.)
- Using control flow (switch statements, for loops with keys)
- Implementing portals or refs