Status of nuxt-directus rewrite using the Directus SDK

[Sandros94]

How to use it

Install

1. Install the module

   npm i -D nuxt-directus-next
   yarn i -D nuxt-directus-next
   pnpm i -D nuxt-directus-next

2. Add the module to your nuxt.config.ts and set your url

   export default defineNuxtConfig({
     modules: ['nuxt-directus-next'],
     directus: {
       url: 'https://my-directus.com'
     }
   })

   Or by setting your .env

   NUXT_PUBLIC_DIRECTUS_URL = "https://my-directus.com"

Documentation

Currently the new documentation is Work In Progress, so not every page is complete.

But some starting points are:

• Installation
• Concepts

Be aware

Although obvious, you must expect things to not work as expected and encounter some bugs. So, if you intend to use this in production, be conscious you are doing it at your own risk.

Since we are in pre-release, any support by providing links to reproducible bugs will help us get closer to a stable release.

What this new version is currently about

As some of you might know I started rewriting the nuxt-directus module by wrapping the Directus SDK, both providing simple everyday-use functionalities, as well as simplifying repetitive tasks and exposing more complex ones.

Thanks again to @Intevel and @casualmatt for the support and decision making.

Things that start with NEW are new feature implemented in the module that weren't present in the OG version.

Release notes during this rewrite

• [email protected]
• [email protected]
• [email protected]
• [email protected]
• [email protected]

✅ DONE

• useDirectus
• useDirectusAuth
• useDirectusCollections
• useDirectusFiles
  • getThumbnail (missing intentionally, see notes below)
• useDirectusItems
• useDirectusNotifications
• useDirectusTokens
• useDirectusUsers
• useDirectusRevisions
• Full type support.
• NEW: Auth validation.
• NEW: private and public staticTokens.
• NEW: configs for handling auth cookie by Directus or Nuxt.
• NEW: optionally auto-import native composables from the Directus SDK (with customization via prefix/suffix).
• NEW: natively use useAsyncData for readAsync** functions. Check this comment for more info
• NEW: oFetch and Websockets support with possibility to customize them.
• NEW: out of the box image support with @nuxt/image, with transforms and automatic sizing from Directus API
• NEW: query defaults for authenticated users available under directus.moduleConfig.readMeQuery in your nuxt.config.ts
• NEW: custom clients available under ~/server for server side operations (docs are on the way).

⬜ TODO

• Docs: for basically everything, as well as for good practices.
• useDirectusVersions
• useDirectusTranslations

😅 Known issues

• docs aren't updated as often as the nuxt-directus-next releases, please refer to the playground to see examples on the current usage

📑Notes

• Nuxt Image is part of this module and preconfigured, but there is still an open issue about editing the baseURL at runtime. To workaround that issue, until it is fixed, I've added a custom Image provider named nuxt-directus that takes care of picking up your directus.url automatically and use that, even if you pass it via NUXT_PUBLIC_DIRECTUS_URL env variable.

[matt-clegg]

Thank you for handling this rewrite! Is there an ETA on a release candidate?

[casualmatt]

We are in the testing phase; it will take some more time to test everything.
And because we don't want to push it, we will not have any ETA.

But you can freely download it manually, copy it to the modules folder in your Nuxt project and rename the module.ts into the index.ts

[Sandros94]

Might be useful a guide section in the main post on how to test the rewrite manually, with a huge disclaimer that things are expected to work/crash differently. But any detailed and reproducible report/bug will definitely help speed up the testing phase.

Tomorrow, or as soon as I have time, I'll add that guide section at the bottom of the main post of this discussion.

[Sandros94]

@matt-clegg I added the small guide

[Intevel]

First Release Candidate

Hello everyone! I'm actually quite late in getting back to you, sorry for that.

First of all, a big compliment to @Sandros94 and @casualmatt for their work.

Our plan is to release the new version after successful testing in the main branch under version v6.0, at the same time there will be a new documentation and a separate Directus instance with a sample app showing authentication and more, that's the plan for the near future.

I have just released the first RC of nuxt-directus with the integration of the Directus SDK.
This version does not run under the nuxt-directus package. ⚠️

