GraphQL CLI Prepare Plugin

1.4.19 verified Thu Apr 23 auth: no javascript abandoned

graphql-cli-prepare is a plugin for the original `graphql-cli` command-line interface, designed to automate GraphQL schema bundling and binding generation. It leverages `graphql-import` to process `import` statements within GraphQL schemas, allowing for modular schema definitions. Additionally, it integrates with `graphql-static-binding` to generate type-safe bindings for use with older `graphql-yoga` and `graphcool-binding` setups, facilitating GraphQL query and mutation delegation in resolvers. The package's latest stable version is 1.4.19, last published in March 2018. Due to the rapid evolution of the GraphQL ecosystem and the explicit deprecation of `graphql-cli` itself in favor of `graphql-config` and `GraphQL Code Generator CLI`, this plugin is no longer actively maintained. It primarily functions by extending the `graphql-cli` with a `prepare` command and stores its configuration within `.graphqlconfig` files, an older configuration format.

Common errors

error `graphql prepare` is not a valid command. ↓

cause The `graphql-cli` installation is either too old, too new, or the plugin `graphql-cli-prepare` is not correctly installed or recognized.

fix

Ensure you are using graphql-cli version 3.x or below, as the prepare command was removed in version 4.x. If using a newer graphql-cli, migrate to @graphql-codegen/cli. If using an older graphql-cli, ensure graphql-cli-prepare is globally or locally installed alongside it.

error Error: Cannot find module 'graphql-import' ↓

cause The `graphql-import` dependency, used internally by `graphql-cli-prepare`, is missing or not resolvable in your project.

fix

Install graphql-import explicitly: npm install graphql-import or yarn add graphql-import.

error Error: Must provide name. You must provide a name for a GraphQL type, query or mutation. ↓

cause This error typically indicates an issue with the GraphQL schema files being bundled, such as incorrect syntax, missing type definitions, or problems with the `import` statements not resolving correctly.

fix

Review your .graphqlconfig file for correct schema paths. Inspect your .graphql schema files for syntax errors or malformed import statements. Ensure all imported schemas are valid and accessible.

Warnings

breaking The core `graphql-cli` tool, which this plugin extends, has been deprecated and its `prepare` command removed in `graphql-cli` versions 4.x and higher. Modern GraphQL tooling, particularly `GraphQL Code Generator CLI` and `@graphql-tools`, offers a more robust and actively maintained approach for schema bundling and code generation. ↓

fix Migrate to `graphql-config` for project configuration and use `@graphql-codegen/cli` with relevant plugins (e.g., `@graphql-codegen/schema-ast`, `@graphql-codegen/typescript`) for schema bundling and code generation. `graphql-config` has a migration tool for old `.graphqlconfig` files.

deprecated The underlying `graphql-import` library used by this plugin for schema bundling is considered deprecated. Its functionality is often superseded by native GraphQL schema stitching capabilities or other tools that handle schema composition more effectively. ↓

fix Adopt modern GraphQL schema composition techniques, such as `@graphql-tools/load` and `@graphql-tools/merge`, or use federated GraphQL approaches (e.g., Apollo Federation) for complex schema architectures.

deprecated The `graphql-static-binding` and `graphcool-binding` libraries, used for generating bindings, are outdated. The `graphql-yoga` framework, for which these bindings were generated, has also evolved significantly since this plugin's last release. ↓

fix For type-safe clients and resolvers, consider using `GraphQL Code Generator` with plugins like `typescript-operations`, `typescript-resolvers`, or `typescript-graphql-request`. For client-side bindings, explore modern GraphQL clients like Apollo Client or Relay.

gotcha This plugin relies on the `.graphqlconfig` file format for its configuration. Newer versions of GraphQL CLI and `graphql-config` utilize `.graphqlrc.yml` or similar modern formats, which are incompatible with the configurations saved by this plugin. ↓

fix If migrating an older project, manually convert your `.graphqlconfig` to `.graphqlrc.yml` following the `graphql-config` migration guide or use the provided migration tool.

Install

npm install graphql-cli-prepare

yarn add graphql-cli-prepare

pnpm add graphql-cli-prepare

Quickstart

Demonstrates the installation and primary CLI usage for schema bundling and binding generation, including initial configuration and automated runs.

npm install -g graphql-cli graphql-cli-prepare

# Assuming you have a .graphqlconfig file set up for your project
# and schema files with 'import' statements, e.g., in a 'schema' directory.
# Example .graphqlconfig content (old format):
# projects:
#   app:
#     schema: ./schema/app.graphql
#     extensions:
#       prepare:
#         output: src/generated
#         bundle: true
#         bindings: false
#   database:
#     schema: ./schema/database.graphql
#     extensions:
#       prepare:
#         output: src/generated
#         bundle: false
#         bindings: true
#         generator: graphcool-ts

# First-time setup for schema bundling, saving config
graphql prepare -p app -o src/generated --bundle --save

# First-time setup for binding generation, saving config
graphql prepare -p database -o src/generated -g graphcool-ts --bindings --save

# After initial setup, run without parameters to process all configured projects
graphql prepare

# Output example:
# √ Bundled schema for project app written to src/generated/app.graphql
# √ Bindings for project database written to src/generated/database.ts