Routing Controllers Promotion

[pleerock]

This library is great. It allows to create really beautiful and well-structured controllers using amazing TypeScript language. It exists already for 1.5 year and proved itself on production, in large scale projects, in teams. I can say its quite stable already.

But its not so popular. It has only 255 stars at the moment for 1.5 years... Thats a shame having the fact of routing-controllers awesomeness.

I need contributors help to promote this library.

• first and simple promotion is to post this library on reddit (some people already see this library on reddit already in comments). I plan to post this library link once 0.7.0 release is out
• second is to promote via twitter. Unfortunately I don't have lot of followers on twitter. So we need to find somebody with lot of followers to share our library.
• third is to write blogs. It would be great if somebody can write a blog on medium on how to create awesome node.js applications with typescript and routing-controllers.

Anyone know other good ways to promote this lib? I need all you guys help to promote what we are working with.

[NoNameProvided]

I have no more followers than you (+6 to be exact 😄 ) but happy to write "why to use routing-controllers" article about it, also I am sure I can DM a few friend to share the library. (This would work better with an article.)

Also before really going mainstream, there is a few thing you should consider:

• docs: quite some time should be spent on improving the docs, now it's long and messy, some hierarchy and better wording should help a lot
• code audit: we should re-read the code, to try to find some hiding bugs, especially with focus on uncaught exception. Also the explicit next() calling should be solved before a final release
• release of 1.0: since you consider the lib mature, a 1.0 release should be considered. Beta (and Alpha) releases scare people away.
• rename: most of the mainstream projects has easily recognizable and "cool" names, routing-controllers is not. This is totally subjective to me, but it really should be considered.
• moving the repo into its own org: I would say its a good idea to move routing-controllers, class-validator, and class-transformer into one organization. They would still continue to work alone as well, but moving the into an org should send a strong message about these tools was made to work with each other. (Maybe moving under typestack org?)
• contributing guidelines: no there are no guidelines docs about the structure of the project, this would help lowering the entry to others to open PR-s for issues

I know docs writing is hard and time consuming, re-reading and validating the code is hard as well, but these are things the project need before going mainstream. Also some kind of communication (Gitter?, Slack?) should be created to help organize the work of maintainers. (If you going mainstream, you will eventually need some.)

[pleerock]

"why to use routing-controllers" article about it,

this would be awesome :)

docs

agree, it needs improvements and simplifying. Need suggestions how we can simplify it + someone should check grammar

code audit

this should be contributors work.

release of 1.0

this can be done in a near future

rename

agree, but... I was thinking about naming a lot and did not came to something good (I also have socket-controllers and model-controllers lib which also should be renamed)

moving the repo into its own org

yes, I have plan to move all repos into typestack org

contributing guidelines

yes, something I need to do

(Gitter?, Slack?)

there is a gitter channel

[MichalLytek]

agree, it needs improvements and simplifying. Need suggestions how we can simplify it + someone should check grammar

Use GitBook instead of plain readme on github. It should be divided into two parts - introduction, where you show how simple and clean controllers you can write vs the plain express equivalent, and the part where more advanced parts are described + the API reference on the end (easily searchable)

third is to write blogs. It would be great if somebody can write a blog on medium on how to create awesome node.js applications with typescript and routing-controllers

I was thinking about a big article showing how to write modern node.js app using TypeScript, routing-controllers, TypeORM, class-validator and TypeDI for more than a half of year. But the bigger article I want to write, the less time I have for it and I'm not sure I will have more time in the nearest feature 😞

It exists already for 1.5 year and proved itself on production, in large scale projects, in teams. I can say its quite stable already.

So it's an ideal time to move into 1.0.0 release. Show the potential users that it's a mature framework, battle-tested in production and with stable API. There always be some things to add, some things to fix and some code to refactor, so you can postpone the 1.x.x release for an another 1.5 year if you want to release it as a perfect tool.

most of the mainstream projects has easily recognizable and "cool" names, routing-controllers is not. This is totally subjective to me, but it really should be considered. agree, but... I was thinking about naming a lot and did not came to something good (I also have socket-controllers and model-controllers lib which also should be renamed)

It doesn't have to be a meaningful name, it can be abstractive and should be short and easy to remember. Names like nest.js are the example 😉

[Diluka]

I love this lib. It really makes things easy. The community is active and you guys are enthusiasm.

I found something. Maybe the tags have some problems. Don't see it by this searching on github. I suggest some short simple tag, like typescript, express, koa, framework, web, decorator,spring, etc.

BTW, routing-controllers is really a long name hard to remember.

P.S. I found all the families (routing-controllers, typedi, class-validator, typeorm) though @pleerock 's account.

[pleerock]

Use GitBook instead of plain readme on github

TBH I don't like gitbook, never liked reading docs on github. Gitbook docs seems bad UX for me. Maybe better idea to create a separate site just like typeorm has. I've created #163 for this purpose

I was thinking about a big article showing how to write modern node.js app using TypeScript, routing-controllers, TypeORM, class-validator and TypeDI for more than a half of year.

