Cannot find module '@umbraco-cms/backoffice/tiptap'

[erikjanwestendorp]

What type of issue is it? (Choose one - delete the others)

Wrong documentation

What article/section is this about?

rich-text-editor/extensions

Describe the issue

When attempting to add the following code sample:

import { UmbTiptapExtensionApiBase } from '@umbraco-cms/backoffice/tiptap';
import { Highlight } from '@tiptap/extension-highlight';

export default class UmbTiptapHighlightExtensionApi extends UmbTiptapExtensionApiBase {
	getTiptapExtensions = () => [Highlight];
}

Cannot find module '@umbraco-cms/backoffice/tiptap' or its corresponding type declarations.

[sofietoft]

Thanks for reporting this @erikjanwestendorp ! 💪

I'll run this b our frontend developers, to get it verified.

What specific version of Umbraco are you using? Is it 15.1.1?

[erikjanwestendorp]

@sofietoft Sorry, my mistake. For some reason, I had a very old version of @umbraco-cms/backoffice, but now I’m facing a different issue. First, I follow the Vite package setup as described here:

https://docs.umbraco.com/umbraco-cms/customizing/development-flow/vite-package-setup.

After that, I follow the steps in:
https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/rich-text-editor/extensions#adding-a-native-extension

However, after following these steps, I get the following console errors:

GET https://localhost:99999/App_Plugins/MyTiptapExtension/highlight.tiptap-api.js net::ERR_ABORTED 404 (Not Found)

and

Uncaught (in promise) TypeError: Failed to fetch dynamically imported module: https://localhost:99999/App_Plugins/MyTiptapExtension/highlight.tiptap-api.js

So, I updated the umbraco-package.json like so (change api path to client.js):

{
    "name": "My Tiptap Extension",
    "version": "1.0.0",
    "extensions": [
        {
            "type": "tiptapExtension",
            "alias": "My.Tiptap.Highlight",
            "name": "My Highlight Tiptap Extension",
            "api": "/App_Plugins/MyTiptapExtension/client.js",
            "meta": {
                "icon": "icon-thumbnail-list",
                "label": "Highlight",
                "group": "#tiptap_extGroup_formatting"
            }
        },
        {
            "type": "tiptapToolbarExtension",
            "kind": "button",
            "alias": "My.Tiptap.Toolbar.TaskList",
            "name": "My Highlight Tiptap Toolbar Extension",
            "api": "/App_Plugins/MyTiptapExtension/client.js",
            "meta": {
                "alias": "highlight",
                "icon": "icon-brush",
                "label": "Highlight"
            }
        }
    ]
}

But then I get this:

create-extension-ele…-api.function.js:61 -- Extension of alias "My.Tiptap.Toolbar.TaskList" did not succeed creating an Element with Api, Element was created but the imported Api JS file did not export a 'api' or 'default'. 
{__isMatchedWithKind: true, type: 'tiptapToolbarExtension', kind: 'button', alias: 'My.Tiptap.Toolbar.TaskList', element: ƒ, …}

My vite.config.ts looks like this:

import { defineConfig } from "vite";

export default defineConfig({
    build: {
        lib: {
            entry: "src/index.ts", 
            formats: ["es"],
        },
        outDir: "../../MyProject/App_Plugins/MyTiptapExtension", 
        emptyOutDir: true,
        sourcemap: true,
        rollupOptions: {
            external: [/^@umbraco/],            
        },
    },
    base: "/App_Plugins/MyTiptapExtension/", 
});

And my index.ts like this:

export * from './highlight.tiptap-api';
export * from './highlight.tiptap-toolbar-api';

[leekelleher]

@erikjanwestendorp Thank you for testing out the Tiptap extension documentation steps, sorry that you've experienced issues with it. I've re-reviewed the steps and there is room for improvements on how to set-up the initial structure for an Umbraco extension/package.

Hopefully the latest (but currently undocumented) dotnet new umbraco-extension template will resolve many of these pain points. I'll be working with the Community Packages Team to update the existing documentation.

In the meantime, the issue you've experienced is with referencing the client.js (compiled from the index.ts) for both the Tiptap extension and toolbar APIs, as both extensions are expecting the export to be either named api or be the default export. Which in this case would cause a conflict with the named api exports, and the default to using the class names.

The current way to workaround this would be to use the bundle extension type, then you would be able to define the Tiptap manifests within TypeScript, using the () => import("./highlight.tiptap-api.js") syntax. (The Vite JS bundler would handle updating the filepath names).

This approach will align nicely with the latest dotnet new umbraco-extension template. I'll look to update the documentation accordingly.

---

@sofietoft This is the work item that the Community Package Team has for updating the documentation for the new umbraco-extension template. Community Package Team
I'll try to coordinate efforts on the updates. 🤞

[sofietoft]

Thanks for the insights @leekelleher ! 😄

Let me know if you anything from me team, regarding the umbraco-extensions template docs 🙌

[erikjanwestendorp]

@leekelleher First of all, thank you for your detailed response! 🙏 I already heard a colleague mention the dotnet new umbraco-extension template, and I’m really looking forward to using it! 😄.

Using a bundle does indeed solve the issue. However, the documentation (even though it’s still a work in progress) is outdated, as copying the example below gives me a deprecated warning:

export const manifests: Array<ManifestTypes> = [
    {
        type: 'dashboard',
        name: 'Example Dashboard',
        alias: 'example.dashboard.demo',
        element: () => import('./demo-dashboard.js'),
        weight: 900,
        meta: {
            label: 'Demo example',
            pathname: 'demo-example',
        },
    },
    // ... insert as many manifests as you like
]

I’ve therefore updated the manifest file to the following (using UmbExtensionManifest instead of ManifestTypes):

export const manifests: Array<UmbExtensionManifest> = [
    {
        type: 'tiptapExtension',
        name: 'My.Tiptap.Highlight',
        alias: 'My Highlight Tiptap Extension',
        js: () => import('./highlight.tiptap-api.js'),
        meta:{          
            "icon": "icon-thumbnail-list",
            "label": "Highlight",
            "group": "#tiptap_extGroup_formatting"
        }
    },
    {
        type: 'tiptapToolbarExtension',
        kind: 'button',
        alias: 'My.Tiptap.Toolbar.TaskList',
        name: 'My Highlight Tiptap Toolbar Extension',
        js: () => import('./highlight.tiptap-toolbar-api.js'),
        meta:{
            "alias": "highlight",
            "icon": "icon-brush",
            "label": "Highlight"
        }
    }
]

@sofietoft Would it be okay for me to create a PR to update the v15 version of the bundle article, even though this article is still a work in progress?

Additionally, there’s still a small issue with using the Highlighting extension, as I’m getting the following console error:

For me, this isn’t a big issue right now, as I’m only reading the documentation to start building my own extension, but it might be good to look into this. If I find the issue, I’ll create a PR. 😄

[sofietoft]

Please feel free to create the PR @erikjanwestendorp ! 🙌

Any updates to these articles are much appreciated, while we work on getting our ducks in a row to update the missing pieces 😁 🦆