The RC can be installed under nuxt-directus-next, the new documentation up to the release in v6.0 will run under next.nuxt-directus.site.

In the future, the new documentation will then run on the main domain and the old one at v5.nuxt-directus.site.

---

Package on NPM: https://www.npmjs.com/package/nuxt-directus-next
Documentation: https://next.nuxt-directus.site/

[zguig52]

Hello,
I'm currently testing the new release of the project. First, thanks a lot for this great job!
Shall I open questions / bugs here in this tread as it is not a stable release or just open standard issues telling I use the next release ?
My current concerns/topics to discuss with you are:

• usage in Pinia Stores
• integration with external authentication library like Nuxt/Auth (they are close to release a refresh mode of their lib)
• custom user profile response stored in live State

[Sandros94]

I do agree with @casualmatt and most of the points presented are advanced use cases. Meaning that in the described use case some of the provided functions and composables either don't do enough or need too many customizations.

This is the exact reason we optionally auto-import and expose the native Directus SDK. This approach would require you to either create your own clients or use the already available ones and use the composables from the native SDK on top of them. I'll make sure to re-add the advances-use section to the new docs with some basic examples.

I could give some more info about some points:

1. If you are talking about schema types then there are actually plans for that, but they are not ready yet. You can take a look at the state of the official Directus issue and pull request. But again, since this is such a complex topic (the plan is to support most, if not every, use cases) there are no ETA, nor promises.
2. As @casualmatt already said, the easiest route is to use the SDK that comes with the module. The optimal solution for this would be to use the clients exported from either useDirectus, useDirectusRest, useDirectusGraphql and useDirecutsRealtime and then manually import or auto-import the SDK composables. From this point you could simply follow Directus official docs.
3. Nothing to add.
4. That is actually my oversight, hopefully I'll be able to add it before stable release.
5. Nothing to add.

[zguig52]

Thanks for all your answers @casualmatt and @Sandros94.

I'll check how to use the SDK from the module

[Sandros94]

@zguig52 solved the query defaults for authenticated users

• NEW: query defaults for authenticated users available under directus.moduleConfig.readMeQuery in your nuxt.config.ts

[zguig52]

Discussion continued on feedbacks as I have clarified some elements.

2. [BUG?] Usage inside Pinia Stores:
   What I understood is that Pinia stores doesn't like useState methods (the bug comes only when looped several time in an init function). Might be more on Pinia side to handle this properly. I will investigate later. But it works when using SDK directly (and NOT using function relying on state methods from other modules / stores).

3. [QUESTION / EVOLUTION?] Integration with Nuxt/Auth:
   Here is how I made it work with the sdk exposed. Maybe there could be something done to support it in future releases?

class ExternalAuthStorage {
  get() {
    let token = 'UNDEFINED';
    let tokenSplit = useAuth().token.value?.split(`Bearer `)
    if(tokenSplit && tokenSplit.length >= 2){
      token = tokenSplit[1];
    }
    return {
      access_token: token,
      refresh_token: useAuth().refreshToken.value,
      expires: null,
      expires_at: null,
    };
  }
  set() {
  }
}

export const directusAuthenticatedRestClient = () => {
  // https://github.com/directus/directus/discussions/13882
  let storage = new ExternalAuthStorage();
  return sdkCreateDirectus(useRuntimeConfig().public.apiURL as string)
    .with(sdkAuthentication('json', { credentials: 'include', storage }))
    .with(sdkRest());
}

I can provide you also some code samples on creating a Nuxt server API gateway to handle Nuxt/Auth info transfer with refresh module (there only lacks custom refresh token payload implementation to be able to fully authenticate directly with Directus server - but works totally for other features - login, logout, ):

      body: JSON.stringify({
        refresh_token: body.refreshToken,
        mode: "json"
      }),

This might be solved soon by this:
sidebase/nuxt-auth#635
Or this:
sidebase/nuxt-auth#714

[Sandros94]

for now I'll say that we can keep an eye on that. But surely, while buing an iteresting topic, I could see it as a future 6.x version (post 6.0 stable)

