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!

🚀 Quick Start

Installation

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

<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:

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:

<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:

<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:

<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 - Comprehensive guides and API reference
• Examples - Live demos and code samples
• Migration Guide - Upgrading from previous versions

🔧 Advanced Usage

Custom Extensions

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.

<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:

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 for detailed information.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Tiptap - The headless editor framework
• UI components inspired by shadcn/ui
• Icons by Lucide

⭐ Star us on GitHub 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.