npm package: @nocsi/recurse
Description: Best Rich Text Editor, made for Svelte Developers with Tiptap
Author: nocsi
Latest version: 1.1.1

# Recurse

[![npm version](https://img.shields.io/npm/v/%40nocsi%2Frecurse.svg)](https://www.npmjs.com/package/@nocsi/recurse)
[![CI](https://github.com/nocsi/recurse/actions/workflows/ci.yml/badge.svg)](https://github.com/nocsi/recurse/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Svelte](https://img.shields.io/badge/Svelte-5.0+-orange.svg)](https://svelte.dev/)
[![GitHub stars](https://img.shields.io/github/stars/nocsi/recurse?style=social)](https://github.com/nocsi/recurse)

![waka-api](https://waka-api.dev-nocsi.workers.dev/Recurse)

> **Best Rich Text Editor for Svelte Developers** - Built with Tiptap, designed for modern Svelte applications

Recurse (formerly Edra) is a powerful, extensible rich text editor built specifically for Svelte developers. It combines the robust editing capabilities of Tiptap with beautiful, customizable UI components that integrate seamlessly into your Svelte projects.

**✨ Now fully portable** - Works with or without SvelteKit!

<img width="1023" alt="Screenshot 2025-06-03 at 1 13 31 PM" src="https://github.com/user-attachments/assets/b85e6e3f-28a4-439e-91ed-bc7fc9fddcc2" />

## 🚀 Quick Start

### Installation

```bash
pnpm add @nocsi/recurse
# or
npm install @nocsi/recurse
# or
yarn add @nocsi/recurse
# or
bun add @nocsi/recurse
```

Note: This repository uses pnpm and includes a `pnpm-lock.yaml`. Prefer pnpm for installs and scripts to avoid lockfile and peer-dependency mismatches. See `AGENTS.md` for details.

### Basic Usage

```svelte
<script>
	import { ShadcnEditor, ShadcnToolBar } from '@nocsi/recurse';
	import { Editor } from '@tiptap/core';

	let editor = $state();
	let content = $state();
</script>

<ShadcnToolBar bind:editor />
<ShadcnEditor bind:editor bind:content />
```

### CLI Setup (Alternative)

For a more integrated setup experience:

```bash
pnpm dlx @nocsi/recurse init shadcn    # For styled components
# or
pnpm dlx @nocsi/recurse init headless  # For unstyled components
```

### Development

- Dev server: Vite runs on port `5180` by default (configured in `vite.config.ts`).
- Start dev: `pnpm dev` (or `pnpm dev -- --port 5180`)
- Preview build: `pnpm preview` (also uses port `5180`)

### Examples & Demo Mode

- Examples are always available and run in demo/no‑network mode by default. The demo provider streams locally and never calls external APIs.
- To enable real providers (OpenAI, Anthropic, Gemini) in your own app, set `demoMode={false}` on `AIChatPanel` and pass your API key and model in `initialConfig`:

```svelte
<AIChatPanel
	demoMode={false}
	initialConfig={{
		provider: 'gemini',
		model: 'gemini-1.5-flash',
		apiKey: import.meta.env.VITE_GEMINI_API_KEY
	}}
/>
```

- A project‑wide toggle is also available at `src/lib/config.ts` (`export const demoMode = true`). You can flip it to control demo behavior across examples.

## 🎯 Key Features

### 📝 Rich Text Editing

- **Markdown shortcuts** - Type naturally with markdown syntax
- **Complete formatting** - Bold, italic, underline, strikethrough, superscript, subscript
- **Advanced typography** - Emojis, special characters, and visual enhancements
- **Custom styling** - Text colors, highlights, and font size controls

### 🎨 Media & Content

- **Tables** - Full-featured tables with merge, split, and styling options
- **Images** - Upload, resize, align, and caption images
- **Videos & Audio** - Embed and control multimedia content
- **Code blocks** - Syntax highlighting with 100+ languages and themes
- **Math & LaTeX** - Mathematical expressions and equations

### ⚡ Productivity Features

- **Slash commands** - Quick content insertion with `/` commands
- **Drag & drop** - Intuitive content reorganization
- **Search & replace** - Find and replace text across documents
- **Bubble menus** - Context-sensitive editing tools
- **Auto-save** - Never lose your work

### 🛠 Developer Experience

- **TypeScript support** - Full type safety and IntelliSense
- **Headless architecture** - Bring your own styles or use our components
- **Plugin system** - Extend functionality with custom extensions
- **Performance optimized** - Efficient rendering and memory management

## 🎨 UI Options

Choose the UI approach that best fits your project:

### Headless Components

Perfect for custom designs and complete styling control:

```svelte
<script>
	import { HeadlessEditor, HeadlessToolBar, HeadlessEditorHeader } from '@nocsi/recurse';
</script>

<HeadlessEditorHeader />
<HeadlessToolBar bind:editor />
<HeadlessEditor bind:editor bind:content />
```

### Shadcn/UI Components

Beautiful, pre-styled components built with Tailwind CSS:

```svelte
<script>
	import {
		ShadcnEditor,
		ShadcnToolBar,
		ShadcnBubbleMenu,
		ShadcnEditorHeader
	} from '@nocsi/recurse';
</script>

<ShadcnEditorHeader />
<ShadcnToolBar bind:editor />
<ShadcnEditor bind:editor bind:content />
<ShadcnBubbleMenu bind:editor />
```

## 📚 Documentation

- **[Complete Documentation](https://recurse.nulity.com/docs)** - Comprehensive guides and API reference
- **[Examples](https://recurse.nulity.com/examples)** - Live demos and code samples
- **[Migration Guide](https://recurse.nulity.com/docs/migration)** - Upgrading from previous versions

## 🔧 Advanced Usage

### Custom Extensions

```javascript
import { createEditor } from '@nocsi/recurse';
import { MyCustomExtension } from './my-extension';

const editor = createEditor({
	extensions: [MyCustomExtension],
	content: '<p>Hello world!</p>'
});
```

### Typography Utility

Animated, product-aware typography with math-like symbol transforms.

```svelte
<script>
	import { Typography } from '@nocsi/recurse';
</script>

<!-- Basic: transform code-like tokens into symbols -->
<Typography text="a -> b, x <= y, z != w" />

<!-- Product-specific rendering + animation -->
<Typography text="[[ block ]] :: pipe |>" product="recurse" animate />
```

### Environment Detection

Recurse includes portable environment utilities:

```javascript
import { browser, dev, version } from '@nocsi/recurse';

if (browser) {
	// Browser-specific code
}

if (dev) {
	// Development-only features
}
```

## 🤝 Contributing

We welcome contributions! Here's how to get started:

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Make your changes** and add tests
4. **Run the test suite**: `npm test`
5. **Submit a pull request**

Please read our [Contributing Guidelines](CONTRIBUTING.md) for detailed information.

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- Built with [Tiptap](https://tiptap.dev/) - The headless editor framework
- UI components inspired by [shadcn/ui](https://ui.shadcn.com/)
- Icons by [Lucide](https://lucide.dev/)

---

**[⭐ Star us on GitHub](https://github.com/nocsi/recurse)** if you find Recurse useful!

## Releasing

There are two supported ways to publish a new version.

### CI (Recommended)

- Prepare version: update `package.json` (e.g., `1.0.1`).
- Tag the version: `git tag v1.0.1 && git push origin v1.0.1`.
- Configure once: add `NPM_TOKEN` repo secret (npm automation token).
- The GitHub Actions Release workflow builds, tests, and publishes automatically.

### Manual (Local)

- Login: `npm login` (or `pnpm login`).
- Build & test: `pnpm build && pnpm test`.
- Publish: `pnpm publish --access public`.
- Tag (optional): `git tag vX.Y.Z && git push origin vX.Y.Z`.