[Lucas-Gruber]

Is it planned to support anything like the transform property from useAsyncData?

https://nuxt.com/docs/api/composables/use-async-data#params

[casualmatt]

We are working on solving some reactivity and nested reactivity issues with useAsyncData, it's possible but still not decided that we will use the new payload API of nuxt, and drop useAsyncData, due to the same issues useFetch have.

Here a list of just some of them:

• to pass reactive parameters, the parameter needs to be a ref or a reactive const, without the .value in the case of ref.
• No types support in the query parameters, just in the response.

We are open to suggestions and feedback,
and @Sandros94 is the lead dev for the new SDK, and he is keener on the use of the payload API, which has a lower performance impact, and the fix of the duple request behavior for SSR, SSG,... (this way the main issue that we try to solve with async data)

[Sandros94]

• No types support in the query parameters, just in the response.

Well, in reality not even in the response, that's why any transform are also blind.

Hopefully later this day, I'll update the main description of this discussion with the current list of caveats I've encountered while trying to implement a native support for useAsyncData, and the approach I have in mind.

But first I want to fix an oversight I did in regard of server-only static tokens.

[Sandros94]

@Lucas-Gruber I've updated the description and published [email protected] that removes useAsyncData but implements native payload support:

I've pushed the decision in removing support for useAsyncData. The main reason being a number of reactivity issues that were breaking mainly the watch and refresh functions, not allowing simple use of reactive queries. This is something that is closely monitored, tested and hopefully addressed in a future version. But we wanted to prevent double fetches and hydration errors so we implemented useNuxtData (the same one that handles the payload for useFetch and useAsyncData under the hood) within all read* functions. If you need to disable or customize the key of this caching system, you can simply edit the nuxtData property:

   const posts = await readItems('posts', { nuxtData: 'my-custom-key' }) 
   // or
   const { data: posts } = await useAsyncData('my-custom-key', () => readItems('posts', { nuxtData: false }))

Once we sort those issues we'll make sure to re-add native support for it.

[Lucas-Gruber]

I can't retrieve relational fields.

Request:

const data = await readItems('collection', {
  query: {
    fields: [
      'id',
      'relation.relational_field'
    ],
  },
});

And i get only this:

{
  "id": "xxxxx",
  "relation": "[only the relational-item-id not the data]"
}

Is this a bug? When i try it with the rest it works so i don't think its a Directus problem.

[casualmatt]

fields: [
    "name",
// M2M
    "categories.categories_id.title",
 // O2M
    "thumbnail.id", 
    "thumbnail.title",
  ]

Depends, your example misses context, but that would only work if it's an O2M relationship.
If you have an M2M you need to go one more deep.

[casualmatt]

I would suggest looking at Directus documentation; the module doesn't interfere with query parameters.
https://docs.directus.io/reference/query.html#fields

[Lucas-Gruber]

I now know what the error was, I had the field-property in the query object:

wrong:

const data = await readItems('collection', {
  query: {
    fields: ['id', 'gallery.id'],
  }
});

right:

const data = await readItems('collection', {
  fields: ['id', 'gallery.id'],
});

[Sandros94]

right:

const data = await readItems('collection', {
  fields: ['id', 'gallery.id'],
});

Indeed, since I've removed useAsyncData I also removed the params property, so now you don't need to wrap them in query anymore.

Docs are still WIP and we also were trying to address them in a separate branch, but I've updated the examples for this one.

[Sandros94]

With [email protected] I've introduced a breaking change for a greater good, let me explain:

no more payload support

This decision was made mainly to follow the same logic of all the other functions: tightly coupling them with the module and configurations to let everyone build upon them. This change has unlocked the following one.

useAsyncData is back

Now it is available under a few experimental functions. The naming convention mixes the normal read* functions and useAsyncData. They are available under their respective composable and named readAsync* (eg: readAsyncItem, readAsyncItems, readAsyncFile, and so on).

All these functions accept refs as their top-level query parameters, mimicking how useFetch works:

import type { RegularCollections, QueryFields } from '@directus/sdk'
import type { Schema, Post, Test } from '~/types'

