npm package: @livewire-filemanager/tiptap
Description: TipTap extension to browse and insert files from Livewire Filemanager
Latest version: 1.0.0

# @livewire-filemanager/tiptap

TipTap extension for [Livewire Filemanager](https://github.com/livewire-filemanager/filemanager). Browse, search and insert files directly from your TipTap editor.

## Features

- Built-in file browser modal with folder navigation and search
- Image files inserted as `<img>` tags, other files as download links
- Keyboard shortcut `Ctrl+Shift+F` (or `Cmd+Shift+F` on macOS)
- 12 languages supported out of the box
- Fully typed (TypeScript)
- No dependencies beyond `@tiptap/core`

## Prerequisites

This package requires the [Livewire Filemanager](https://github.com/livewire-filemanager/filemanager) backend to be installed and its API routes to be enabled.

```bash
composer require livewire-filemanager/filemanager
php artisan vendor:publish --tag=livewire-filemanager-config
php artisan vendor:publish --tag=livewire-filemanager-migrations
php artisan migrate
```

Make sure the API is enabled in `config/livewire-filemanager.php`:

```php
'api' => [
    'enabled' => true,
    'prefix' => 'filemanager/v1',
    'middleware' => ['api', 'auth:sanctum'],
    // ...
],
```

> If using Sanctum SPA authentication, remember to call `$middleware->statefulApi()` in `bootstrap/app.php` and set `SANCTUM_STATEFUL_DOMAINS` in your `.env`.

## Installation

```bash
npm install @livewire-filemanager/tiptap @tiptap/core
```

For automatic image insertion, also install the Image extension:

```bash
npm install @tiptap/extension-image
```

## Usage

```js
import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import Image from '@tiptap/extension-image'
import { Filemanager } from '@livewire-filemanager/tiptap'

const editor = new Editor({
  element: document.getElementById('editor'),
  extensions: [
    StarterKit,
    Image,
    Filemanager.configure({
      apiUrl: '/api/filemanager/v1',
      lang: 'en',
    }),
  ],
})
```

### Opening the file manager

Use the keyboard shortcut `Ctrl+Shift+F`, or call the command programmatically:

```js
editor.commands.openFilemanager()
```

### Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiUrl` | `string` | `'/api/filemanager/v1'` | Base URL of the Filemanager API |
| `lang` | `SupportedLocale` | `'en'` | UI language (see supported locales below) |
| `onInsert` | `(files: FileItem[], editor: Editor) => void` | `undefined` | Custom insert callback. Overrides the default behavior |

### Custom insert behavior

By default, images are inserted as `<img>` tags and other files as `<a>` download links. You can override this:

```js
Filemanager.configure({
  onInsert: (files, editor) => {
    files.forEach(file => {
      editor.chain().focus().insertContent(`[${file.name}](${file.url})`).run()
    })
  },
})
```

### FileItem type

```ts
interface FileItem {
  id: number
  name: string
  file_name: string
  url: string
  thumbnail_url?: string
  mime_type: string
  size: number
}
```

## Supported locales

| Code | Language |
|------|----------|
| `en` | English |
| `fr` | French |
| `es` | Spanish |
| `ar` | Arabic |
| `fa` | Persian |
| `he` | Hebrew |
| `it` | Italian |
| `nl` | Dutch |
| `pt_BR` | Portuguese (Brazil) |
| `pt_PT` | Portuguese (Portugal) |
| `ro` | Romanian |
| `tr` | Turkish |

## License

MIT