# @shane32/graphql-codegen-near-operation-file-plugin

> A plugin for [GraphQL Code Generator](https://www.graphql-code-generator.com/) that exports GraphQL documents from a generated file adjacent to where they were defined.

Latest version **1.0.7** (published 2025-12-05) · MIT license · 0 weekly downloads

## Install

```sh
npm install @shane32/graphql-codegen-near-operation-file-plugin
pnpm add @shane32/graphql-codegen-near-operation-file-plugin
yarn add @shane32/graphql-codegen-near-operation-file-plugin
bun add @shane32/graphql-codegen-near-operation-file-plugin
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2025-12-05 |
| First published | 2024-11-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Shane Krueger |
| Maintainers | shane32 |
| Keywords | example, typescript, npm, package, sample, boilerplate, starter, demo, cjs, esm |

## Links

- npm: https://www.npmjs.com/package/@shane32/graphql-codegen-near-operation-file-plugin
- Repository: https://github.com/Shane32/graphql-codegen-near-operation-file-plugin
- Issues: https://github.com/Shane32/graphql-codegen-near-operation-file-plugin/issues
- npm.io page: https://npm.io/package/@shane32/graphql-codegen-near-operation-file-plugin

## Alternatives

- [@openai/codex-sdk](https://npm.io/package/@openai/codex-sdk.md) — 731.4K weekly downloads
- [babel-plugin-transform-react-jsx](https://npm.io/package/babel-plugin-transform-react-jsx.md) — 565.0K weekly downloads
- [babel-helper-remove-or-void](https://npm.io/package/babel-helper-remove-or-void.md) — 508.5K weekly downloads
- [@pnpm/store-controller-types](https://npm.io/package/@pnpm/store-controller-types.md) — 186.9K weekly downloads
- [react-native-signature-canvas](https://npm.io/package/react-native-signature-canvas.md) — 155.6K weekly downloads

## Recent versions

- 1.0.7 (latest) — 2025-12-05
- 1.0.6 — 2025-12-05
- 1.0.5 — 2025-01-28
- 1.0.4 — 2024-12-02
- 1.0.3 — 2024-11-29
- 1.0.2 — 2024-11-29

## README

# @shane32/graphql-codegen-near-operation-file-plugin

A plugin for [GraphQL Code Generator](https://www.graphql-code-generator.com/) that exports GraphQL documents from a generated file adjacent to where they were defined.

[![NPM Version](https://img.shields.io/npm/v/%40shane32%2Fgraphql-codegen-near-operation-file-plugin)](https://www.npmjs.com/package/@shane32/graphql-codegen-near-operation-file-plugin)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Installation

```bash
npm install @shane32/graphql-codegen-near-operation-file-plugin
```

## Purpose

This plugin helps manage GraphQL operations in a more organized way by:
1. Creating `.g.ts` files adjacent to your GraphQL operation files
2. Exporting the generated document constants from these files
3. Maintaining proper relative imports from the main generated file

This approach keeps your GraphQL operations close to where they are used, making your codebase more maintainable and easier to navigate.

## Usage

Update your `codegen.ts` configuration file to include this plugin in your client preset:

```typescript
import type { CodegenConfig } from '@graphql-codegen/cli';

const config: CodegenConfig = {
  schema: 'schema.graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      plugins: ['@shane32/graphql-codegen-near-operation-file-plugin'],
      presetConfig: {
        gqlTagName: 'gql'
      }
    }
  }
};

export default config;
```

## Configuration

The plugin supports the following configuration options:

### `includeFileExtension`

- **Type:** `boolean`
- **Default:** `false`

When set to `true`, the generated import statements will include the file extension (e.g., `"../gql/graphql.ts"` instead of `"../gql/graphql"`).

### `fileHeader`

- **Type:** `string`
- **Default:** `"This file was automatically generated based on {filename}"`

Specifies a custom header comment to be added at the top of each generated file. The placeholder `{filename}` will be replaced with the name of the source file.

**Example:**

```typescript
const config: CodegenConfig = {
  schema: 'schema.graphql',
  documents: ['src/**/*.tsx'],
  generates: {
    './src/gql/': {
      preset: 'client',
      plugins: ['@shane32/graphql-codegen-near-operation-file-plugin'],
      config: {
        fileHeader: 'Auto-generated from {filename} - DO NOT EDIT'
      },
      presetConfig: {
        gqlTagName: 'gql'
      }
    }
  }
};
```

To disable the file header, set it to an empty string:

```typescript
config: {
  fileHeader: ''
}
```

## Example

Given the following structure:

```
src/
  components/
    UserProfile.tsx  // Contains a GraphQL query
  gql/
    graphql.ts      // Main generated file
```

If `UserProfile.tsx` contains:

```typescript
const GET_USER = gql`
  query GetUser($id: ID!) {
    user(id: $id) {
      id
      name
    }
  }
`;
```

The plugin will generate:

```
src/
  components/
    UserProfile.tsx
    UserProfile.g.ts  // Generated file with exports
  gql/
    graphql.ts
```

Where `UserProfile.g.ts` contains:

```typescript
// This file was automatically generated based on UserProfile.tsx
export { GetUserDocument } from "../gql/graphql";
```

## License

MIT

---
_Source: https://npm.io/package/@shane32/graphql-codegen-near-operation-file-plugin · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._