const { readAsyncItems } = useDirectusItems<Schema>()

const collection = ref<RegularCollections<Schema>>('posts')
const fields = ref<QueryFields<Schema, Post | Test>>(['id'])
const search = ref('')

const { data, refresh } = await readAsyncItems(collection, {
  query: {
    fields,
    search
  },
  immediate: false,
  watch: [collection, fields, search]
})

const { data: useFetch, refresh: useFetchRefresh } = await useFetch(collection, {
  query: {
    fields,
    search
  },
  baseURL: 'https://mydirectus.com/items',
  immediate: false,
  watch: [collection, fields, search]
})

As you can see it follows the same structure of useFetch as well it requires you to pass refs directly (and NOT .value).

why are these considered experimental?

There are still some rough edges, for example:

• there is no pick parameter: since in the current state it nukes useAsyncData (although we could debate whether it is required or not, considering that we could just specify which fields to pick via query and in extremis drop some of them via transform)
• transforms don't update the type output
• the query property itself isn't reactive, the following wont work:

  const query = reactive({})
  const { data } = await readAsyncItems(collection, { query })

Please report any issue you encounter, either replying here or opening up a new issue with a reproduction link.

Other changes with 0.0.11

• error handling is still WIP, but now any fetch error (with status, statusCode and message) can be catched.
• clients (from any composable within nuxt-direcuts-next) now correctly fall back to generic types if no Schema is passed, providing basic type functionalities.

[luigigorlero]

Is there a higher-level method for aggregate()?

I managed to grab it by exposing:

const { client } = useDirectusItems<Collections>()
const items = await client.request(sdkAggregate('collection', {
  aggregate: { count: 'id' },
}))

but it feels like a hack. Thanks for the rewrite, I’m enjoying using the library!

[Sandros94]

Is there a higher-level method for aggregate()?

I managed to grab it by exposing:

[...]

Currently not, and indeed you need to mix the preconfigured client with the aggregate function from the SDK

but it feels like a hack.

Not at all! This is actually the intended use.
We are not going to wrap every function from the SDK (mainly for maintainability purposes). This means that those we currently don't provide require you to just follow the official Directus docs. With the only exception that we prepare the clients for you 😜

Thanks for the rewrite, I’m enjoying using the library!

Thanks! 🔥

[Sandros94]

Just released [email protected], this update mainly focuses on Nuxt Image integration:

Notable changes

• simplified the structure of our custom provider nuxt-directus, this means you can override properties from your nuxt.config.ts
• support for staticToken and authToken with Nuxt Image, editable in your nuxt.config.ts

  directus: {
    nuxtImage: {
      useAuthToken: false, // default false
      useStaticToken: true // default true
    }
  }

• support to manually passing tokens, or disable them, for each Image request via modifiers

Notes

• By default useAuthToken is set to false because since it will append the current access_token of the logged user to the URL of the image. Unfortunately Nuxt Image doesn't provide a way to handle auth tokens only via headers. You will be the judge to set it to ture and automatically adding it to all image requests or just manually passing it when you need it.
• If you need to manually construct the URLs, since $img from Nuxt Image doesn't support reactive inputs, you must wrap it manually in a watch function and handle it yourself.

Examples

Checkout the nuxt.config.ts and restricted.vue in the dev/playground to see some examples.

[Sandros94]

[email protected] and [email protected]

Notable Changes

Return types are now manually handled, this both fixes a number of technical issues as well makes the module run easier. Please open up any issue with a reproduction, since this was mainly a manual operation and I could have missed something.

0.0.14

Fixed a few other types, mainly involved with useAsyncData

0.0.15

Fixed a few auth issues for [email protected] and [email protected]

[Sandros94]

@zguig52 thanks for taking the time in testing this and documenting it. Indeed I will need to start working on automated tests, for now I'm mostly focused on finilizing the update for v6.0.0-rc and eventually stable release

[zguig52]

Bug is confirmed and tracked here:
directus/directus#21955

[Sandros94]

Bug is confirmed and tracked here: directus/directus#21955

yeah I was following it

