Cannot use fastify-cli with --options

[nicolas-goudry]

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

5.4.0

Plugin version

No response

Node.js version

20.17.0

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

NixOS 24.11

Description

Hi,

First of, thanks for this demo repository, it's filled with goodies I already used and even more I wasn't aware of.

I based one of my projects on this repository and found out that using fastify-cli with the --options flag ends up in an error I can't quite figure out:

TypeError: ajv.validate is not a function
    at envSchema (/home/nicolas/work/perso/demo/node_modules/env-schema/index.js:83:21)
    at fastifyEnv (/home/nicolas/work/perso/demo/node_modules/@fastify/env/index.js:8:20)
    at Plugin.exec (/home/nicolas/work/perso/demo/node_modules/avvio/lib/plugin.js:125:28)
    at Boot._loadPlugin (/home/nicolas/work/perso/demo/node_modules/avvio/boot.js:432:10)
    at process.processTicksAndRejections (node:internal/process/task_queues:82:21)

To reproduce this error, run the following command:

npm run dev:start -- --options

From what I could gather, this issue is related to this part of the code in src/app.ts:

export const options = {
  ajv: {
    customOptions: {
      coerceTypes: 'array',
      removeAdditional: 'all'
    }
  }
}

If removing the ajv key entirely, it works again. I tried adding other options like ignoreDuplicateSlashes and such and they do work.

I’d love to be able to fix this, but I don't really know where to start.

I can deduce from the error message that this has something to do with the @fastify/env plugin and its dependency env-schema. I’ll try to look into it if I have some time.

Link to code that reproduces the bug

https://github.com/fastify/demo

Expected Behavior

The --options flag of fastify-cli should use custom options defined in the app service without any errors.

[nicolas-goudry]

I looked through the env-schema code and it seems to be quite a subtle bug.

---

Why is this happening?

To understand why this happens, we have to look at how fastify-cli handles the options export from plugins (which serviceApp is).

This is an excerpt from the current README file:

If you want to use custom options for the server creation, just export an options object with your route and run the cli command with the --options flag. These options also get passed to your plugin via the options argument.

From this statement, we can deduce that because the options key is defined in a "top-level" plugin and the way encapsulation works in Fastify, all plugins will inherit of this option, including @fastify/env.

Let's take look at @fastify/env then!

Luckily, the code is pretty simple. The statement responsible of this issue is here:

function fastifyEnv (fastify, opts, done) {
  try {
    const config = envSchema(opts) // <== `opts` contains the whole `options` object defined in `app.ts`

    /* Rest of the code */
  } catch (err) {
    done(err)
  }
}

So, what about env-schema?

In env-schema, the code responsible of using the ajv key from options is here:

const ajv = chooseAjvInstance(sharedAjvInstance, opts.ajv)

This code calls the following function, responsible of instanciating an ajv instance:

function chooseAjvInstance (defaultInstance, ajvOpts) {
  if (!ajvOpts) {
    return defaultInstance
  } else if (typeof ajvOpts === 'object' && typeof ajvOpts.customOptions === 'function') {
    const ajv = ajvOpts.customOptions(getDefaultInstance())
    if (!(ajv instanceof Ajv)) {
      throw new TypeError('customOptions function must return an instance of Ajv')
    }
    return ajv
  }
  return ajvOpts
}

In our case, env-schema ends up returning the original ajv key as if it was an ajv instance (even if it's not), because ajv.customOptions is not a function.

From the README, here is how the ajv.customOptions should be used:

const config = envSchema({
  schema: schema,
  data: data,
  dotenv: true,
  ajv: {
    customOptions (ajvInstance) {
      require('ajv-formats')(ajvInstance)
      return ajvInstance
    }
  }
})

So, one could think: ok, let's set ajv.customOptions to a function as instructed! The code in app.ts would then turn out to be the following:

import ajvFormats from 'ajv-formats'

export const options = {
  ajv: {
    customOptions (ajvInstance) {
      ajvFormats(ajvInstance)
      return ajvInstance
    }
  }
}

That should fix it, right? Well, again, it's subtle.

Enter papa Fastify

Remember? The ajv option is also sent to Fastify's server instance. And guess what, it turns out that it doesn't accept ajv.customOptions to be a function:

FastifyError [Error]: ajv.customOptions option should be an object, instead got 'function'

Note

This behavior has not changed in latest Fastify version (5.6.0)

So, what now?

Well, if we look at the whole picture now that we now all the bits and pieces, I can't see a one-size fits all solution.

We can't set the ajv key to a custom ajv instance, since it would content env-schema but not Fastify, which only uses this key to customize its builtin ajv instance (providing a custom ajv instance is an entirely different process).

We've seen that we can't set ajv.customOptions to a function, since this would again content env-schema but not Fastify.

So… We're stuck now. I think the best course of action would be to update env-schema to match Fastify behavior of using the customOptions to build an ajv instance by merging its default options for ajv with the ones provided into customOptions.

What do you think about that? Should I open an issue in env-schema to address this?

[jean-michelet]

Thanks for the report and investigation, but I think this is more of a design issue from the current implementation.
I remember I received a warning from a former mysql plugin because unexpected options were propagated.

I followed the template generated by fastify-cli, which propagates options, for the design of this demo: https://github.com/fastify/fastify-cli/blob/main/templates/app-ts-esm/src/app.ts#L31

The quick fix is to avoid propagating options to external plugins (see here):

await fastify.register(fastifyAutoload, {
    dir: path.join(import.meta.dirname, “plugins/external”),
    options: {}
  })

But I suspect that it's generally a bad idea to propagate custom options to custom plugins and routing plugins as well.

Should we stop recommending this on fastify-cli?

[jean-michelet]

@fastify/core @fastify/plugins

[nicolas-goudry]

Regarding the propagation, I think this could be a useful feature if you're deep down in the plugin stack, but I do agree it seems like a really bad idea to do it at the top-level. Hopefully, most plugins don't care about extraneous options, but like you pinpointed, some do.

I think the feature is however really useful to set custom options to the Fastify server instance when running with fastify-cli. So IMO it should be kept as-is in app.ts. The real issue here is with downstream plugins, so I guess your fix proposal is a good idea.

I tried it on my project, and it works as expected 👌

It feels like the right fix, since most users would expect the options export to configure the server and not downstream plugins. And also, this makes options inheritance an opt-in feature, which is imo a good practice.

However, I think this should be documented through a descriptive comment above the options export or above the plugins register.