# @pawells/nx-graphql

[![CI](https://github.com/PhillipAWells/workspace/actions/workflows/ci.yml/badge.svg)](https://github.com/PhillipAWells/workspace/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/@pawells/nx-graphql.svg)](https://www.npmjs.com/package/@pawells/nx-graphql)
[![Node](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

NX workspace executors for GraphQL development, providing tools to compile NestJS GraphQL decorators to SDL and run code generation.

## Description

`@pawells/nx-graphql` provides two executors for NX monorepos:

- **`build-schema`** — Compiles NestJS resolver classes (decorated with `@Resolver`, `@Query`, `@Mutation`) into GraphQL SDL (.graphql files) using NestJS's GraphQLSchemaFactory.
- **`codegen`** — Runs graphql-codegen with a preset plugin stack (@pawells/graphql-codegen-ts) to generate fully-typed TypeScript code from GraphQL operations.

Both executors enforce workspace-relative paths and validate all inputs to prevent directory traversal attacks.

## Requirements

- NX >=22.0.0. This package's `@nx/devkit` dependency (`^23.0.1`) matches this workspace's own NX
  version (`23.1.0`).
- NestJS 11.x with @nestjs/graphql 13.x+
- Node.js 22.x or higher
- TypeScript ~6.0.x
- `@pawells/graphql-codegen-ts` (peer dependency, `^3.1.0`) — required by the `codegen` executor's
  default plugin stack unless you override `plugins` to exclude it

## Installation

```bash
yarn add -D @pawells/nx-graphql
```

## Quick Start

### Configure build-schema executor

Add the executor to your project's `project.json`:

```json
{
	"targets": {
		"build-schema": {
			"executor": "@pawells/nx-graphql:build-schema",
			"options": {
				"resolversModule": "src/graphql/resolvers",
				"schemaFile": "dist/schema.graphql"
			}
		}
	}
}
```

Run it:

```bash
yarn nx run your-project:build-schema
```

### Configure codegen executor

Add the executor to your project's `project.json`:

```json
{
	"targets": {
		"codegen": {
			"executor": "@pawells/nx-graphql:codegen",
			"options": {
				"schemaFile": "dist/schema.graphql",
				"documentsGlob": "src/**/*.graphql",
				"outputFile": "src/generated/graphql.ts"
			}
		}
	}
}
```

Run it:

```bash
yarn nx run your-project:codegen
```

Or in watch mode:

```bash
yarn nx run your-project:codegen --watch
```

## API Reference

### build-schema

Compiles NestJS resolver classes to GraphQL SDL.

**Options:**

| Option | Type | Required | Description |
|--------|------|----------|-------------|
| `resolversModule` | string | Yes | Path to module that exports an array of NestJS resolver classes (relative to workspace root). Module must export a `GraphQLSchema` named export containing the resolver classes. |
| `schemaFile` | string | Yes | Output path for the generated .graphql SDL file (relative to workspace root). |
| `project` | string | No | NX project name for context (defaults to inferred from project.json). |

**Example:**

```json
{
	"targets": {
		"build-schema": {
			"executor": "@pawells/nx-graphql:build-schema",
			"options": {
				"resolversModule": "src/graphql/resolvers/index.ts",
				"schemaFile": "dist/schema.graphql"
			}
		}
	}
}
```

### codegen

Runs graphql-codegen with preset plugins for TypeScript code generation.

**Options:**

| Option | Type | Required | Default | Description |
|--------|------|----------|---------|-------------|
| `schemaFile` | string | Yes | - | Path to .graphql schema file (relative to workspace root or glob pattern). |
| `documentsGlob` | string | Yes | - | Glob pattern for GraphQL operation files (e.g., `src/**/*.graphql`). |
| `outputFile` | string | Yes | - | Output .ts file path for generated code (relative to workspace root). |
| `target` | string | No | `typescript` | Target platform. Currently only `typescript` is supported. |
| `plugins` | string[] | No | See below | Override default plugin list. |
| `config` | object | No | See below | Merge custom settings into default codegen config. |
| `watch` | boolean | No | `false` | Run in watch mode for development. |

**Default Plugins:**

- `typescript` — Generate TypeScript types from schema
- `typescript-operations` — Generate operation helpers
- `typed-document-node` — Generate typed document nodes
- `typescript-apollo-client-helpers` — Apollo client helpers
- `@pawells/graphql-codegen-ts` (`^3.1.0`) — Custom plugin for enhanced type generation. This is a
  `peerDependency` of `@pawells/nx-graphql` (see [Requirements](#requirements)) — install it
  separately in the consuming project, or override `plugins` to exclude it if it isn't needed.

**Default Config:**

```typescript
{
	namingConvention: 'keep',
	immutableTypes: false
}
```

**Example:**

```json
{
	"targets": {
		"codegen": {
			"executor": "@pawells/nx-graphql:codegen",
			"options": {
				"schemaFile": "dist/schema.graphql",
				"documentsGlob": "src/**/*.graphql",
				"outputFile": "src/generated/graphql.ts",
				"config": {
					"namingConvention": "pascalCase"
				}
			}
		}
	}
}
```

## License

MIT — See [LICENSE](./LICENSE) for details.