From d7bb3defc3c39a76f5434fdf9fe582526f7b709d Mon Sep 17 00:00:00 2001
From: Pujit Mehrotra <pujitm2009@gmail.com>
Date: Mon, 28 Oct 2024 13:51:38 -0400
Subject: [PATCH] doc(web): intro to using graphql

---
 web/CONTRIBUTING.md | 66 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)
 create mode 100644 web/CONTRIBUTING.md

diff --git a/web/CONTRIBUTING.md b/web/CONTRIBUTING.md
new file mode 100644
index 000000000..ec9ec676e
--- /dev/null
+++ b/web/CONTRIBUTING.md
@@ -0,0 +1,66 @@
+# Contribution Guide for unraid/api/web
+
+## Web Components
+
+For legacy compatibility, Unraid ships web components to the webgui. These components
+are written as Vue and turned into web components as a build step. By convention,
+Vue components that are built as top-level web components are suffixed with `*.ce.vue`
+for "**c**ustom **e**lement", which comes from the tool used for compilation: `nuxt-custom-elements`.
+
+Note: `nuxt-custom-elements` is currently pinned to a specific version because
+our build process breaks in later versions.
+
+## Graphql
+
+Unraid uses graphql to fetch & update server-related data. The web code uses `graphql-codegen` to
+sync graphql schemas & generate typescript types & utilities.
+
+During development, we often have `npm run codegen:watch` running in the background.
+
+When using graphql, import helper functions from `~/composables`, e.g.:
+
+```ts
+import { graphql } from "~/composables/gql/gql";
+```
+
+Use it to define type fragments, queries, and mutations, e.g.:
+
+```ts
+export const NOTIFICATION_FRAGMENT = graphql(/* GraphQL */ `
+  fragment NotificationFragment on Notification {
+    id
+    title
+    subject
+    description
+    importance
+    link
+    type
+    timestamp
+  }
+`);
+
+export const getNotifications = graphql(/* GraphQL */ `
+  query Notifications($filter: NotificationFilter!) {
+    notifications {
+      id
+      list(filter: $filter) {
+        ...NotificationFragment
+      }
+    }
+  }
+`);
+
+export const archiveNotification = graphql(/* GraphQL */ `
+  mutation ArchiveNotification($id: String!) {
+    archiveNotification(id: $id) {
+      ...NotificationFragment
+    }
+  }
+`);
+```
+
+Note the `/* GraphQL */` pragma. This enables syntax highlighting & type-sense for
+graphql stuff.
+
+You should define graphql-related snippets outside of your Vue components, so they're
+easier to re-use and independently validate.
\ No newline at end of file