nuxt-modules / prismic

Easily connect your Nuxt.js application to your content hosted on Prismic
https://prismic.nuxtjs.org
MIT License
245 stars 48 forks source link

Migrate to @prismicio/helpers #177

Closed madiyetov closed 1 year ago

madiyetov commented 1 year ago

Is your feature request related to a problem? Please describe.

This package doesn't support types.

Describe the solution you'd like

prismic-dom is deprecated and replaced by @prismicio/helpers v2. The new package comes with Typescript and other than that has multiple benefits.

Let's upgrade to the @prismicio/helpers and add Typescript support

Describe alternatives you've considered

No alternatives

lihbr commented 1 year ago

Hey there, thanks for contributing!

I assume you're talking about @nuxtjs/prismic v1, which targets Nuxt 2/Vue 2. (Just in case, @nuxtjs/prismic v3 targets Nuxt 3/Vue 3 and is fully typed: https://github.com/nuxt-modules/prismic/tree/v3) [^1]

Updating to @prismicio/helpers

It could be possible to update @nuxtjs/prismic v1 away from prismic-dom to @prismicio/helpers v2[^2][^3]. This would result in breaking changes to handle (notably: https://prismic.io/docs/prismic-helpers-v2-migration-guide#update-children-in-html-serializers).

This could be mitigated in the plugin template (with conditionals) alongside an additional option (similar to the current modern one, or the modern one with a new special value)

  1. Does that sound like an option to you?
  2. If you'd like to work on that feel free to open a PR, would be happy to help!

Alternatives

Providing an extra .d.ts file alongside the module

A lightweight alternative could be for @nuxtjs/prismic to provide some type definitions (referencing a .d.ts file in its package definition). This way we could provide some basic types for the injected plugins and improve the experience.

Using @prismicio/helpers directly in your code

Vue 2 ecosystem overall had fragile TypeScript support and getting it to work correctly was non-trivial. That's why most of the SDKs (at least on Prismic's side) were just plain JavaScript.

If you'd like to use helpers from @prismicio/helpers in your codebase, you can do so directly once you have it installed in your dependencies.

import * as prismicH from "@prismicio/helpers";

export default {
    mounted() {
        prismicH.asHTML(...);
    },
};

Let me know if anything! Again, I'm happy to help!

[^1]: To be transparent, I first reserved @nuxtjs/prismic v2 for a potential new major of the module still targeting Nuxt 2. However with both Nuxt 2 and Vue 2 going EOL by the end of the year, I now would like to avoid releasing a new major.

[^2]: For reference, helpers (utils from prismic-dom/@prismicio/helpers v2) are also injected by the Vue plugin (when not using Nuxt) @prismicio/vue v2: https://github.com/prismicio/prismic-vue/blob/v2/src/methods.js, Ideally both would keep behaving the same, the reason this logic is duplicated is that the community first made the Nuxt module.

[^3]: Just a heads up that updating to @prismicio/helpers alone wouldn't provide full TypeScript support to the module as the client @prismicio/client is still on v5 (which provided very light support), and the components are untyped.

madiyetov commented 1 year ago

Thanks for the detailed answer! If it will result in a new major version, I think that directly using the @prismicio/helpers will be feasible to me until we migrate to the nuxt v3)

Feel free to close this issue πŸ™ŒπŸΌ

lihbr commented 1 year ago

Awesome, thanks for your understanding ☺️

I'll keep it opened for now just in case I get a better idea in the meantime~

Thanks again!

lihbr commented 1 year ago

Well, we're on the verge of releasing complete Nuxt 3 support alongside with the Nuxt 3 module going out of RC soon.

I don't have any reasonable idea to improve the above for Nuxt 2, workarounds have been shared above~

Thanks again for your contribution and comprehension πŸ™