From 9d7f63841543566e09ff17b443617171d9e55b35 Mon Sep 17 00:00:00 2001 From: Felipe Henrich Date: Fri, 20 Dec 2024 11:23:25 -0300 Subject: [PATCH 1/3] docs: draft ADR for gql.tada and updated FE README --- docs/adr/adr-typing-graphql.md | 65 ++++++++++++++++++++++++++++++++++ front/README.md | 3 +- 2 files changed, 67 insertions(+), 1 deletion(-) create mode 100644 docs/adr/adr-typing-graphql.md diff --git a/docs/adr/adr-typing-graphql.md b/docs/adr/adr-typing-graphql.md new file mode 100644 index 000000000..f2da7ebef --- /dev/null +++ b/docs/adr/adr-typing-graphql.md @@ -0,0 +1,65 @@ +# ADR: Typing GraphQL Usage + +## Status + +Implemented + +## Context + +We need a reliable and efficient way to handle GraphQL typings in our project. Currently, we are using GraphQL Code Generator, which has its benefits but also some drawbacks. We are considering switching to `gql.tada` for the following reasons: + +1. **Developer Experience**: `gql.tada` offers a more streamlined and intuitive developer experience. It simplifies the process of defining and using GraphQL types, reducing the cognitive load on developers. +2. **Type Inference**: `gql.tada` provides better type inference capabilities, which can lead to more accurate and maintainable code. This is particularly important in a dynamic and evolving codebase. +3. **Performance**: `gql.tada` is designed to be lightweight and fast, which can improve the overall performance of our development workflow. + +## Decision + +We will adopt `gql.tada` for typing GraphQL usage in our project. This decision is based on the following comparisons with GraphQL Code Generator: + +### GraphQL Code Generator + +- **Pros**: + - Automatically generates TypeScript types from GraphQL schemas and operations. + - Supports a wide range of plugins and configurations. + - Well-documented and widely used in the community. +- **Cons**: + - Can be complex to configure and maintain, especially for large projects. + - Generated code can be verbose and difficult to navigate. + - Requires additional build steps, which can slow down the development process. + +### gql.tada + +- **Pros**: + - Simplifies the process of defining and using GraphQL types with a more intuitive API. + - Provides better type inference, reducing the need for manual type annotations. + - Lightweight and fast, with minimal impact on build times. + - Easier to integrate into existing projects with less configuration overhead. +- **Cons**: + - Less mature and less widely adopted compared to GraphQL Code Generator. + - May have fewer plugins and integrations available. + +## Consequences + +By adopting `gql.tada`, we expect to achieve the following benefits: + +- Improved developer experience with a more intuitive and streamlined API. +- Better type inference, leading to more accurate and maintainable code. +- Faster development workflow with reduced build times. + +However, we also acknowledge the potential risks: + +- Limited community support and fewer available plugins compared to GraphQL Code Generator. +- Potential need for additional customizations or workarounds due to the relative immaturity of `gql.tada`. + +Overall, we believe that the benefits of adopting `gql.tada` outweigh the potential drawbacks, and we are confident that this decision will lead to a more efficient and enjoyable development experience. + +## Implementation + +1. Integrate `gql.tada` into the project and replace existing GraphQL Code Generator configurations. +2. Update documentation and provide guidelines for using `gql.tada` in the codebase. +3. Monitor the adoption and gather feedback from the development team to ensure a smooth transition. + +## References + +- [gql.tada Documentation](https://example.com/gql-tada-docs) +- [GraphQL Code Generator Documentation](https://example.com/graphql-code-generator-docs) diff --git a/front/README.md b/front/README.md index 62067024d..a69bb0424 100644 --- a/front/README.md +++ b/front/README.md @@ -1,6 +1,6 @@ # Readme -This front-end project of Boxtribute was bootstrapped with [Create React App](https://github.com/facebook/create-react-app). +This front-end project of Boxtribute was bootstrapped with [Vite](https://vite.dev/). ## Table of Contents @@ -13,6 +13,7 @@ This front-end project of Boxtribute was bootstrapped with [Create React App](ht 4. [Testing](#testing) 5. [Conventions for file and folder organisation](#conventions-for-file-and-folder-organisation) 6. [About Apollo](#apollo) +7. [Types and GraphQL](#types-and-graphql) ## Development Set-Up From 20c97fbd18f2ddba1a8d627b393eeb1617a0dbca Mon Sep 17 00:00:00 2001 From: Felipe Henrich Date: Mon, 23 Dec 2024 17:34:20 -0300 Subject: [PATCH 2/3] docs: update FE docs and gql.tada ADR --- docs/adr/adr-typing-graphql.md | 18 +++++++++++------- front/README.md | 1 + 2 files changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/adr/adr-typing-graphql.md b/docs/adr/adr-typing-graphql.md index f2da7ebef..ac456690e 100644 --- a/docs/adr/adr-typing-graphql.md +++ b/docs/adr/adr-typing-graphql.md @@ -1,5 +1,7 @@ # ADR: Typing GraphQL Usage +Author: [Felipe](https://github.com/fhenrich33) + ## Status Implemented @@ -24,25 +26,27 @@ We will adopt `gql.tada` for typing GraphQL usage in our project. This decision - Well-documented and widely used in the community. - **Cons**: - Can be complex to configure and maintain, especially for large projects. - - Generated code can be verbose and difficult to navigate. - - Requires additional build steps, which can slow down the development process. + - Although we don't really need to manually check and review, generated code can be verbose and difficult to navigate. + - Requires additional build steps, which can slow down the development process. While infrequent, we must regenerate the types when the schema changes. + - Requires extra boilerplate code, as we need to pass generated types as generics to GraphQL functions. ### gql.tada - **Pros**: - - Simplifies the process of defining and using GraphQL types with a more intuitive API. + - Simplifies defining and using GraphQL types with a more intuitive API. - Provides better type inference, reducing the need for manual type annotations. - Lightweight and fast, with minimal impact on build times. - Easier to integrate into existing projects with less configuration overhead. + - A less impactful in the grand scheme of things but a nice bonus: orders of magnitude less generated code (a few thousand lines of code removed). - **Cons**: - Less mature and less widely adopted compared to GraphQL Code Generator. - - May have fewer plugins and integrations available. + - Nearly non-existent plugins and integrations available. ## Consequences By adopting `gql.tada`, we expect to achieve the following benefits: -- Improved developer experience with a more intuitive and streamlined API. +- Improved developer experience with a more intuitive and streamlined API. We can explore and experiment with queries from the code as we have type hints inside GraphQL strings. - Better type inference, leading to more accurate and maintainable code. - Faster development workflow with reduced build times. @@ -61,5 +65,5 @@ Overall, we believe that the benefits of adopting `gql.tada` outweigh the potent ## References -- [gql.tada Documentation](https://example.com/gql-tada-docs) -- [GraphQL Code Generator Documentation](https://example.com/graphql-code-generator-docs) +- [gql.tada Documentation](https://gql-tada.0no.co/) +- [GraphQL Code Generator Documentation](https://the-guild.dev/graphql/codegen) diff --git a/front/README.md b/front/README.md index a69bb0424..e873ed9b4 100644 --- a/front/README.md +++ b/front/README.md @@ -56,6 +56,7 @@ docker compose exec front pnpm format:write - no console.log - no debugger statements - no vars +- prefer types over interfaces - interfaces/type should start with "I" ## Note about pnpm and Docker From 035f5cb94ef41933cd6c518c309198949d5aa0af Mon Sep 17 00:00:00 2001 From: Felipe Henrich Date: Fri, 27 Dec 2024 15:50:56 -0300 Subject: [PATCH 3/3] docs: add reviewer to ADR Signed-off-by: Felipe Henrich --- docs/adr/adr-typing-graphql.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/adr/adr-typing-graphql.md b/docs/adr/adr-typing-graphql.md index ac456690e..c4721d465 100644 --- a/docs/adr/adr-typing-graphql.md +++ b/docs/adr/adr-typing-graphql.md @@ -2,6 +2,8 @@ Author: [Felipe](https://github.com/fhenrich33) +Reviewed by: [Philipp](https://github.com/pylipp) + ## Status Implemented