Transitioning Back to a Nuxt-First Approach

[casualmatt]

Hi to all,

This is to update you on the module and why nuxt-directus-next was not realized as stable, and it's still a beta.

---

During the development of Nuxt-Directus-Next, we encountered several challenges with the new Directus SDK-based module. @sandros94 and the team faced significant difficulties, particularly in the early stages. The SDK's incompatibility with ofetch and the complete rewrite of TypeScript (TS) support mid-development forced us to make extensive changes to our codebase. Additionally, we struggled with optimizing the SDK within a useAsyncData composable to enhance Nuxt's performance by improving page load times and reducing the number of API requests sent to Directus.

Moreover, the frequent major releases of the Directus SDK, occurring every two months, necessitated constant fixes and adjustments to maintain compatibility with TS and adhere to good Nuxt practices. This rapid pace of change made the current approach increasingly unsustainable.

After careful evaluation, Sandro and I have concluded that building the module around the SDK is not maintainable in the long term. Therefore, we have decided to pivot to a Nuxt-first approach, prioritizing developer experience and stability. Our revised plan includes:

• $directus based on ofetch for manual Directus REST API calls.
• useDirectus based on useFetch for the most optimized access to the Directus API.
• useDirectusWs for interacting with the WebSocket functionality exposed by Directus.

Additionally, we will provide composables for wrapping essential functions, such as the Files API, that are vital for your projects.

We're also considering implementing a smart feature: if the module detects the presence of the SDK in your project, it will automatically create a preconfigured client for both server and browser environments.

With this new approach, we believe every use case will be addressed. Experienced users will still have access to the SDK, but in day-to-day projects, your TypeScript configurations won't break every two months. You can also expect better integration with Nuxt 4, particularly in terms of data fetching and state management optimizations.

We look forward to your feedback and to refining this approach further to meet the community's needs.

Matt.

[sandros94]

Some personal notes about this new implementation of nuxt-directus:

• feature parity with official SDK (and what was done previously with nuxt-directus-next)
• preconfigured SDK client if it is found as a dep
• preconfigured nuxt-image preset if it is found as a dep (instead of installing it forcefully)
• everything should be based on a custom $fetch and useFetch
• dedicated composable for translations
• dedicated composable for versions
• dedicated composable for websockets

[Lucas-Gruber]

Is there any repo or branch to watch the current state?

[casualmatt]

yes ofc: nuxt-first

@sandros94 is also updating the playground, so you should be able to test part of the new module already.

[Nisthar]

yes ofc: nuxt-first

@sandros94 is also updating the playground, so you should be able to test part of the new module already.

i was just going through the repo to learn more. wondering why this is commented out:

// TODO: ensureDependencyInstalled forces it to install if not present
    // Check if a Directus SDK is installed and auto import it
    // const directusSDK = await ensureDependencyInstalled('@directus/sdk')
    // nuxt.options.alias['#nuxt-directus/sdk'] = directusSDK
    //   ? '@directus/sdk'
    //   : 'unenv/runtime/mock/empty'
    // // Auto import native components
    // if (directusSDK && directus.moduleConfig.sdk.autoImport) {
    //   const sdkComposables = await import('#nuxt-directus/sdk')
    //   const prefix = directus.moduleConfig.sdk.prefix
    //   const suffix = directus.moduleConfig.sdk.suffix
    //   Object.keys(sdkComposables).forEach(name =>
    //     addImports({
    //       name,
    //       as:
    //         prefix
    //         + (prefix ? name.charAt(0).toUpperCase() + name.slice(1) : name)
    //         + suffix,
    //       from: '@directus/sdk',
    //     }),
    //   )
    // }

Its not usable like this Right?

[sandros94]

Ehy @Nisthar, first off I've seen your other issues and comments, I haven't replied yet since most (if not all) of them will be fixed with the new nuxt-first rewrite. They are mainly related to changes that Nuxt has gotten in the past year or so, and v5 is based on even older structure.

Yes, that commented out section is mainly a note to myself in the future. Currently I don't have a way to dynamically check if the Directus SDK dependency is installed or not, thus I delegated that section to a future me. More importantly I will need to revisit the authentication storage (cookie/session) to make that sdk client work, so it is both not an easy/fast task to do and I want to focus on the nuxt-first approach first.

Unfortunately I don't have an exact eta, nor I'm able to work on it every day since I just got back from holidays and need to focus mainly on other work. If you have any use-cases or ideas to share feel free to write them here in a new comment, but for updates you can subscribe to #273

[vwasteels]

Hello, after reading many issues and discussions, I still don't understand if I should be using using nuxt-directus or nuxt-directus-next, Is the next version doing what 5.7 does ?

Also , I can't find the doc for the next version, the doc linked in the repo is offline :

Thanks !!

[scherii]

It seems that nuxt-directus (official documentation) is currently the better option.

The last commit on the nuxt-first branch was five months ago, which might indicate it’s not actively maintained.

@sandros94 @Intevel Could you provide a quick update on the current status?
If you need feedback, testing, or anything else, just let me know—I’d be happy to help. Thanks!

[Intevel]

Hello, after reading many issues and discussions, I still don't understand if I should be using using nuxt-directus or nuxt-directus-next, Is the next version doing what 5.7 does ?

Also , I can't find the doc for the next version, the doc linked in the repo is offline :

Thanks !!

The Domain for the documentation is nuxt-directus.de

[sandros94]

@sandros94 @Intevel Could you provide a quick update on the current status? If you need feedback, testing, or anything else, just let me know—I’d be happy to help. Thanks!

replying for what I've been doing on nuxt-directus-next and why I stalled.

original idea

Provide a SSR safe wrapper for the official sdk. At first this looked like the simplest approach as well as being backed up from upstream docs/implementation. But then the upstream sdk received a number of breaking changes one after the other, each requiring a rewrite, since I was wrapping each method/operation to provide SSR support.

nuxt-first approach

This is when a nuxt-first approach seemed more doable, as I was already writing each method and operation, but then a number of edge cases started to rise in the custom useFetch implementation I was writing. Testing each every one has started becoming as timeconsuming as rewriting based on each sdk breaking change.

present

It has been a few months since I realized that the solution lies in between the two approaches.
The first one being completely based on upstream's implementation, meaning that this module would have 1-on-1 feature partity with upstream's docs/implementation, at the cost of SSR support (well actually SSR works, the only issue there is are double fetches: one from nuxt server and the other nuxt client, which requires the use of Nuxt's useAsyncData). While the second part (mainly focusing on SSR and less on sdk) would be creating a single composable that acts like useFetch but utilizes directus's OpenAPI to provide full-type support, potentially helping those who are on older versions of Directus instances.

my personal problem

As you might have guessed it this means yet another rewrite. Although, personally speacking, this would be the simplest and shortest one. But most importantly lack of Directus instances to mimic a production-use, added with the lack of time for building a propper one, as my own clients migrated away from Directus.

But I can assure you that there isn't a single week where I don't think about this module and how to solve this stall

[scherii]

@sandros94 Thanks for the detailed update, your openness is very helpful! 😊

Finding a balance between SDK parity and full SSR support sounds very reasonable.
If it helps, I’d be happy to set up a Directus instance for testing or provide feedback from a user’s perspective. Just let me know if that would be useful in any way.

And either way, thanks again for your continued work on this — much appreciated!

[vwasteels]

Thanks all for your answer, I will continue to check on this module :)
Meanwhile I am moving to manual integration of directus SDK to see if I can manage to handle authentication properly.

Thanks