From 9bf4e24b3ce6c482fa193fc2751ed9201b3147a0 Mon Sep 17 00:00:00 2001 From: Phil Pluckthun Date: Mon, 15 Jan 2024 20:46:32 +0000 Subject: [PATCH] docs: Add Introduction page content --- website/src/content/docs/index.mdx | 96 ++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/website/src/content/docs/index.mdx b/website/src/content/docs/index.mdx index 8f14f7a7..05fac50f 100644 --- a/website/src/content/docs/index.mdx +++ b/website/src/content/docs/index.mdx @@ -1,3 +1,99 @@ --- title: Introduction --- + +The `gql.tada` project aims to improve the experience of writing and using GraphQL +with TypeScript on the client-side by providing more feedback when writing GraphQL, +and reducing friction between TypeScript and GraphQL. + +The project currently contains two installable modules: +- `gql.tada`, the package providing typings and the runtime API as a library, +- `@0no-co/graphqlsp`, a TypeScript Language Service plugins for editor feedback and integration. + +`gql.tada` as a project was started to answer the question: +“Why can’t we teach TypeScript to understand the GraphQL query language?” + +Once `gql.tada` is set up, we write our GraphQL queries in pure TypeScript, +our queries automatically infer their types, and our editor introspects our +GraphQL schema and provides immediate feedback, auto-completion, diagnostics, +and GraphQL type hints.
+This all happens on-the-fly in TypeScript. + +### A demo in 128 seconds + + + +## How does it work? + +As you start your editor, `@0no-co/graphqlsp` is started as a TypeScript Language Service +plugin, which allows it to integrate with the same process that provides your editor +with type hints, diagnostics, and auto-completions; the TypeScript language server +process. + +During this time, `@0no-co/graphqlsp` will retrieve your GraphQL schema, find GraphQL +documents and provide added diagnostics and features using your schema information. +It will also output an introspection file for `gql.tada` to use. + +The GraphQL documents, written with `gql.tada` will be parsed — all inside TypeScript +typings — and are combined with the introspection information that `@0no-co/graphqlsp` +provides to create typings for GraphQL result and variables types. + +This means, all we see in our code is the plain GraphQL documents with no annotations or distractions: + +```ts title="example.ts" +import { graphql } from 'gql.tada'; + +const fragment = graphql(` + fragment HelloWorld extends Query { + hello + world + } +`); + +const query = graphql(` + query HelloQuery { + hello + ...HelloWorld + } +`, [fragment]); +``` + +## How does it compare to other solutions? + +Typically, when integrating client-side GraphQL code with TypeScript, other solutions +will generate typings files for GraphQL documents. + +This means that you’ll need to run a persistent and separate process that watches your +TypeScript files, and generates more auto-generated TypeScript files containing your +GraphQL types. + +This leads to the additional friction of having additional generated files around and +causing the TypeScript process to having to watch your files, error on changes, picking +up the newly generated files, and updating the checks. In other words, these tools cause +a “split” between what TypeScript sees, what you see, and what the code generator sees. + +`gql.tada` instead takes the approach of generating the typings fully in TypeScript to +eliminate this “split experience”, reducing friction. All while writing actual GraphQL +queries, rather than an object-syntax, which is only an approximation of GraphQL queries. + +## What GraphQL syntax is supported? + +We aim to support all of the GraphQL syntax, and further support type features that +are relevant to all GraphQL clients that support typed GraphQL (via `TypedDocumentNode`s). + +Currently, the list of supported features is: + +- Mapping selection sets mapping to object-like types to TypeScript object types +- Grouping type mappings of possible types for interfaces and unions +- `@defer`, `@skip`, and `@include` directives switching fields and fragments to be optional +- resolving inline fragment and fragment spreads in documents +- inferring the type of `__typename` fields +- resolving types of custom scalars from a configuration + +## Next steps + +[The next page, “Installation”](../installation/), will show you how to install and set up `gql.tada` and `@0no-co/graphqlsp`. + +[The following page, “Writing GraphQL”](../writing-graphql/), will show you how to use `gql.tada` and write GraphQL documents with it.