tiptap/docs/installation/alpine.md

148 lines
4.8 KiB
Markdown
Raw Normal View History

---
title: Alpine WYSIWYG
2021-09-08 04:50:22 +08:00
tableOfContents: true
---
# Alpine.js
2021-01-30 05:05:47 +08:00
## Introduction
The following guide describes how to integrate Tiptap with version 3 of [Alpine.js](https://github.com/alpinejs/alpine).
2021-01-30 05:05:47 +08:00
For the sake of this guide well use [Vite](https://vitejs.dev/) to quickly set up a project, but you can use whatever youre used to. Vite is just really fast and we love it.
## Requirements
* [Node](https://nodejs.org/en/download/) installed on your machine
* Experience with [Alpine.js](https://github.com/alpinejs/alpine)
## 1. Create a project (optional)
If you already have an existing Alpine.js project, thats fine too. Just skip this step and proceed with the next step.
2021-11-09 18:56:27 +08:00
For the sake of this guide, lets start with a fresh [Vite](https://vitejs.dev/) project called `my-tiptap-project`. Vite sets up everything we need, just select the Vanilla JavaScript template.
```bash
2021-11-09 18:56:27 +08:00
npm init vite@latest my-tiptap-project -- --template vanilla
cd my-tiptap-project
npm install
2021-08-17 02:57:45 +08:00
npm run dev
```
## 2. Install the dependencies
2021-08-17 02:57:45 +08:00
Okay, enough of the boring boilerplate work. Lets finally install Tiptap! For the following example youll need `alpinejs`, the `@tiptap/core` package, the `@tiptap/pm` package and the `@tiptap/starter-kit`, which includes the most common extensions to get started quickly.
```bash
feat(pm): new prosemirror package for dependency resolving * chore:(core): migrate to tsup * chore: migrate blockquote and bold to tsup * chore: migrated bubble-menu and bullet-list to tsup * chore: migrated more packages to tsup * chore: migrate code and character extensions to tsup * chore: update package.json to simplify build for all packages * chore: move all packages to tsup as a build process * chore: change ci build task * feat(pm): add prosemirror meta package * rfix: resolve issues with build paths & export mappings * docs: update documentation to include notes for @tiptap/pm * chore(pm): update tsconfig * chore(packages): update packages * fix(pm): add package export infos & fix dependencies * chore(general): start moving to pm package as deps * chore: move to tiptap pm package internally * fix(demos): fix demos working with new pm package * fix(tables): fix tables package * fix(tables): fix tables package * chore(demos): pinned typescript version * chore: remove unnecessary tsconfig * chore: fix netlify build * fix(demos): fix package resolving for pm packages * fix(tests): fix package resolving for pm packages * fix(tests): fix package resolving for pm packages * chore(tests): fix tests not running correctly after pm package * chore(pm): add files to files array * chore: update build workflow * chore(tests): increase timeout time back to 12s * chore(docs): update docs * chore(docs): update installation guides & pm information to docs * chore(docs): add link to prosemirror docs * fix(vue-3): add missing build step * chore(docs): comment out cdn link * chore(docs): remove semicolons from docs * chore(docs): remove unnecessary installation note * chore(docs): remove unnecessary installation note
2023-02-03 00:37:33 +08:00
npm install alpinejs @tiptap/core @tiptap/pm @tiptap/starter-kit
```
If you followed step 1, you can now start your project with `npm run dev`, and open [http://localhost:5173](http://localhost:5173) in your favorite browser. This might be different, if youre working with an existing project.
2021-04-09 04:44:55 +08:00
## 3. Initialize the editor
2021-10-20 04:30:45 +08:00
To actually start using Tiptap, youll need to write a little bit of JavaScript. Lets put the following example code in a file called `main.js`.
2021-10-20 04:30:45 +08:00
This is the fastest way to get Tiptap up and running with Alpine.js. It will give you a very basic version of Tiptap. No worries, you will be able to add more functionality soon.
```js
2021-08-17 02:57:45 +08:00
import Alpine from 'alpinejs'
import { Editor } from '@tiptap/core'
2021-05-07 00:41:22 +08:00
import StarterKit from '@tiptap/starter-kit'
document.addEventListener('alpine:init', () => {
Alpine.data('editor', (content) => {
let editor // Alpine's reactive engine automatically wraps component properties in proxy objects. Attempting to use a proxied editor instance to apply a transaction will cause a "Range Error: Applying a mismatched transaction", so be sure to unwrap it using Alpine.raw(), or simply avoid storing your editor as a component property, as shown in this example.
return {
updatedAt: Date.now(), // force Alpine to rerender on selection change
init() {
const _this = this
editor = new Editor({
element: this.$refs.element,
extensions: [
StarterKit
],
content: content,
onCreate({ editor }) {
_this.updatedAt = Date.now()
},
onUpdate({ editor }) {
_this.updatedAt = Date.now()
},
onSelectionUpdate({ editor }) {
_this.updatedAt = Date.now()
}
feat(pm): new prosemirror package for dependency resolving * chore:(core): migrate to tsup * chore: migrate blockquote and bold to tsup * chore: migrated bubble-menu and bullet-list to tsup * chore: migrated more packages to tsup * chore: migrate code and character extensions to tsup * chore: update package.json to simplify build for all packages * chore: move all packages to tsup as a build process * chore: change ci build task * feat(pm): add prosemirror meta package * rfix: resolve issues with build paths & export mappings * docs: update documentation to include notes for @tiptap/pm * chore(pm): update tsconfig * chore(packages): update packages * fix(pm): add package export infos & fix dependencies * chore(general): start moving to pm package as deps * chore: move to tiptap pm package internally * fix(demos): fix demos working with new pm package * fix(tables): fix tables package * fix(tables): fix tables package * chore(demos): pinned typescript version * chore: remove unnecessary tsconfig * chore: fix netlify build * fix(demos): fix package resolving for pm packages * fix(tests): fix package resolving for pm packages * fix(tests): fix package resolving for pm packages * chore(tests): fix tests not running correctly after pm package * chore(pm): add files to files array * chore: update build workflow * chore(tests): increase timeout time back to 12s * chore(docs): update docs * chore(docs): update installation guides & pm information to docs * chore(docs): add link to prosemirror docs * fix(vue-3): add missing build step * chore(docs): comment out cdn link * chore(docs): remove semicolons from docs * chore(docs): remove unnecessary installation note * chore(docs): remove unnecessary installation note
2023-02-03 00:37:33 +08:00
})
},
isLoaded() {
return editor
},
isActive(type, opts = {}) {
return editor.isActive(type, opts)
},
toggleHeading(opts) {
editor.chain().toggleHeading(opts).focus().run()
},
toggleBold() {
editor.chain().toggleBold().focus().run()
},
toggleItalic() {
editor.chain().toggleItalic().focus().run()
},
feat(pm): new prosemirror package for dependency resolving * chore:(core): migrate to tsup * chore: migrate blockquote and bold to tsup * chore: migrated bubble-menu and bullet-list to tsup * chore: migrated more packages to tsup * chore: migrate code and character extensions to tsup * chore: update package.json to simplify build for all packages * chore: move all packages to tsup as a build process * chore: change ci build task * feat(pm): add prosemirror meta package * rfix: resolve issues with build paths & export mappings * docs: update documentation to include notes for @tiptap/pm * chore(pm): update tsconfig * chore(packages): update packages * fix(pm): add package export infos & fix dependencies * chore(general): start moving to pm package as deps * chore: move to tiptap pm package internally * fix(demos): fix demos working with new pm package * fix(tables): fix tables package * fix(tables): fix tables package * chore(demos): pinned typescript version * chore: remove unnecessary tsconfig * chore: fix netlify build * fix(demos): fix package resolving for pm packages * fix(tests): fix package resolving for pm packages * fix(tests): fix package resolving for pm packages * chore(tests): fix tests not running correctly after pm package * chore(pm): add files to files array * chore: update build workflow * chore(tests): increase timeout time back to 12s * chore(docs): update docs * chore(docs): update installation guides & pm information to docs * chore(docs): add link to prosemirror docs * fix(vue-3): add missing build step * chore(docs): comment out cdn link * chore(docs): remove semicolons from docs * chore(docs): remove unnecessary installation note * chore(docs): remove unnecessary installation note
2023-02-03 00:37:33 +08:00
}
})
})
2021-08-17 02:57:45 +08:00
window.Alpine = Alpine
Alpine.start()
```
## 4. Add it to your app
Now, lets replace the content of the `index.html` with the following example code to use the editor in our app.
```html
<!DOCTYPE html>
2021-04-09 04:12:46 +08:00
<html lang="en">
<head>
<meta charset="UTF-8">
</head>
<body>
<div x-data="editor('<p>Hello world! :-)</p>')">
2021-04-09 04:12:46 +08:00
<template x-if="isLoaded()">
2021-04-09 04:12:46 +08:00
<div class="menu">
<button
@click="toggleHeading({ level: 1 })"
:class="{ 'is-active': isActive('heading', { level: 1 }, updatedAt) }"
2021-04-09 04:12:46 +08:00
>
H1
</button>
<button
@click="toggleBold()"
:class="{ 'is-active' : isActive('bold', updatedAt) }"
2021-04-09 04:12:46 +08:00
>
Bold
</button>
<button
@click="toggleItalic()"
:class="{ 'is-active' : isActive('italic', updatedAt) }"
2021-04-09 04:12:46 +08:00
>
Italic
</button>
</div>
</template>
2021-04-09 04:12:46 +08:00
<div x-ref="element"></div>
</div>
2021-04-09 04:12:46 +08:00
<script type="module" src="/main.js"></script>
<style>
body { margin: 2rem; font-family: sans-serif; }
button.is-active { background: black; color: white; }
.tiptap { padding: 0.5rem 1rem; margin: 1rem 0; border: 1px solid #ccc; }
2021-04-09 04:12:46 +08:00
</style>
</body>
</html>
```
2021-10-20 04:30:45 +08:00
You should now see Tiptap in your browser. Time to give yourself a pat on the back! :)