graphile / graphile/graphile.github.io

Inconsistent plugins development documentation

Đang mở
#255 10 bình luận 0 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
SCSS
Star
27
Fork
126
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

I'm trying to add a custom plugin to the `postgraphile:http:handler` event.
Accordint to the https://www.graphile.org/postgraphile/plugins/#enabling-via-postgraphilercjs section, I'm adding it to the `plugins` rc file section.
According to the https://www.graphile.org/postgraphile/plugins/#writing-your-own-plugins section, I've created my plugin stub:
```
const CorsPlugin = {
['postgraphile:http:handler'] (req, p2) {
console.log(req);
console.log(p2);
return req;
}
}
module.exports = CorsPlugin
```
But when running, I'm getting the following error log:
```
/postgraphile/build-turbo/postgraphile/cli.js:300
throw new Error(`No plugin found matching spec '${name}' - expected function, found '${typeof plugin}'`);
^
Error: No plugin found matching spec '/postgraphile/CorsPlugin' - expected function, found 'object' at /postgraphile/build-turbo/postgraphile/cli.js:300:19
```

Please update these docs on how to write own plugins.

Also, there's no documentation on how to use the existing CORS plugin example with the rc file to be able to adapt it to my needs. Plugins documentation is overall messy and it's hard to understand what's going on and how to catch anything without a long time googling, discord discussions, or github issues.

My main pain points during all my Postgraphile experience are:

1. What type of plugins exists?
2. What's the difference between plugin types?
3. How plugins and hooks relate?
4. What types of hooks exist?
5. Which hooks can be set up from which plugins?
6. Where to see plugins and hooks parameters documentation?
7. How to convert plugins and hooks declaration/connection between different types (middleware, library, rc file, CLI)? If I found an example of a plugin/hook I spend a lot of time trying to adapt it to rc file.
8. When I see a comment like `use postgraphile:http:handler to intercept the result if it's for us` used by Benjie everywhere I see a wall of hours of investigations how to implement it in the reality. Especially in my deployment way (with an rc file).
9. A single entrypoint of plugins/hooks documentation with a clear table of contents would be very useful. Like this: https://www.easypost.com/docs/api . Examples of plugins with the different types of connection (library/rc file/cli) like code examples in different languages also would be super useful (here https://www.easypost.com/docs/api it is implemented as a dropdown list, some sites use tabs: https://cloud.google.com/tasks/docs/reference/rest/v2/projects.locations.queues.tasks/run).

I like Postgraphile a lot, but every time I need to do something by my own plugins I feel pain... :(

Hướng dẫn đóng góp

Chưa lập chỉ mục được hướng dẫn đóng góp cho kho mã nguồn này

Hướng nghiên cứu

Bắt đầu với các phần được liên kết “Enabling via postgraphilerc.js” và “Writing your own plugins”, sau đó tái hiện lỗi đối tượng thay vì hàm đã được báo cáo bằng ví dụ CorsPlugin được đưa ra. Hoàn thành khi tài liệu plugin giải thích các loại plugin và hook, các tham số và mối quan hệ của chúng, đồng thời cung cấp các ví dụ rõ ràng về thư viện, tệp rc và CLI, bao gồm plugin CORS hiện có.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
javascript
Lĩnh vực
documentation
Loại issue
Tài liệu
Độ khó
5/5
Thời gian dự kiến
Hơn một tuần
Mức độ hoạt động
Đình trệ
Độ rõ ràng
Cần làm rõ
Mức phù hợp với người mới
20/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.