prosemirror-image-plugin

By Viktor Váczi at Emergence Engineering

Try it out at https://emergence-engineering.com/blog/prosemirror-image-plugin

Features

• Drag and drop or paste images from anywhere
• Upload images to endpoints, showing placeholder until the upload finishes, and optionally delete images when the image is removed from the document
• Customizable overlay for alignment ( or whatever you think of! )
• Optional image title
• Image resizing with body resize listeners, so the image always fits the editor ( inspired by czi-prosemirror )
• Scaling images with editor size ( when resizing is enabled )
• Easy to implement image caching ( in downloadPlaceholder )

How to use

import {schema} from "prosemirror-schema-basic";
import {EditorState} from "prosemirror-state";
import {EditorView} from "prosemirror-view";
import {
    defaultSettings,
    updateImageNode,
    imagePlugin,
} from "prosemirror-image-plugin";

import "prosemirror-image-plugin/dist/styles/common.css";
import "prosemirror-image-plugin/dist/styles/withResize.css";
import "prosemirror-image-plugin/dist/styles/sideResize.css";

// Update your settings here!
const imageSettings = {...defaultSettings};

const imageSchema = new Schema({
    nodes: updateImageNode(schema.spec.nodes, {
        ...imageSettings,
    }),
    marks: schema.spec.marks,
});

const initialDoc = {
    content: [
        {
            content: [
                {
                    text: "Start typing!",
                    type: "text",
                },
            ],
            type: "paragraph",
        },
    ],
    type: "doc",
};

const state = EditorState.create({
    doc: imageSchema.nodeFromJSON(initialDoc),
    plugins: [
        ...exampleSetup({
            schema: imageSchema,
        }),
        imagePlugin({...imageSettings}),
    ],
});

const view: EditorView = new EditorView(document.getElementById("editor"), {
    state,
});

Configuration

ImagePluginSettings

Interface for the settings used by this plugin.

updateImageNode

Returns the updated nodes ( Schema["spec"]["nodes"] type )

Arguments:

startImageUpload

Dispatches a transaction in the editor view which starts the image upload process ( and places placeholder etc ). Returns undefined

Arguments:

startImageUploadFn

Dispatches a transaction in the editor view which starts the image upload process ( and places placeholder etc ). Returns Promise<ImageUploadReturn> (as the uploadFile function you gave in but after the editor transformations)

Type helper; type ImageUploadReturn = { url: string; alt?: string };

Arguments:

Example call;

const myImgUploadFn = (imgUrl: string) => async () => {
    const file = await getFileFromtheInternet(imgUrl);
    const src = await uploadFileToOurServer(file);
    return { url: src, alt: file.name };
};
await startImageUploadFn(editor, myImgUploadFn(inputUrl));

Uploading files

Be aware that the default uploadFile inserts the dataURI of the image directly into the ProseMirror document. That can cause issues with large files, for ex. gifs with long animations.

Upload placeholder

The plugin creates a widget decoration while the upload process is still in progress. The widget decoration's dom node is a <placeholder>, an example style could be:

placeholder {
    color: #ccc;
    position: relative;
    top: 6px;
}

placeholder:after {
    content: "☁";
    font-size: 200%;
    line-height: 0.1;
    font-weight: bold;
}

Loading image css

It is not really trivial how can you use css while you have a broken image src. To get some dirty ideas please check the dev/src/index.css file in the repo and try to understand the placeholderClassName rules.

Test your solution in all browsers!

Firefox and Safari not showing the broken image icon, Chrome and Firefox handles the ::after hack properly, Safari not. So you need to use a platform specific css hack to handle all!

Loading images the custom way

If you have an image behind authentication, or even you just want to show the loading indicator, you need to set the downloadImage function. You can add a string => Promise<string> function to the plugin settings, BUT you want that returning string to be a base64 encoded image. The reason you want to do that, is because if you add a simple image url, your browser will try to load that image "again" without the auth, and without the custom load indicator.

We have a helper function which just fetches the given url and transforms it to base64. (Useful if you want to use the loading indicator.)

import {fetchImageAsBase64} from "prosemirror-image-plugin";

const imageSettings = {...defaultSettings, downloadImage: fetchImageAsBase64};

Cache images and drag & drop

Sometimes you want to modify the editor state as a way that the images want to rerender. Drag and drop is a good example. Usually we don't want to redownload the images. If we have good caching settings at the backend we will not move all the data again, but still... We have some helpers to help you with that.

import {fetchImageAsBase64, imageCache, localStorageCache} from "prosemirror-image-plugin";

const inMemoryCachedDownloadImage = imageCache(
        new Map() // <- this map will be used as a cache, you can move it to a global variable
    )((url) => fetchImageAsBase64(url));
const localStorageCachedDownloadImage = imageCache(
        localStorageCache("img_cache_")
    )((url) => fetchImageAsBase64(url));

const imageSettings = {...defaultSettings, downloadImage: inMemoryCachedDownloadImage};

imageCache is a function which takes a long and a short-lived cache, and a download function (and returns with a more complex download function).

• The long-lived cache needs to have a get(string)=>string|undifined and a set(string,string) function (which Maps happened to have).
• The short-lived cache defaults to a Map<string, Promise<string>>, we use this to cache the promises only, if you have the same image multiple times in your editor state.
• The download function is a string => Promise<string> function, which returns the base64 encoded image (see above).

Uploading images from a file picker

A small React example

In the "html" / JSX part:

<input type="file" id="imageselector" onChange={onInputChange}/>

The onInputChange callback:

const onInputChange = useCallback(
    (e: ChangeEvent<HTMLInputElement>) => {
        if (
            pmView?.state.selection.$from.parent.inlineContent &&
            e.target.files?.length
        ) {
            const file = e.target.files[0];
            startImageUpload(
                pmView,
                file,
                file.name,
                defaultSettings,
                imageSchema,
                pmView.state.selection.from
            );
        }
    },
    [pmView]
);

CSS & Styles

The following styles are in the bundle:

import "prosemirror-image-plugin/dist/styles/common.css";
import "prosemirror-image-plugin/dist/styles/withResize.css";
import "prosemirror-image-plugin/dist/styles/sideResize.css";
import "prosemirror-image-plugin/dist/styles/withoutResize.css";

YJS compatibility

• BREAKING CHANGE: works with yjs collab out of the box, we have a custom mapping which deals with yjs replacing the whole document on external changes, so no worries about lost decorations

Known issues

• titles and inline nodes do not work well together. If hasTitle is true then isBlock should also be true.

Development

Running & linking locally

1. install plugin dependencies: npm install
2. install peer dependencies: npm run install-peers
3. link local lib: npm run link
4. link the package from the project you want to use it: npm run link prosemirror-image-plugin

About us

Emergence Engineering is dev shop from the EU: https://emergence-engineering.com/

We're looking for work, especially with ProseMirror ;)

Feel free to contact me at viktor.vaczi@emergence-engineering.com