search

nestjs / docs.nestjs.com

The official documentation https://docs.nestjs.com 📕
MIT License
1.18k stars 1.69k forks source link

Evaluate adding a section that explains how to create a Nestjs project from scratch #1759

Open ericmorand opened 3 years ago

ericmorand commented 3 years ago

I'm submitting a...

[ ] Regression [ ] Bug report [ ] Feature request [X] Documentation issue or request (new chapter/page) [ ] Support request => Please do not submit support request here, instead post your question on Stack Overflow.

Context

Current documentation explains how to create a Nestjs project using either the CLI or a starter project (https://docs.nestjs.com/#installation). Both approaches work fine but mask the real prerequisites of NestJS. This can be an issue for people that don't want to use a scaffolder or a starter project - either because they prefer to control what they install or because they use projects architectures that are different from the one provided by the scaffolders - or both.

These people are left in the blind, forced to investigate by themselves what they need to create a project using NestJS. I for example spent a few hours stuck with providers not injected into my controllers because my TypeScript config was missing the emitDecoratorMetadata compiler option.

More generally, I think it would be great to have a list of the minimal requirements to have a functionnal Nestjs project instead of only exposing scaffolders and starter projects. Frameworks like Angular, Drupal or Magento have became extremely difficult to scaffold without using the official scaffolders or starter projects because nobody knows anymore what is needed exactly to create a project from scratch, and I think that this error can still be avoided with Nestjs.

Fortunately, the minimal requirement for Nestjs is quite small and straightforward (another proof of the quality of the framework if you ask me) but I think that some subtle details need to be explicitely written down in the documentation.

I'd like to provide a PR about that.

jmcdo29 commented 3 years ago

I think this is a pretty good idea. Mentioning the bare minimum packages that should be used, and the required configs on the tsconfig to make sure the decorators work. I'll see if I can work on something over the weekend.

kamilmysliwiec commented 3 years ago

This sounds like a great addition! PRs are more than welcome.

Just one important note: we might need to add it in a different chapter than First Steps/Introduction to avoid confusion and making an impression that there are plenty of steps required to set up a barebone application. Instead, we should consider creating a dedicated chapter and moving it under one of the existing categories (not Overview)

micalevisk commented 1 year ago

I just wrote an article on that subject: 5 steps to create a bare minimum NestJS app from scratch!

micalevisk commented 2 months ago

Here is my WIP example of a simple nestjs app that doesn't use the @nestjs/cli as has only the minimum packages to work with nestjs+typescript: https://gitlab.com/micalevisk/really-bare-minimum-nestjs-standard-app

image

micalevisk commented 2 months ago

@ericmorand @kamilmysliwiec @jmcdo29

do you still think that this would be good to have in the docs site? Blog posts like this one can fill this gap I guess. I really don't think that people will try to create a Nestjs without running nest new. Specially because the 'default' boilerplate is not that big. I'd say that this addition would be more for advanced learning purposes.

If you guys agree on having this in the docs, I'll try to work on it.

ericmorand commented 2 months ago

Specially because the 'default' boilerplate is not that big.

That's a fair point.

I'd say that this addition would be more for advanced learning purposes.

I'll let my teaching nature speak here: I'm convinced that we should always teach people how something work before giving them some tools to make it more comfortable to use.

Although I totally understand the benefits - from a consumer engagement point of view - of hiding the complexity, I have seen so many seasoned developers fail to explain how their favorite frameworks (or favorite patterns like IoC) work that I can't but be convinced that the "skeleton application / boilerplate" trend is detrimental to our job.

Anyway, I think that a quick mention and a link to the article you wrote, in the documentation, would be the best of both worlds. I know that I would have immediately followed such a link, would it have been available years ago when I started working with nestjs. :)