GraphQXL Node Wrapper

0.40.2 verified Thu Apr 23 auth: no javascript

node-graphqxl is a JavaScript/TypeScript development dependency that provides a Node.js wrapper for the GraphQXL compiler. GraphQXL itself is an extension of the GraphQL Schema Definition Language (SDL) designed to facilitate the creation of large and scalable server-side GraphQL schemas by introducing features like inheritance, generics, and imports, which are typically found in programming languages. This package (currently at version 0.40.2) makes the `graphqxl` command-line interface (CLI) binary available within Node.js projects, allowing developers to compile `.graphqxl` schema files into standard GraphQL SDL. It is a build-time tool, not a runtime library for executing GraphQL queries. The primary use case is in schema-first GraphQL development workflows, enabling enhanced schema modularity and reusability. As a 0.x.x versioned project, it should be noted that the API and behavior may evolve rapidly.

Common errors

error command not found: graphqxl ↓

cause The `graphqxl` executable is installed as a `devDependency` and is typically accessed via `npx` or `package.json` scripts. It's not added to your global PATH by default.

fix

Ensure you are running the command through npx graphqxl or define it as a script in your package.json (e.g., "scripts": { "compile": "graphqxl src/schema.graphqxl" }) and then execute with npm run compile or yarn compile.

error Error: Failed to compile GraphQXL schema: ... (followed by parsing errors) ↓

cause This indicates a syntax error or a semantic issue within your `.graphqxl` schema file that prevents the compiler from converting it to valid GraphQL SDL.

fix

Carefully review the specified line and column in your .graphqxl file. Consult the GraphQXL documentation (github.com/gabotechs/graphqxl) for correct syntax, especially for features like inheritance, generics, or imports.

Warnings

gotcha node-graphqxl is primarily a CLI wrapper. It provides the `graphqxl` executable to your `node_modules/.bin` path and is intended for use in `package.json` scripts or direct CLI calls. There is no public programmatic JavaScript API for compiling GraphQXL schemas directly within your Node.js code. ↓

fix Always invoke `graphqxl` via the CLI (e.g., `npx graphqxl` or `npm run script_name`). Do not attempt to `import { compile } from 'node-graphqxl'` as such an API does not exist.

breaking As a pre-1.0.0 project (version 0.x.x), `node-graphqxl` and the underlying GraphQXL language are subject to frequent breaking changes between minor and patch releases. Always check release notes when upgrading. ↓

fix Pin exact versions (e.g., `"node-graphqxl": "0.40.2"`) or use caret ranges carefully (`^0.40.2`) and review release notes thoroughly before updating. Consider using a lockfile (npm-lockfile.json or yarn.lock) to ensure consistent builds.

gotcha GraphQXL is a compile-time language extension for GraphQL SDL, not a runtime library. It compiles `.graphqxl` files into standard `.graphql` SDL, which then needs to be used by a separate GraphQL server library (e.g., Apollo Server, Express GraphQL) to serve an API. ↓

fix Understand that `node-graphqxl` is a build step. Your application still requires a GraphQL execution engine (like `@apollo/server` or `graphql-yoga`) to serve the compiled schema.

Install

npm install node-graphqxl

yarn add node-graphqxl

pnpm add node-graphqxl

Quickstart

Demonstrates how to integrate the GraphQXL compiler into your project's build scripts to generate a GraphQL schema file.

{
  "name": "my-graphqxl-project",
  "version": "1.0.0",
  "description": "A project using GraphQXL for schema definition.",
  "main": "index.js",
  "scripts": {
    "generate:schema": "graphqxl src/schema.graphqxl > dist/schema.graphql",
    "start": "node src/server.js"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "node-graphqxl": "^0.40.2"
  }
}
// src/schema.graphqxl (example content)
// type User {
//   id: ID!
//   name: String!
// }
//
// type Query {
//   users: [User!]
// }

// To run this example, save the above JSON in package.json and the commented out content in src/schema.graphqxl.
// Then run: npm install && npm run generate:schema