Not that important but most package managers provide link for this type of functionality which can be a bit more easier to work with when debugging, i.e npm link.

Alternatively just using a link in the package.json can be handy.

"my-module": "link:../modules/my-module"

All good options though

(unrelated but could be worth mentioning stubbing nuxt-module-builder --stub)

I thought about advertizing link here indeed, but I think there's a gotcha with using so (which would be why the current guide suggests pack), maybe @danielroe can enlighten us here? ☺️

Pointing people to use hooks is great but it kind of makes the problem worst as it's harder to debug when these things go wrong. Recommending logging around code that could take a while could help

import { useLogger, defineNuxtModule } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const logger = useLogger('my-module')
    nuxt.hook('modules:done', async () => {
      logger.debug('Starting long async code')
      await doSomethingThatTakesAWhile()
    })
  }
})

Hmm, I get it but I'm not sure how to refactor that section to hint towards that, any suggestions? 🤔

Hm ye I agree it doesn't fit naturally. Maybe it's own section?

Providing Logs

It's good practice to provide logging within your module for code that could misbehave due to user configuration or environment. Allowing end-users to diagnose problems themselves as well as provide useful information for issues.

For example, imagine you're loading files from the user's file system when they are starting your module. The user can provide configuration to change which directories to scan.

If the user accidentally provides a path that is going to scan endless files (symlinked node_module, root directories), their nuxt app may hang indefinitely.

Or they may provide a directory that doesn't hang but is loading more files than expected, resulting in a significantly slower start.

import { useLogger, defineNuxtModule, resolveFiles } from '@nuxt/kit'

export default defineNuxtModule({
  setup (options, nuxt) {
    const logger = useLogger('my-module')
    nuxt.hook('modules:done', async () => {
      logger.debug('Loading files in ${loadDir}.')
      const files = await resolveFiles(loadDir)
      if (files.length > 1000) {
         logger.warn(`Woah ${files.length} files, that's a lot! Is the ${options.loadDir} directory correct?`)
      }
    })
  }
})

To view debug logs users can run their Nuxt app with debug enabled DEBUG=* nuxi dev.

When using other aspects of logging, you should avoid spamming the user with messages that don't provide any needed information.