diff --git a/llm-docs/getting-started/quick-start.md b/llm-docs/getting-started/quick-start.md index 790e5152..07f61bef 100644 --- a/llm-docs/getting-started/quick-start.md +++ b/llm-docs/getting-started/quick-start.md @@ -14,6 +14,13 @@ npm init --yes && npm pkg set type="module" ## Install dependencies +> **TIP:** +> If you use an AI coding agent, install the Grats skill to make it a Grats expert: +> +> ```bash +> npx skills add captbaritone/grats +> ``` + Grats can be used with many different GraphQL servers, but this example uses `graphql-yoga`. ```bash diff --git a/skills/grats/SKILL.md b/skills/grats/SKILL.md new file mode 100644 index 00000000..ba839634 --- /dev/null +++ b/skills/grats/SKILL.md @@ -0,0 +1,101 @@ +--- +name: grats +description: Build GraphQL servers by annotating TypeScript code with docblock tags like @gqlType and @gqlField. Use when writing, reviewing, or refactoring GraphQL resolvers in a project that uses Grats, or when the user mentions Grats, @gqlType, @gqlField, or similar docblock tags. +license: MIT +metadata: + author: grats + version: "1.0.0" +--- + +# Grats + +Grats extracts a GraphQL schema from TypeScript code. Instead of writing a separate schema file, you annotate your TypeScript types and functions with docblock tags like `/** @gqlType */` and `/** @gqlField */`. Grats then generates an executable GraphQL schema and a `.graphql` file as a build step. + +## Documentation + +Grats ships comprehensive documentation in its npm package at `node_modules/grats/llm-docs/`. Read these files for detailed reference: + +- **Getting started**: `node_modules/grats/llm-docs/getting-started/quick-start.md` +- **All docblock tags**: `node_modules/grats/llm-docs/docblock-tags.md` +- **Resolver patterns**: `node_modules/grats/llm-docs/resolvers.md` +- **Configuration**: `node_modules/grats/llm-docs/getting-started/configuration.md` +- **CLI usage**: `node_modules/grats/llm-docs/getting-started/cli.md` + +## How to Write Grats Code + +Write idiomatic TypeScript — classes, type aliases, interfaces, functions — whatever style suits the project. Then add docblock tags (`/** @gqlType */`, `/** @gqlField */`, etc.) to the constructs you want to expose in the GraphQL schema. Grats infers the GraphQL meaning from your TypeScript types. If something is ambiguous or incorrect, Grats will give you a helpful error message telling you how to fix it. + +You do not need to learn a specific pattern or DSL. Just write the TypeScript code that feels natural and annotate it. Grats supports classes, interfaces, type aliases, functions, static methods, and more — use whatever fits. + +Annotate the project's existing model types and data classes directly rather than creating a separate "resolver" layer with new wrapper types. Grats is designed to work with your real domain types — add `@gqlType` and `@gqlField` to the types you already have. + +### Docblock Tags + +Each tag maps directly to a GraphQL schema construct. Tags must use `/**` (two asterisks). + +| Tag | Purpose | +| ----------------------- | ---------------------------------------------- | +| `@gqlType` | Define a GraphQL object type | +| `@gqlField` | Define a field on a type | +| `@gqlQueryField` | Define a field on the root `Query` type | +| `@gqlMutationField` | Define a field on the root `Mutation` type | +| `@gqlSubscriptionField` | Define a field on the root `Subscription` type | +| `@gqlInterface` | Define a GraphQL interface | +| `@gqlUnion` | Define a GraphQL union | +| `@gqlEnum` | Define a GraphQL enum | +| `@gqlScalar` | Define a custom GraphQL scalar | +| `@gqlInput` | Define a GraphQL input type | +| `@gqlContext` | Mark a type as the GraphQL context object | + +For detailed documentation on each tag, read the files in `node_modules/grats/llm-docs/docblock-tags/`. + +### Configuration + +Grats is configured under the `"grats"` key in `tsconfig.json`: + +```json +{ + "grats": { + "nullableByDefault": true, + "importModuleSpecifierEnding": ".js" + } +} +``` + +For all options, read `node_modules/grats/llm-docs/getting-started/configuration.md`. + +### Running Grats + +```bash +npx grats # Generate schema +npx grats --watch # Watch mode +npx grats --fix # Auto-fix common issues +``` + +Rerun Grats after any change that is expected to modify the GraphQL schema (adding or changing types, fields, arguments, etc.) to regenerate the schema files. + +The project may have its own script or workflow for running Grats (e.g., an npm script, a build step, or a watch task). Check the project's `package.json` scripts and documentation first, and defer to the project's approach if one exists. + +### Working with Generated Files + +Grats generates `schema.ts` and `schema.graphql`. These files should be **committed to the repository** — they are expected to be checked in so that schema changes are visible in code review and accessible to other tools. Do not add them to `.gitignore`. + +Do not manually edit generated files or run autoformatters on them. If CI fails with a "schema out of date" error, rerun Grats and commit the updated files. + +For more details, read `node_modules/grats/llm-docs/guides/workflows.md`. + +## Things You Might Not Expect + +- **All fields are nullable by default** per GraphQL best practices — `string` produces `String`, not `String!`. Prefer keeping fields nullable. `@killsParentOnException` can make a field non-null, but use it with caution: if the resolver throws, the error propagates up and nulls out the nearest nullable parent, increasing the blast radius. For projects that want clients to see which fields are _expected_ to be non-null absent errors, enable `strictSemanticNullability` in the Grats config. See `node_modules/grats/llm-docs/resolvers/nullability.md` and `node_modules/grats/llm-docs/guides/strict-semantic-nullability.md`. +- **Root types are auto-created.** `@gqlQueryField` automatically creates the `Query` type — you don't need to define it separately. See `node_modules/grats/llm-docs/docblock-tags/root-fields.md`. +- **`@deprecated` JSDoc tag auto-maps** to the GraphQL `@deprecated` directive. No need for `@gqlAnnotate`. See `node_modules/grats/llm-docs/resolvers/deprecated.md`. +- **Generics are supported.** `Connection` auto-materializes as `UserConnection` in the schema. See `node_modules/grats/llm-docs/guides/generics.md`. +- **Derived context values** enable dependency injection: a function annotated with `@gqlContext` that takes the root context and returns a new type creates an injectable value. See `node_modules/grats/llm-docs/docblock-tags/context.md`. + +## Additional Documentation + +For advanced topics, read the files in `node_modules/grats/llm-docs/`: + +- **Guides**: `guides/` — subscriptions, dataloader, generics, incremental migration, workflows, permissions, connection spec +- **FAQ**: `faq/` — design principles, limitations, how Grats works +- **Examples**: `examples/` — Apollo Server, Yoga, Next.js, production app patterns diff --git a/website/docs/01-getting-started/01-quick-start.mdx b/website/docs/01-getting-started/01-quick-start.mdx index d527439c..e3880f0b 100644 --- a/website/docs/01-getting-started/01-quick-start.mdx +++ b/website/docs/01-getting-started/01-quick-start.mdx @@ -14,6 +14,15 @@ npm init --yes && npm pkg set type="module" ## Install dependencies +:::tip +If you use an AI coding agent, install the Grats skill to make it a Grats expert: + +```bash +npx skills add captbaritone/grats +``` + +::: + Grats can be used with many different GraphQL servers, but this example uses `graphql-yoga`. ```bash