npm package: @pretto/vite-graphql-codegen-loader
Description: Vite plugin for GraphQL code generation
Author: Ilya Siban
Latest version: 0.9.0

# @pretto/vite-graphql-codegen-loader

Vite plugin that generates TypeScript types and framework-specific Apollo hooks from GraphQL files during development and build.

## Features

- 🔥 **Hot reload** - Types and hooks generated on-the-fly
- 🎯 **Multiple schemas** - Support for multiple GraphQL schemas
- 📦 **Smart fragment support** - Automatic fragment loading with intelligent filtering (only includes used fragments)
- 🚀 **Multi-framework** - React Apollo hooks & Vue Apollo composables
- ⚡ **Vite optimized** - Fast builds with caching
- 🔄 **Auto-generated schema files** - Centralized `enums.ts` and `schema.d.ts` files regenerated on startup
- 🏗️ **Pre-generation** - All GraphQL files are pre-generated at build start (no import required)
- 🎯 **Optimized output** - Fragment tree-shaking ensures minimal file sizes

## Installation

```bash
yarn add @pretto/vite-graphql-codegen-loader
```

## Configuration

```typescript
// vite.config.ts
import { graphqlCodegenPlugin } from "@pretto/vite-graphql-codegen-loader";

export default defineConfig({
  plugins: [
    graphqlCodegenPlugin({
      framework: "react", // Required: "react", "vue", or "none"
      debug: true, // Enable debug logs in development
      schemas: {
        api: {
          url: "https://api.example.com/graphql",
          match: "*.api.graphql", // Files ending with .api.graphql use this schema
        },
        gateway: {
          file: "./src/schema.graphql",
          match: "*.gateway.graphql", // Files ending with .gateway.graphql use this schema
          fragmentsPaths: [
            "./src/fragments/**/*.graphql", // Glob patterns supported
          ],
        },
      },
      schemaTypesPath: "./src/types",
      scalars: {
        DateTime: "string",
        Date: "string",
        JSON: "any",
      },
    }),
  ],
});
```

## How it Works

### Automatic Pre-generation

The plugin automatically pre-generates TypeScript types for ALL GraphQL files in your project at build start. This means:
- ✅ You don't need to import GraphQL files before their types are available
- ✅ No "chicken-and-egg" problem with circular dependencies
- ✅ All hooks and types are immediately available for use

### Smart Fragment Filtering

When using fragments, the plugin intelligently analyzes your GraphQL operations and only includes the fragments that are actually used:
- 📉 Smaller generated files (only necessary fragments included)
- 🔍 Recursive fragment resolution (nested fragments are properly detected)
- ⚡ Better performance with minimal bundle size

## Usage

Create GraphQL files with `.api.graphql` or `.gateway.graphql` extensions:

```graphql
# queries.api.graphql
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

mutation UpdateUser($input: UserInput!) {
  updateUser(input: $input) {
    id
    name
  }
}
```

### With Fragments

```graphql
# user.gateway.graphql
query GetUserWithDetails {
  user {
    ...UserDetails  # Only this fragment will be included
  }
}

# fragments.graphql (configured in fragmentsPaths)
fragment UserDetails on User {
  id
  name
  profile {
    ...ProfileInfo  # Nested fragment also included
  }
}

fragment ProfileInfo on Profile {
  avatar
  bio
}

fragment UnusedFragment on User {  # This won't be included in generated file
  someField
}
```

The plugin automatically generates:

### Centralized Schema Files (per schema)
- `src/types/api/enums.ts` - All GraphQL enums from the API schema
- `src/types/api/schema.d.ts` - All TypeScript types from the API schema
- `src/types/gateway/enums.ts` - All GraphQL enums from the Gateway schema
- `src/types/gateway/schema.d.ts` - All TypeScript types from the Gateway schema

These files are regenerated on every Vite startup, ensuring they stay up-to-date with the latest schema changes. You can safely add them to `.gitignore`.

### Per-Query Files

```typescript
// queries.api.graphql.d.ts - TypeScript types
export type GetUserQuery = { ... }
export type UpdateUserMutation = { ... }

// queries.api.graphql - JavaScript runtime
export const GetUserDocument = gql`...`
export function useGetUserQuery(options) { ... } // React hooks or Vue composables based on framework
export function useUpdateUserMutation(options) { ... }
```

Import and use:

#### React
```typescript
import { useGetUserQuery, useUpdateUserMutation } from "./queries.api.graphql";

function UserProfile({ userId }: { userId: string }) {
  const { data, loading } = useGetUserQuery({ variables: { id: userId } });
  const [updateUser] = useUpdateUserMutation();

  // TypeScript knows the exact shape of data!
}
```

#### Vue
```typescript
import { useGetUserQuery, useUpdateUserMutation } from "./queries.api.graphql";

export default {
  setup() {
    const { result, loading } = useGetUserQuery({ id: userId });
    const { mutate: updateUser } = useUpdateUserMutation();

    // TypeScript knows the exact shape of data!
    return { result, loading, updateUser };
  }
}
```

## Configuration Options

| Option            | Type                           | Default       | Description                                   |
| ----------------- | ------------------------------ | ------------- | --------------------------------------------- |
| `framework`       | `"react" \| "vue" \| "none"`   | **required**  | Target framework for hook/composable generation |
| `debug`           | `boolean`                      | `false`       | Enable debug logging                         |
| `schemas`         | `Record<string, SchemaConfig>` | `{}`          | Schema configurations                        |
| `schemaTypesPath` | `string`                       | `"src/types"` | Path for centralized schema files           |
| `scalars`         | `Record<string, string>`       | `{}`          | Custom scalar type mappings                 |

### Schema Configuration

```typescript
interface SchemaConfig {
  url?: string;             // Remote GraphQL endpoint
  file?: string;            // Local schema file
  match?: string;           // File pattern to match (e.g., "*.api.graphql")
  fragmentsPaths?: string[]; // Fragment files to include (supports glob patterns)
}
```

### Framework Options

- **`react`** (default): Generates React Apollo hooks (`useQuery`, `useMutation`, etc.)
- **`vue`**: Generates Vue Apollo composables (`useQuery`, `useMutation`, etc.) 
- **`none`**: Only generates TypeScript types without framework-specific hooks

## Development

```bash
# Install dependencies
yarn install

# Development mode
yarn dev

# Build
yarn build
```

## License

MIT