graphile / graphile/graphile.github.io
Inconsistent plugins development documentation
- 主要言語
- SCSS
- スター
- 27
- フォーク
- 126
- PR マージ指標
- 30日以内にマージされた PR はありません
説明
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... :(
コントリビューションガイド
このリポジトリのコントリビューションガイドは索引されていません
調査の方向性
リンクされている「Enabling via postgraphilerc.js」と「Writing your own plugins」のセクションから始め、次に、示されている CorsPlugin の例を使って報告されたオブジェクトと関数のエラーを再現します。完了条件は、プラグインのドキュメントでプラグインとフックの種類、それらのパラメーターと関係を説明し、既存の CORS プラグインを含む、ライブラリ、rc ファイル、CLI の明確な例を提供することです。
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- javascript
- 領域
- documentation
- issue の種類
- ドキュメント
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 活発さ
- 停滞
- 明瞭さ
- 説明が足りない
- 初心者へのやさしさ
- 20/100