Decorator undefined in sibling Fastify plugin after register()

Answer the exact question first

1. Does encapsulate: false on the provider guarantee visibility to subsequently registered siblings? – Yes. Setting encapsulate: false (or wrapping the plugin with fastify-plugin, which internally sets encapsulate: false) attaches the decorator to the parent instance. Any plugin registered after it can read the decorator via fastify[decoratorName].

2. Can a consumer read a decorator from an encapsulated provider without fastify‑plugin? – No. An encapsulated provider isolates its decorators to its own child instance. A consumer, even if encapsulated, inherits only the parent’s decorators, not those of the provider’s child.

3. Does autoload filesystem sort order make this behavior non‑repeatable across operating systems? – Yes. fastify-autoload registers files in the order returned by fs.readdir, which is OS‑dependent. Relying on lexicographic order is fragile; explicit registration is required for deterministic dependency resolution.

Likely explanation

Fastify creates a new instance for each encapsulated plugin. Decorators added to that instance are invisible to other plugins unless the instance is promoted to the parent scope. The canonical way to expose a decorator to the parent without leaking it into the global namespace of every plugin is to wrap the provider with fastify-plugin or set encapsulate: false.

Confirmed facts

• Fastify v4/v5: encapsulate: false or fastify-plugin attaches a decorator to the parent instance.
• Encapsulated plugins inherit parent decorators but not sibling decorators.
• Autoload’s order is not guaranteed across OSes; explicit register calls are deterministic.

Practical steps for this case

1. Wrap the provider plugin with fastify-plugin (or set encapsulate: false)

   const fp = require('fastify-plugin');
   
   function provider(fastify, opts, done) {
     fastify.decorate('myDecor', { value: 42 });
     done();
   }
   
   module.exports = fp(provider); // exposes decorator to parent
   

2. Register the provider before the consumer

   await fastify.register(require('./provider'));
   await fastify.register(require('./consumer'));
   

3. In the consumer plugin, read the decorator from the parent instance

   module.exports = async function (fastify, opts) {
     // fastify.myDecor is available because the provider exposed it to the parent
     console.log('Decorator value:', fastify.myDecor.value);
   };
   

4. Do not rely on autoload ordering – if you use fastify-autoload, explicitly set the order:

   await fastify.register(require('fastify-autoload'), {
     dir: path.join(__dirname, 'plugins'),
     ignore: ['consumer.js'] // register consumer after provider
   });
   await fastify.register(require('./plugins/consumer'));
   

5. Verify on the target OS – run a small test that logs the decorator value in the consumer to confirm it is defined.

One diagnostic detail that might change the recommendation

If the provider plugin is already wrapped with fastify-plugin and you still observe the decorator as undefined, check whether the consumer plugin is being registered inside a fastify-plugin wrapper that sets encapsulate: true and is executed before the provider. In that case, the consumer’s instance will not see the parent decorator until after the provider registers. Adjust the registration order or remove the encapsulation wrapper.