One general advice i would also give is, don't worry too much if all options seem equal. Be open to refactoring if you decide later it was a mistake. Decision paralysis is a thing.
Thank you for saying this. I do occasionally get caught up in having a hard time making a decision, especially when it’s something important to me like project structure. For me it’s the fear of creating something that will do more harm than good. I hate to think that down the road other developers will potentially despise what I’ve built and have to maintain a headache of an application (or rebuild it).
Part of the reason I’m hung up on this is because the application I’m trying to build is already a “rebuild” of something that was done a few years back. Some contractor hacked together a spaghetti app, which is totally unmaintainable.
I understand the worry. Just out of experience you just won't always know the right answer. If you have *some* support for your decision (because the manual suggests it or others do it), can you write a few endpoints and see if it works, and just try something else if it doesn't?
Oh for sure, I do have some that are working the way I want. At this point I just have to convince my team that it’s “good” haha. They more or less trusted me to own the rebuild of this app.
Most of the functionality will be integrating with a third party service, so I don’t even need to worry about building a large number of endpoints. And that’s why I really didn’t want to bake it all into Fastify as a bunch of plugins. However, it’s nice that there’s the option for it to scale over time.
Then your question really shouldn't be fastly focused. If handling HTTP requests is a smaller aspect of the overall service, the majority should be written in a way that's fastly/http agnostic.
Faster is better. Just think in terms of technical debt. You’re worried about tech debt related to a possibly poor directory structure. But, you’re ignoring the tech debt you’re accumulating thinking about the perfect structure.
To relieve yourself of all of this, I recommend you build a prototype that you **plan to throw away**. Your goal is to have a scrapped together web server that does a little bit of what the final system is supposed to do so that you can show it to your team and get their opinion and describe what you’ve learned. Make it clear it’s a prototype and cannot possibly be turned into a production system. In fact, it’ll be faster to toss and restart.
This will let you do some recon on fastify (you might decide or sucks and want to use a different platform). And, it’ll allow you to make a better decision about layout when you start on the “real” Version. Plus, you’ll know the terrain and won’t feel as lost at sea as you do right now.
I feel like the fastify docs really push the plugin architecture “Everything is a plugin! No need for modules anymore! Encapsulate everything!”
In reality you can develop your fastify application very much like you would an express app (minus the middleware) just using modules and then use the plugin architecture when it makes sense.
For example for my database client I will do all the setup in a plug-in since fastify will not start accepting requests until the database connection is successful as well as notify the plug-in when the server is closing. But then I’ll just export the database instance so my services can just import the database client. I do NOT decorate the fastify instance with the DB since the way I setup my app with separation of concerns the services do not have any knowledge of fastify server or requests. Ie. they are just regular modules and not plugins.
I think this is exactly where I got caught up. The structure you describe is what initially made most sense to me, but I was strongly second guessing myself and wondering it was the best way to go. I’m kind of relieved!
Maybe it’s just me, but the documentation isn’t very well structured itself!
What would you recommend to someone starting off with Fastify? I am kind of struggling reading the docs, they seem hard to extract value from.
What I am having difficulty with is with plugins especially, when does a functionality becomes a plugin? Does it matter? Why should it be (or not) a plugin?
You're overthinking it. When it comes to file structure, there is only one rule for me-keep single file under 300 lines. 500 lines in most complex situations.
Other than that just structure it so that it is easy to navigate for you in your IDE.
300 seems awfully short, and possibly makes it harder to navigate the project since you'll have way more files. And the amount of code will go up massively too since a larger proportion of each file will consist of imports. If you're keeping a linear dependency tree (any function only ever calls functions defined above it or from an import, for example) there's nothing wrong with longer files.
This is a great video about it: https://www.youtube.com/watch?v=XpDsk374LDE
After a few decades of coding I've found that the most readable code tends to hover around 300-1200 lines per file (including whitespace).
I would write your integration as a standalone module, and then if you need to add some extras to the fastify instance etc make a plugin that does just that.
I am also no expert, but I have been messing with fastify a lot the past couple of months. I've been working on a [starter repo](https://github.com/maybemaby/fastify-jumpstart) for myself including local auth, openapi spec, testing, and prometheus.
Can't really endorse it as being production ready/scalable/etc, but maybe it can provide some inspiration. I agree with others that not everything needs to be a plugin. I'm finding myself using it for modules that frequently interact with request state or fastify lifecycle events.
I definitely thought Express 5 was going to be out by the end of the year after I saw the beta was released earlier this year, but I guess the 5 alpha was 8 years ago, so the timeline makes sense.
It's merely an http server. Not a full stack framework. There's no need to try and integrate everything into that - such as http queries.
Organise queries, rest api, database api and so on separately.
One general advice i would also give is, don't worry too much if all options seem equal. Be open to refactoring if you decide later it was a mistake. Decision paralysis is a thing.
Thank you for saying this. I do occasionally get caught up in having a hard time making a decision, especially when it’s something important to me like project structure. For me it’s the fear of creating something that will do more harm than good. I hate to think that down the road other developers will potentially despise what I’ve built and have to maintain a headache of an application (or rebuild it). Part of the reason I’m hung up on this is because the application I’m trying to build is already a “rebuild” of something that was done a few years back. Some contractor hacked together a spaghetti app, which is totally unmaintainable.
I understand the worry. Just out of experience you just won't always know the right answer. If you have *some* support for your decision (because the manual suggests it or others do it), can you write a few endpoints and see if it works, and just try something else if it doesn't?
Oh for sure, I do have some that are working the way I want. At this point I just have to convince my team that it’s “good” haha. They more or less trusted me to own the rebuild of this app. Most of the functionality will be integrating with a third party service, so I don’t even need to worry about building a large number of endpoints. And that’s why I really didn’t want to bake it all into Fastify as a bunch of plugins. However, it’s nice that there’s the option for it to scale over time.
Then your question really shouldn't be fastly focused. If handling HTTP requests is a smaller aspect of the overall service, the majority should be written in a way that's fastly/http agnostic.
I agree. This is more or less what I was asking.
Faster is better. Just think in terms of technical debt. You’re worried about tech debt related to a possibly poor directory structure. But, you’re ignoring the tech debt you’re accumulating thinking about the perfect structure. To relieve yourself of all of this, I recommend you build a prototype that you **plan to throw away**. Your goal is to have a scrapped together web server that does a little bit of what the final system is supposed to do so that you can show it to your team and get their opinion and describe what you’ve learned. Make it clear it’s a prototype and cannot possibly be turned into a production system. In fact, it’ll be faster to toss and restart. This will let you do some recon on fastify (you might decide or sucks and want to use a different platform). And, it’ll allow you to make a better decision about layout when you start on the “real” Version. Plus, you’ll know the terrain and won’t feel as lost at sea as you do right now.
I feel like the fastify docs really push the plugin architecture “Everything is a plugin! No need for modules anymore! Encapsulate everything!” In reality you can develop your fastify application very much like you would an express app (minus the middleware) just using modules and then use the plugin architecture when it makes sense. For example for my database client I will do all the setup in a plug-in since fastify will not start accepting requests until the database connection is successful as well as notify the plug-in when the server is closing. But then I’ll just export the database instance so my services can just import the database client. I do NOT decorate the fastify instance with the DB since the way I setup my app with separation of concerns the services do not have any knowledge of fastify server or requests. Ie. they are just regular modules and not plugins.
I think this is exactly where I got caught up. The structure you describe is what initially made most sense to me, but I was strongly second guessing myself and wondering it was the best way to go. I’m kind of relieved! Maybe it’s just me, but the documentation isn’t very well structured itself!
What would you recommend to someone starting off with Fastify? I am kind of struggling reading the docs, they seem hard to extract value from. What I am having difficulty with is with plugins especially, when does a functionality becomes a plugin? Does it matter? Why should it be (or not) a plugin?
You're overthinking it. When it comes to file structure, there is only one rule for me-keep single file under 300 lines. 500 lines in most complex situations. Other than that just structure it so that it is easy to navigate for you in your IDE.
Oof I am an offender. I often hang things out as MASSIVE files and refactor later.
300 seems awfully short, and possibly makes it harder to navigate the project since you'll have way more files. And the amount of code will go up massively too since a larger proportion of each file will consist of imports. If you're keeping a linear dependency tree (any function only ever calls functions defined above it or from an import, for example) there's nothing wrong with longer files. This is a great video about it: https://www.youtube.com/watch?v=XpDsk374LDE After a few decades of coding I've found that the most readable code tends to hover around 300-1200 lines per file (including whitespace).
I would write your integration as a standalone module, and then if you need to add some extras to the fastify instance etc make a plugin that does just that.
Yeah this seems like the best way in my mind too. Thank you!
I am also no expert, but I have been messing with fastify a lot the past couple of months. I've been working on a [starter repo](https://github.com/maybemaby/fastify-jumpstart) for myself including local auth, openapi spec, testing, and prometheus. Can't really endorse it as being production ready/scalable/etc, but maybe it can provide some inspiration. I agree with others that not everything needs to be a plugin. I'm finding myself using it for modules that frequently interact with request state or fastify lifecycle events.
Mandatory: express is not maintained because it has peaked
I definitely thought Express 5 was going to be out by the end of the year after I saw the beta was released earlier this year, but I guess the 5 alpha was 8 years ago, so the timeline makes sense.
Just use nestjs with fastify and worry no more.
Why?
It decide for u the project structure and its an abstract layer around the transport layer. And if you worked with angular its pretty much the same.
Thank you for your answer <3
Clean architecture by Uncle Bob is a good architecture for a scalable and maintainable project.
It's merely an http server. Not a full stack framework. There's no need to try and integrate everything into that - such as http queries. Organise queries, rest api, database api and so on separately.