Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/chnapy/ts-gql-plugin
TypeScript Language Service Plugin for GraphQL DocumentNode typing
https://github.com/chnapy/ts-gql-plugin
codegen graphql language-service typescript
Last synced: 29 days ago
JSON representation
TypeScript Language Service Plugin for GraphQL DocumentNode typing
- Host: GitHub
- URL: https://github.com/chnapy/ts-gql-plugin
- Owner: Chnapy
- License: mit
- Created: 2022-06-08T19:50:46.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2023-02-06T02:22:55.000Z (almost 2 years ago)
- Last Synced: 2024-10-03T08:15:57.645Z (about 2 months ago)
- Topics: codegen, graphql, language-service, typescript
- Language: TypeScript
- Homepage:
- Size: 107 MB
- Stars: 8
- Watchers: 2
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# ts-gql-plugin
[](https://www.npmjs.com/package/ts-gql-plugin)
[](https://github.com/chnapy/ts-gql-plugin/blob/master/LICENSE)
[](https://github.com/Chnapy/ts-gql-plugin/actions/workflows/ci.yml)
A [TypeScript Language Service Plugin](https://github.com/Microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin) adding GraphQL DocumentNode typing.
---
- :triangular_ruler: Typed GraphQL operations
- :x: No code generation
- :toolbox: [CLI support](#cli)
- :pencil: Editor support with autocomplete / quick-infos / "go to definition"
- :link: Multi-projects support
---
Using `gql` from `graphql-tag` gives you generic `DocumentNode` type, which does not allow you to manipulate typed requested data when used with Apollo for example. To resolve that you can use [code generators](https://www.graphql-code-generator.com/) creating typescript code with correct types, but it adds lot of generated code with risk of obsolete code and bad development comfort.
`ts-gql-plugin` is meant to solve this issue, by replacing most of code generation by compiler-side typing, using [TypeScript Language Service Plugin](https://github.com/Microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin).
## Get started
Install with your package manager
```
yarn add -D ts-gql-plugin
npm install -D ts-gql-plugin
```
Then add plugin to your `tsconfig.json`
```jsonc
{
"compilerOptions": {
"plugins": [
{
"name": "ts-gql-plugin"
}
]
}
}
```
Since this plugin uses [graphql-config](https://www.graphql-config.com/docs/user/user-introduction) you should add a config file targeting your GraphQL schema.
```jsonc
// .graphqlrc
{
"schema": "./schema.graphql"
}
```
Depending on how you want to use it:
- [with your editor](#vscode)
- [with a CLI](#cli)
To work this plugin requires a specific syntax:
```ts
gql(`...`);
```
A concrete example:
```ts
import { gql } from 'graphql-tag';
// TypedDocumentNode<{ user, users }, { id }>
gql(`
query User1($id: ID!) {
user(id: $id) {
id
name
}
users {
id
}
}
`);
```
> You can find more examples in [example/](./example/).
## Configuration
Configuration can be done at 2 levels: in `tsconfig.json` and in `graphql-config` file.
### tsconfig.json
Checkout config type & default values in [plugin-config.ts](./src/plugin-config.ts).
> Log level `'debug'` writes log files into `ts-gql-plugin-logs` directory. When running by VSCode this directory can be hard to find, checkout TSServer logs where files paths are logged.
> These logs contain updated code with hidden types generated by plugin.
### graphql-config
You can add project-related configuration using extension `"ts-gql"`.
```jsonc
// .graphqlrc
{
"schema": "./schema.graphql",
"extensions": {
"ts-gql": {
"codegenConfig": {
"defaultScalarType": "unknown",
"scalars": {
"DateTime": "String"
}
}
}
}
}
```
Checkout config type in [extension-config.ts](./src/extension-config.ts).
### Multi-projects configuration
If you should handle multiple GraphQL projects (= multiple schemas), define projects into your graphql-config file.
```jsonc
// .graphqlrc
{
"projects": {
"Catalog": {
"schema": "./catalog/schema.graphql"
},
"Channel": {
"schema": "./channel/schema.graphql"
}
}
}
```
> graphql-config extensions should not be added in root level, but in each projects
Then into your plugin config define project name regex, following your own constraints.
This regex is used to extract project name from operations.
```jsonc
{
"compilerOptions": {
"plugins": [
{
"name": "ts-gql-plugin",
"projectNameRegex": "([A-Z][a-z]*)"
}
]
}
}
```
Finally, create your operations following regex constraints.
```ts
gql(`
query CatalogProduct($id: ID!) {
product(id: $id) {
id
name
}
}
`);
gql(`
query ChannelItem($id: ID!) {
item(id: $id) {
id
name
}
}
`);
```
With this kind of configuration, each of these operations match corresponding project, so its own schema.
## Use of generated types
Even if this plugin allows you to avoid code generation, you may want to use generated types.
For this kind of use a global module is exposed. Named `TsGql`, you can access from it every generated types.
```ts
gql(`
query ProfileAuth {
...
}
`);
const authInput: TsGql.ProfileAuthInput = {
username,
password,
};
```
To use `TsGql` in a file without `gql` uses, you should put a `@ts-gql` tag with the project name you want to use, anywhere in your file.
This is the only way for `ts-gql-plugin` to know without performance impact when you want to access generated types.
```ts
// @ts-gql Profile
const authInput: TsGql.ProfileAuthInput = {
username,
password,
};
```
### Enums
Since enums persist on runtime, they cannot be exposed by `ts-gql-plugin`. To solve this issue, types are generated instead of enums.
```gql
# schema-profile.graphql
enum OAuthProvider {
GOOGLE
FACEBOOK
}
```
So this enum can be used like that:
```ts
// @ts-gql Profile
const provider: TsGql.ProfileOAuthProvider = 'GOOGLE';
```
Also you may want to list every possible values from a GraphQL enum, like to be used with HTML `` elements.
To handle this case `ts-gql-plugin` exposes an utility type, `UnionToArray`, which allows to create a tuple from an union with a strong constraint forcing to give every possible values.
```ts
import { UnionToArray } from 'ts-gql-plugin';
const providerList: UnionToArray = [
'GOOGLE',
'FACEBOOK',
];
```
## VSCode
You should [set your workspace's version of TypeScript](https://code.visualstudio.com/docs/typescript/typescript-compiling#_using-the-workspace-version-of-typescript), which will load plugins from your tsconfig.json file.
```bash
# Open VSCode command palette with Shift + Ctrl/Cmd + P
> TypeScript: Select TypeScript version...
> Use Workspace Version
```
After a config change you may have to restart TS server.
```bash
> TypeScript: Restart TS server
```
### TS server logs
You can see plugin logs openning TS server log
```bash
> TypeScript: Open TS server log
```
Then search for `ts-gql-plugin` occurences.
> To see more logs consider passing `logLevel` to `'verbose'` or `'debug'` !
### GraphQL extension
To have highlighting between other features, you can use [GraphQL extension](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql) for VSCode.
> Since this extension does not handle multi-projects configurations you may want to use [GraphQL: Syntax Highlighting extension](https://marketplace.visualstudio.com/items?itemName=GraphQL.vscode-graphql-syntax) instead. This extension only gives syntax highlighting.
## CLI
Because of [Language Service design limitations](https://github.com/microsoft/TypeScript/wiki/Writing-a-Language-Service-Plugin#whats-a-language-service-plugin) `tsc` does not load plugins. So building or type-checking your files using CLI cannot use `ts-gql-plugin`.
As a workaround you can use [`tsc-ls`](https://github.com/chnapy/tsc-ls), a compiler handling language service plugins.
## Caveats & constraints
- Tagged template expressions are not handled, because of [type-safety issue](https://github.com/microsoft/TypeScript/issues/33304)
```ts
// not handled, waiting for TypeScript #33304
gql`
query {...}
`;
```
- since Language Service feature is limited concerning types overriding, solution was to parse & override text source files during TS server process, which is subobtimal for performances (best solution would have been to work with AST)
- as described upper, CLI is not handled out-of-box because of `tsc` design limitations
## Benchmark
You can see performance impact using `ts-gql-plugin`: https://chnapy.github.io/ts-gql-plugin/dev/bench
Keep in mind that this benchmark shows the "worst case": it's done using a [tsconfig](./example/tsconfig.benchmark1.json) including only a single [index.ts](./example/index.ts) file with only `gql` operations, so plugin use is overrepresented.
## Changelog
Checkout [releases](https://github.com/Chnapy/ts-gql-plugin/releases) to see each version changes.
## Contribute
### Issues
Please fill issues with reproductible steps & relevant logs (check VSCode [TS server logs](#ts-server-logs)).
### Work on this project - get started
This project uses [devcontainers](https://code.visualstudio.com/docs/remote/containers) and is made to work on it.
Run checkers
```
yarn c:type
yarn c:lint
yarn c:test
```
Build
```
yarn build
```