documentation
documentation copied to clipboard
strapi
[Request]: Add documentation for the @strapi/utils package
Summary
In v3, most customization was able to pull various functions from the global API strapi.* however in v4 we shifted a lot of functions to a centralized package: @strapi/utils
Currently most of this package is not documented at all or we only reference some functions in code samples without explaining what they do or how they work.
Why is it needed?
Many of these functions are required for many users building plugins, creating custom routes/controllers/services/policies/middlewares/ect. Some examples are:
- All of the sanitize options, some can be passed in the factories but not all
- env-helper (useful for parsing custom environment variables)
- format-yup-errors (custom yup validation and conversion to our error standards)
- pagination (what we use to construct the pagination structure)
- parse-multipart (used to parse files from a request)
- traverse-entity (permissions validation at a deep level)
You can find many more here: https://github.com/strapi/strapi/tree/master/packages/core/utils/lib
Suggested solution(s)
I believe we should work with the engineering teams to discuss these utility functions and start working on documenting more of the Strapi internals as these could be very useful to our community, customers, and users.
Related issue(s)/PR(s)
No response
@derrickmehaffy If I have some time in about 2 weeks I could tackle this. Does this "belong" to the DX squad?
@derrickmehaffy If I have some time in about 2 weeks I could tackle this. Does this "belong" to the DX squad?
It, I think, should belong to the Content Squad actually since the utils I think largely had admin related stuff.
It's a bit of a gray area
IMO it doesn't really matter which "core" squad is handling this. It's one of those shared subjects that anyone could take. Everyone's using those utils and contributing to them :shrug:
This is URGENTLY needed. I wasn't even aware there is a package like this, and now that I have learned I can use it instead of doing delete entry.user I would like to see some proper usage examples / documentation.
@Convly I disagree with you. Whilst anyone can contribute, you can't contribute if you don't know how things work. I am a Strapi user, not a Strapi developer and I don't have the necessary knowledge about the inner workings of Strapi to for example create documentation for the utility functions.
Just look at this thread - everyone is suggesting a different approach, and to be honest NEITHER have worked for me without tweaking the code.
Not having documentation for this will lead to everyone doing things their own way, possibly creating problems and security risks that ultimately will hurt Strapi's reputation. You have to see the big picture. Given that the team has already created and published packages, they need to be documented. A simple README.md would suffice. But providing some documentation for the package is a must.
Hello there,
@Convly I disagree with you. Whilst anyone can contribute, you can't contribute if you don't know how things work. I am a Strapi user, not a Strapi developer and I don't have the necessary knowledge about the inner workings of Strapi to for example create documentation for the utility functions.
Which is why I was referring to Strapi core developers squads in my message, not community members :slightly_smiling_face:
I do agree we need to document this at one point because there are really cool tools inside, we just need to find the time to fit it into one of our squad's sprints.
We have discussed this internally but sharing here as well. The plan to start working on documenting this in the mono-repo under the contrib documentation here: https://github.com/strapi/strapi/tree/main/docs and for the functions that prove to be useful for plugin developers the engineering and support teams will work with the docs team to include them in the dev docs likely in Q1/Q2.
Hi! Update here, one year later. The contributors documentation does not, to my knowledge, document @strapi/utils yet. I'll transfer this request to our internal backlog and we'll take this into consideration for the Strapi v5 docs we've just started writing. I'll close this issue for now but rest assured it is well placed in our backlog and we hope to work closely with Strapi core developers about this one. Thanks again for your precious feedback!
