search

aws-powertools / powertools-lambda-typescript

Powertools is a developer toolkit to implement Serverless best practices and increase developer velocity.
https://docs.powertools.aws.dev/lambda/typescript/latest/
MIT No Attribution
1.55k stars 133 forks source link

Docs: Simpler Get Started Docs #2948

Open nideveloper opened 1 month ago

nideveloper commented 1 month ago

What were you searching in the docs?

I literally just want to pull in lambda powertools into a ts lambda based codebase, I have previously heavily used the python implementation which is just pull it in and add some annotations. I wanted to know how to do that with Typescript, the docs do not come close to showing this. I used the annotations from an example repo and ts threw errors

Is this related to an existing documentation section?

No response

How can we improve?

There is too much ambiguity on the landing page for how to get started and everything seems to be focused on middy, I understand middy users are going to be a large chunk but I just want to use powertools in a ts lambda function with no middleware so I would like a section that just has the getting started for that. If the annotations do not work for that I would like that documented up front or if it does work, I would like that right on the landing page how to do it. Personally I think linking me to a github repo adds too much cognitive complexity because I then need to understand the project then what you did that was an opinion then understand how powertools fits in.

Got a suggestion in mind?

No response

Acknowledgment

boring-cyborg[bot] commented 1 month ago

Thanks for opening your first issue here! We'll come back to you as soon as we can. In the meantime, check out the #typescript channel on our Powertools for AWS Lambda Discord: Invite link

dreamorosi commented 1 month ago

Hi @nideveloper, thank you for the feedback and for taking the time to open an issue about it.

You are right, and we have missed the mark on this aspect in the Typescript documentation when it comes to quickly getting started. While we have an example project in the repo, as well as a basic SAM CLI template we have a lot of room for improvement.

I will spend some time improving this aspect and providing a concise "Getting Started" section as well as how to setup the project with TS (#2395), and potentially also adding a Tutorial similar to the one Powertools for AWS (Python) has.

Regarding your comment on Middy.js vs other patterns - I think the confusion is warranted. As a project we offer three ways of using Powertools for AWS (TypeScript) vs one (decorators) in Powertools for AWS (Python). There are a few reasons why this is the case, and mainly because there're tradeoffs in each one of them in this ecosystem, while in Python using decorators on functions is a well known and established practice.

Despite the context however, it's true that in our docs we barely have an opinion on which one we recommend and why, not to mention the fact that we don't elaborate on the tradeoffs for each one of them. This is something other customers have also voiced, and that unfortunately we haven't answered in the docs yet.

Making these updates will be an iterative process, and it will take some time to get right, but rest assured that we will prioritize this in the coming weeks. Regarding your specific issue, I'd still like to help unblock you and help you get started (provided you still want to).

I'm happy to help you either here or jump on a call with you to guide you - whichever you prefer!