[Sandros94]

@zguig52 [email protected] as been released with that fix. It will be available in the next release, but in the meantime you could try to update the dep locally on your own, so we could even test if this works as intended (module and sdk being partially disconnected with minor and patch updates)

[zguig52]

Hi @Sandros94 ,
Just did some tests with "@directus/sdk": "^15.1.0", everything works as expected on websocket and subscriptions side :)

[luigigorlero]

I’m getting an error when trying to implement the nuxtDirectus provider for @nuxt/image:

Pre-transform error: Failed to resolve import "/Users/[PROJECT_FOLDER]/nuxtDirectus" from "virtual:nuxt:/Users/[PROJECT_FOLDER]/.nuxt/image-options.mjs". Does the file exist?

Is the provider exposed for use?

[Sandros94]

Could you share your current directus and image configs within nuxt.config.ts?

I've got mixed results in various projects so far, and most of the time it depends on the image configs. So I have yet to understand what is caused by the work I've done and what by the @nuxt/image module

[luigigorlero]

I believe I was trying something as simple as:

export default defineNuxtConfig({
  directus: {
    url: process.env.NUXT_PUBLIC_DIRECTUS_URL,
    staticToken: process.env.DIRECTUS_TOKEN,
    staticTokenServer: process.env.DIRECTUS_TOKEN,
    moduleConfig: {
      devtools: true,
      autoRefresh: false,
      autoImport: true,
      nuxtImage: {
        useStaticToken: false,
      }
    },
  },
  image: {
    provider: 'nuxt-directus',
  },
})

but never got it working. What does a working config look like?

From a DX point of view, it would be great if nuxtImage could read the custom provider injected by nuxt-directus and merge any extra config found in image.provider['nuxtDirectus'] or directus.moduleConfig.nuxtImage

[casualmatt]

hi @luigigorlero,

Just a note, probably not related to your issue: you don't have to import process.env.NUXT_PUBLIC_DIRECTUS_URL. This can cause some issues; nuxt will do that for you at runtime; just use the correct key for your environment variable, and let the variable be an empty string in the config or dummy data.

[Sandros94]

@luigigorlero also to extend @casualmatt suggestion: you should handle both staticToken and staticTokenServer via NUXT_PUBLIC_DIRECTUS_STATIC_TOKEN and NUXT_DIRECTUS_STATIC_TOKEN respectively. This is because any process.env (or import.meta.env) are elaborated at build time and lose the ability to be edited at runtime (more info in the docs).

In the end you should have something, simply like this:

// nuxt.config.ts
export default defineNuxtConfig({
  modules:['nuxt-directus-next'],
  directus: {
    moduleConfig: {
      devtools: true,
      autoRefresh: false,
      autoImport: true,
      nuxtImage: {
        useStaticToken: false,
      }
    },
  },
})

# .env
NUXT_PUBLIC_DIRECTUS_URL="https://example.com"
NUXT_PUBLIC_DIRECTUS_STATIC_TOKEN="mySuperLongPublicSecret"
NUXT_DIRECTUS_STATIC_TOKEN="mySuperLongPrivateSecret"

While for the original question:
One of the inconsistencies I'm getting with nuxt image is that in some project the image.provider: 'nuxt-directus' isn't working and most of the times nuxtDirectus is. But more simply, if it is going to be your only image provider then you could simply remove it from the nuxt.config.ts, as I'm managing it directly with the module, if no customization is already applied to nuxt image configs (you don't even need to add it to the modules).

[Lucas-Gruber]

Hey, is it possible to receive activity (especially comments) with the new version?

[casualmatt]

U can do everything the SDK can, I would suggest to take a look at the SDK documentation and instead of using Directus instance from the SDK, u use it from the module.

[Sandros94]

to give an example of what @casualmatt said, you can freely mix-up the module base rest client composable and any sdk function like this:

import { readItems } from '@directus/sdk'

const client = useDirectusRest()

const { data: posts } = await useAsyncData(() => client.request(readItems('my_collection')))

[Lucas-Gruber]

Alright, thanks!
I wasn't sure how to mix the module and the SDK.