ql_gen 0.1.8

Generate strongly typed Dart GraphQL client helpers from schema files, including models, selectors, and operation builders for queries and mutations.

ql_gen

ql_gen generates typed Dart GraphQL helpers from schema files. It parses a GraphQL schema and produces Dart models plus operation builders to simplify query and mutation execution in client apps.

Features

• Generate Dart types from GraphQL schema objects.
• Generate query and mutation helpers.
• Generate selectors/field builders for typed request construction.
• CLI support for schema-to-file generation.
• build_runner integration: auto-generates Dart files from .graphql/.gql sources.

Install

Add ql_gen as a dev dependency together with build_runner:

dev_dependencies:
  ql_gen: ^0.1.7
  build_runner: ^2.0.0

Then run:

dart pub get

build_runner usage

Place your schema file anywhere in the project (e.g. lib/schema.graphql or lib/schema.gql). Then run:

dart run build_runner build

This produces a .dart file next to each schema file (lib/schema.graphql.dart or lib/schema.gql.dart).

To watch for changes and rebuild automatically:

dart run build_runner watch

Builder options

You can customize the schema source and output destination by adding a targets section to build.yaml in your project root:

targets:
  $default:
    builders:
      ql_gen|ql_gen_builder:
        options:
          # Custom schema file path (relative to package root).
          # When set, the builder reads from this file instead of each .graphql/.gql input.
          schema_path: lib/schema/schema.gql

          # Custom output path. Use a trailing "/" for a directory (output file name
          # is derived from the input), or a full path for a specific file.
          output_path: lib/generated/

Both options are optional — the default behavior (process each .graphql/.gql file individually and output next to the source) is preserved when they are omitted.

CLI usage

If you prefer one-off generation without build_runner, install ql_gen as a global tool or add it to dev_dependencies and run:

dart run ql_gen --help

Arguments:

-s, --source    The source schema file path (default: schema.gql)
-t, --target    The output Dart file path (default: ql.dart)
-h, --help      Prints this help message

Generate output:

dart run ql_gen -s schema.gql -t lib/src/generated/ql.dart

Programmatic usage

import 'package:ql_gen/ql_gen.dart';

void main() {
  final generator = ApiGenerator('schema.gql');
  generator.export('lib/src/generated/ql.dart');
}

Runtime integration

Generated methods expect an executor with signature:

Future<Map<String, dynamic>?> execute(
  (String, Map<String, dynamic>) queryAndVariables,
)

This allows using any GraphQL transport/client package. The tuple contains:

• $1: GraphQL query string
• $2: variables map

Example schema

type Author {
  id: ID
  name: String
  books: [Book!]
}

type Book {
  id: ID
  title: String
  author: Author
}

type Query {
  books: [Book!]
  authors: [Author!]
  book(id: ID!): Book
  author(id: ID!): Author
}

A complete generated sample is available in doc/result.dart.

Development

• Run tests: dart test
• Run analysis: dart analyze

Issues

Bug reports and feature requests are welcome at:

• https://github.com/roadroot/ql_gen/issues/new