typestack will simplify those things in the future. For now we need simple article about nodejs+express+typescript+routing-controllers

So it's an ideal time to move into 1.0.0 release.

then lets do this. I have created project lets add things there what we want to put on 1.0.0 release and do it

It doesn't have to be a meaningful name, it can be abstractive and should be short and easy to remember. Names like nest.js are the example

agree. but its hard for me to find abstract name either. Probably I need good names for other libraries as well. One bad thing about renaming - others don't like renaming things....

[pleerock]

@Diluka I added few more tags to the project description...

[Diluka]

@pleerock I see tags with - have very low hit rate in searching. Am I the only one to think so?

I was searching with decorators to find routing-controllers on both google and npm. Using decorators to creating an app by typescript on nodejs like I was doing the same using spring on java is the reason why I choose routing-controllers.

[NoNameProvided]

Maybe better idea to create a separate site just like typeorm has.

We can just move all of our docs into the docs/ folder and write it as markdown, then it can be published as github pages. (Blog post) This way, docs stay in the same repo as the code, so changing the docs when code changes will be a way more easier.

agree. but its hard for me to find abstract name either. Probably I need good names for other libraries as well.

Lets open an issue for this, to see what ideas do others have?

[pleerock]

github docs also is not a good place for docs, I never found convenient to read docs of other libs from github docs.

Lets open an issue for this, to see what ideas do others have?

yeah we can do that

[NoNameProvided]

github docs also is not a good place for docs

Github will generate a website from it, you dont have to read it on the repo, so the docs will become a website available at http://pleerock.github.io/routing-controllers

[pleerock]

yeah I already tried all that stuff before and didn't liked it. Its much flexible if you build site from scratch.

[MichalLytek]

TBH I don't like gitbook, never liked reading docs on github

I'm not talking about docs on github. GitBook creates great websites, here is an example: https://docs.nestjs.com/

For now we need simple article about nodejs+express+typescript+routing-controllers

I should also be a part of the mentioned getting started / introduction of the new docs.

Its much flexible if you build site from scratch.

I don't like coding html when we have markdown and build engine for generating docs site.

[pleerock]

I'm not talking about docs on github. GitBook creates great websites, here is an example: https://docs.nestjs.com/

yeah I know about it. I don't like look and feel of gitbook created sites. Just like docs of nestjs

I don't like coding html when we have markdown and build engine for generating docs site.

if you want to improve site ux you'll need to add a bit client-side javascript code. It will be hard to achieve with generated sites or markdown sites.

[NoNameProvided]

I don't like coding html when we have markdown and build engine for generating docs site.

Yes I vote also to use some already built solution, Gitbook or the already mentioned solution by me: the docs folder. I dont think we should spend time on writing a custom site now. The docs is text only so I see not that much added value here from a full website.

Gitbook Advantages:

• easily manageable
• creates table of content automatically
• great editor Disadvantages:
• needs to be managed differently from the code, this makes it harder to keep in sync with the actual code. (or can we sync from a sub folder of this repo @19majkel94?)

Github Pages Advantages:

• very flexible
• can be the home of the blog as well :) Disadvantages:
• high entry cost, we need to design and build the site itself before starting to create content
• if we want a maintainable solution we need to setup a static site generator to allow editing files
• needs most effort to update

Github Pages Advantages:

• low entry cost, just start creating files in the docs/ folder and pushing them to the master.
• easiest to update alongside with the code, with this approach we can easily group code and doc changes into one PR, everything can be in sync, this is a big win from the devs view. Disadvantages:
• not so flexible, only Github's markdown is supported
• needs to maintain table of content by hand

[NoNameProvided]

Also a think we havent discussed about, we should create a code style, and add some tooling for it. For example my editor is configured totally differently by default, so I have to disable all code formatting to work on routing-controllers which is not so great.

Is the code style open for discussion? I really don't like the 4 space for tab, it makes the code nested way to fest, so I would vote for 2 spaces.

Also there are some other questions in my mind about the tooling but I will open a separate issue for all of these tooling questions.

[MichalLytek]

Is the code style open for discussion? I really don't like the 4 space for tab, it makes the code nested way to fest, so I would vote for 2 spaces.

No, no, no! For God's sake! 😖 That's why:

2 spaces reduces Visual Feedback. Using indentation to separate code-blocks gives you a visual feedback on the level of structure your program is in. Say you were in a for loop structure, and you had indentation of 4 or even 8 spaces, you would immediately know how far this loop structure extends without reading through the code or searching for a closing brace. Using 2 spaces, (at least for me) reduces the effectiveness of that feedback.

With 2 spaces it's getting worse e.g. with promises, there the first char is a dot:

doSomethingAsync
.then(() => {
  console.log("one")
  doSomethingAsync
  .then(() => {
    console.log("two")
    doSomethingAsync
    .then(() => {
      console.log("three")
    })
    console.log("four")
  })
  console.log("five")
})

With more lines you can't see if console.log("four") is on the same line as console.log("one"). 2 spaces is like using ' instead of ", one-line if-statement and other terrible ideas.

