diff --git a/README.md b/README.md index 36855b54..7a8d275f 100644 --- a/README.md +++ b/README.md @@ -46,6 +46,21 @@ server for TypeScript, the documentation for each API should pop up in your edit Code Editor showing GraphQL queries being edited with gql.tada and GraphLSP +## đź’™ [Sponsors](https://github.com/sponsors/urql-graphql) + + + + + + +
BigCommerce
BigCommerce		WunderGraph
WunderGraph
+ + + + + +
BeatGig
BeatGig
+ ## 📦 [Releases](https://github.com/0no-co/gql.tada/releases) If you'd like to get involved, [check out our Contributor's guide.](https://github.com/0no-co/gql.tada/blob/main/CONTRIBUTING.md) diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts index 1b198bb9..05696dc0 100644 --- a/website/.vitepress/config.mts +++ b/website/.vitepress/config.mts @@ -91,7 +91,7 @@ export default defineConfig({ items: [ { text: 'Introduction', - link: '/', + link: '/get-started/', }, { text: 'Installation', diff --git a/website/.vitepress/theme/style.css b/website/.vitepress/theme/style.css index 2273d424..f92e44b5 100644 --- a/website/.vitepress/theme/style.css +++ b/website/.vitepress/theme/style.css @@ -422,3 +422,23 @@ :root .VPContent .vp-doc .vp-code-group .tabs label { line-height: 2.7rem; } + +:root .VPContent .sponsor-item { + display: flex; + flex-direction: row; + align-items: center; + background: var(--vp-c-bg-soft); + border-radius: 8px; + gap: 2em; + padding: 1em 2em; +} + +:root .VPContent .sponsor-item > img { + width: 4rem; + height: 4rem; +} + +:root .VPContent .sponsor-item > a { + font-size: 1.4em; + color: var(--vp-c-text-1); +} diff --git a/website/get-started/index.md b/website/get-started/index.md new file mode 100644 index 00000000..d3e16e5a --- /dev/null +++ b/website/get-started/index.md @@ -0,0 +1,164 @@ +--- +title: Introduction +--- + +# Introduction + +> [!NOTE] +> +> `gql.tada`’s documentation is still a work in progress. +> If you have any feedback, feel free to let us know what you’d like to see explained or changed. + +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. + +`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. + +[Read on on the “Installation” page, to get started! 🪄](./installation) + +### A demo in 128 seconds + + + +## How does it work? + +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. + +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 twoslash +// @filename: graphql-env.d.ts +export type introspection = { + "__schema": { + "queryType": { + "name": "Query" + }, + "mutationType": null, + "subscriptionType": null, + "types": [ + { + "kind": "OBJECT", + "name": "Query", + "fields": [ + { + "name": "hello", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "args": [] + }, + { + "name": "world", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "args": [] + } + ], + "interfaces": [] + }, + { + "kind": "SCALAR", + "name": "String" + } + ], + "directives": [] + } +}; + +import * as gqlTada from 'gql.tada'; + +declare module 'gql.tada' { + interface setupSchema { + introspection: introspection + } +} + +// @filename: index.ts +import './graphql-env.d.ts'; +// ---cut--- +import { graphql } from 'gql.tada'; + +const fragment = graphql(` + fragment HelloWorld on 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. + +## Which GraphQL query language features are supported? + +`gql.tada` supports the entire GraphQL query language syntax, and aims to support all +type features that are relevant to GraphQL clients that support typed GraphQL documents +(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”](./started/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. diff --git a/website/index.md b/website/index.md index 6571cdad..e910e09d 100644 --- a/website/index.md +++ b/website/index.md @@ -1,164 +1,48 @@ --- -title: Introduction +layout: home + +hero: + name: gql.tada + tagline: Magical GraphQL query engine for TypeScript + actions: + - theme: brand + text: Get Started + link: /get-started/ + - theme: alt + text: View on GitHub + link: https://github.com/0no-co/gql.tada --- -# Introduction +`gql.tada` is a GraphQL document authoring library, inferring the result and variables types +of GraphQL queries and fragments in the TypeScript type system. It derives the types for your +GraphQL queries on the fly allowing you to write type-safe GraphQL documents quickly. -> [!NOTE] -> -> `gql.tada`’s documentation is still a work in progress. -> If you have any feedback, feel free to let us know what you’d like to see explained or changed. +In short, `gql.tada`, -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. +- parses your GraphQL documents in the TypeScript type system +- uses your introspected schema and scalar configuration to derive a schema +- maps your GraphQL queries and fragments with the schema to result and variables types +- creates fragment masks and enforces unwrapping fragments gradually -`gql.tada` as a project was started to answer the question: -“Why can’t we teach TypeScript to understand the GraphQL query language?” +Since this is all done in the TypeScript type system and type checker, this all happens +while you edit your GraphQL front-end code and is always accurate. -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. +In short, **with `gql.tada` and [GraphQLSP](https://github.com/0no-co/graphqlsp) you get on-the-fly, automatically typed GraphQL documents +with full editor feedback, auto-completion, and type hints!** -[Read on on the “Installation” page, to get started! 🪄](./get-started/installation) +## Sponsors -### A demo in 128 seconds + - + -## How does it work? - -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. - -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 twoslash -// @filename: graphql-env.d.ts -export type introspection = { - "__schema": { - "queryType": { - "name": "Query" - }, - "mutationType": null, - "subscriptionType": null, - "types": [ - { - "kind": "OBJECT", - "name": "Query", - "fields": [ - { - "name": "hello", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "args": [] - }, - { - "name": "world", - "type": { - "kind": "SCALAR", - "name": "String", - "ofType": null - }, - "args": [] - } - ], - "interfaces": [] - }, - { - "kind": "SCALAR", - "name": "String" - } - ], - "directives": [] - } -}; - -import * as gqlTada from 'gql.tada'; - -declare module 'gql.tada' { - interface setupSchema { - introspection: introspection - } -} - -// @filename: index.ts -import './graphql-env.d.ts'; -// ---cut--- -import { graphql } from 'gql.tada'; - -const fragment = graphql(` - fragment HelloWorld on 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. - -## Which GraphQL query language features are supported? - -`gql.tada` supports the entire GraphQL query language syntax, and aims to support all -type features that are relevant to GraphQL clients that support typed GraphQL documents -(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”](./get-started/installation), will show you how to install and set up `gql.tada` and `@0no-co/graphqlsp`. - -[The following page, “Writing GraphQL”](./get-started/writing-graphql), will show you how to use `gql.tada` and write GraphQL documents with it. +