[pleerock]

yeah I also dislike 2 spaces, its much harder to read this way.

[NoNameProvided]

No, no, no! For God's sake! 😖 That's why:

I can say the same, using 4 spaces nest the code way too fast, forcing you to split your code into multiple lines more often, which imo make code a way more hard to read.

Hmm for me seems very strange the way you nest it, you should ident the lines starting with dot, because they belong to the doSomethingAsync function, putting them in the same line would indicate that they are standalone things in that nesting level, what is not true. I would format it this way:

doSomethingAsync.then(() => {
  console.log("one")
  doSomethingAsync.then(() => {
    console.log("two")
    doSomethingAsync.then(() => {
      console.log("three")
    });
    console.log("four")
  });
  console.log("five")
});

I can read this structure clearly, but I am using guide lines, which you can too:

With these lines, you can immediately understand how deep a line is and using it with two spaces, you can prevent the code going right too fast.

If this not convince you, then I think we have to stick with the 4 space 😄

Either case we should add some tooling for this, an .editorconfig file at least.

[MichalLytek]

I would format it this way

So if you do then inline, how the chaining would look like?

doSomethingAsync.then(() => {
  console.log("one")
  doSomethingAsync.then(() => {
    console.log("two")
  });
  .then(() => { // this way?
    console.log("three")
  })
    .then(() => { // or this way?
      console.log("three")
    })
  console.log("five")
});

Or this way?

doSomethingAsync.then(() => {
  console.log("one")
  doSomethingAsync.then(() => {
      console.log("two")
    });
    .then(() => {
      console.log("three")
    })
  console.log("five")
});

I prefer chaining on new line:

myarray
  .map(element => element * 2)
  .filter(element => element < 10)
  .forEach(console.log)

So when you have multiple chaining and nesting level it's impossible to visually track the nesting level - am I in then or if, etc.

With these lines, you can immediately understand how deep a line is

Lines are like bracket, it require from you to track - "I am on 3rd level, let's go up up up and there is my promise called". With 4 spaces you can do this in 1s on one screen without tracking nesting level.

[pleerock]

I can say the same, using 4 spaces nest the code way too fast, forcing you to split your code into multiple lines more often, which imo make code a way more hard to read.

not so much if you don't do a callback hell. And we don't do a callback hell. I don't think I will agree on changing 4 spaces to 2 here and in other projects. Its more kinda personal preference and perosnal adaptation. Better if we talk here about routing controllers promotion and start writing blogs 😆 For coding style we can create a separate issue.

[idchlife]

@pleerock I will try to do my best with promotion. This and other your libraries make all the fun in TS backend for me. Never felt this way in nodejs.

[pleerock]

thanks 👍

[NoNameProvided]

I don't think I will agree on changing 4 spaces to 2 here and in other projects.

Then it's decided I guess, hehe.

For coding style we can create a separate issue.

Created one 👉 #173

[bradymholt]

This library is awesome. I'll try to help in whatever way I can.

• I do agree on the name change. Maybe spending a little time on a name generate site like http://www.naminum.com/ could help? Name changes are painful but I do think it would certainly help this project.
• Documentation site - there are obviously tons of ways to do this but I think keeping it in markdown in the repo and generating the html output, published on GitHub pages is the way to go. On one of my projects, I have a simple generate.js script that takes a template and a markdown page (the README.md in my case) and outputs index.html. It's simple and works great. Reference: https://github.com/bradyholt/cRonstrue/tree/master/docs
• Website - along with docs, I think there needs to be a landing page for this project with a very simple and impressive block of "Getting Started" code that immediately catches attention. This website and the docs could all be together in one site as well. Now has a page similar to what I am thinking. It certainly doesn't have to be as fancy but when you open that page, you think "whoa, this is cool". This project is so helpful I think a simple Getting Started animated gif of block of code could really help.

[NoNameProvided]

Website - along with docs, I think there needs to be a landing page for this project with a very simple and impressive block of "Getting Started" code that immediately catches attention.

Absolutely true, Evan You the author of Vue has wrote a about this somewhere, a few good demo really can keep up the interest of visitors, they stay longer and read more on the site.

For the documentation if we really go with a website, we should consider Hexo, with a plugin for markdown. This is the way how Vue docs are written:

The website is built with Hexo, a nice static site generator which is essentially Jekyll in Node.js. This allows me to write documentations and guides in Markdown while retaining full control over the site - including visual design and embedding examples. The documentation is written separately in Markdown because personally for me writing all the docs in source comments hurts code readability quite a bit. The site is hosted on GitHub pages. It is also open sourced so users can contribute to the contents. One day after launch I got a pull request fixing Bruce Lee’s email address. You see, open source is awesome.

[bradymholt]

Currently at 304 ★ and counting 😄

[chriszrc]

I just started using nestjs, and it's implemented a very similar set of controller decorators, I wonder if there's a possibility for collaboration here

[pleerock]

collaboration isnt possible and it was already discussed, they have their own way and we have our own.

[github-actions[bot]]

Stale issue message