{"id":29552603,"url":"https://github.com/tiagoboeing/graphql-federation-schema-parser","last_synced_at":"2025-10-30T19:15:07.446Z","repository":{"id":303655133,"uuid":"1015656873","full_name":"tiagoboeing/graphql-federation-schema-parser","owner":"tiagoboeing","description":"CLI tool to parse GraphQL schemas and generate federated GraphQL schemas for use in a GraphQL Federation gateway","archived":false,"fork":false,"pushed_at":"2025-07-15T18:40:14.000Z","size":55643,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-16T16:37:39.442Z","etag":null,"topics":["cli","graphos","graphql","hive","parser","schema","wundergraph"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/@tiagoboeing/gql-federation-schema-parser","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tiagoboeing.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-07T20:54:36.000Z","updated_at":"2025-07-15T19:33:24.000Z","dependencies_parsed_at":"2025-07-08T19:04:31.782Z","dependency_job_id":"244bf33d-22cc-48a7-8918-67c034828db8","html_url":"https://github.com/tiagoboeing/graphql-federation-schema-parser","commit_stats":null,"previous_names":["tiagoboeing/graphql-federation-schema-parser"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/tiagoboeing/graphql-federation-schema-parser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagoboeing%2Fgraphql-federation-schema-parser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagoboeing%2Fgraphql-federation-schema-parser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagoboeing%2Fgraphql-federation-schema-parser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagoboeing%2Fgraphql-federation-schema-parser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tiagoboeing","download_url":"https://codeload.github.com/tiagoboeing/graphql-federation-schema-parser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tiagoboeing%2Fgraphql-federation-schema-parser/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265703769,"owners_count":23814076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","graphos","graphql","hive","parser","schema","wundergraph"],"created_at":"2025-07-18T05:11:18.584Z","updated_at":"2025-10-30T19:15:02.427Z","avatar_url":"https://github.com/tiagoboeing.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GraphQL Federation Schema Parser\n\n![GitHub Release](https://img.shields.io/github/v/release/tiagoboeing/graphql-federation-schema-parser)\n[![NPM Version](https://img.shields.io/npm/v/%40tiagoboeing%2Fgql-federation-schema-parser)](https://www.npmjs.com/package/@tiagoboeing/gql-federation-schema-parser)\n\n![](./docs/terminal.png)\n\n## Table of Contents\n\n- [Overview](#overview)\n- [Usage](#usage)\n- [How it works](#how-it-works)\n- [Documentation](#documentation)\n- [Installation](#installation)\n- [Development](#development)\n- [Getting Help](#getting-help)\n- [License](#license)\n- [Support](#support)\n\n## Overview\n\nThis project provides a CLI tool to parse GraphQL schemas and generate federated GraphQL schemas for use in a GraphQL Federation gateway. All GraphQL types will be prefixed with the namespace and service name, allowing you to have multiple services under the same namespace without conflicts. Eg.: `PlatformUsers__User`, `PlatformUsers__Post`, etc.\n\nRun it on a directory containing GraphQL schema files, and it will output a federated GraphQL schema to publish to Schema Registry. All schema files will be parsed and merged into a single schema scoped by a provided namespace and service name.\n\nFor what purpose should you use this tool?\n- Building a **GraphQL supergraph**: Use it to create a federated schema for a GraphQL gateway, allowing you to combine multiple services into a single schema and namespace them properly.\n\n### Quick Example\n\n```bash\n# Parse GraphQL schemas in the ./schemas directory\ngql-federation-schema-parser parse -d ./schemas -s users -n platform\n\n# This transforms your schemas into a federated format:\n# User -\u003e PlatformUsers__User\n# Query.user -\u003e Query.platform.users.user\n```\n\n### Features\n\n| Feature                    | Description                                  | Supported |\n| -------------------------- | -------------------------------------------- | --------- |\n| **Recursive schema parsing** | Parses all `.graphql` files in a directory and its subdirectories | ✅ |\n| **Type prefixing**         | Add namespace and service prefixes to types  | ✅ |\n| **Federation support**     | Generate federated query structures          | ✅ |\n| **Directive preservation** | Maintain GraphQL directives in output        | ✅ |\n| **Multiple type support**  | Support for all GraphQL type kinds (scalars, enums, interfaces, unions, inputs, objects) | ✅ |\n\n## Usage\n\n### Commands\n\n- `parse`: Parses GraphQL schema files and generates federated GraphQL schemas.\n- `help`: Displays help information for the CLI tool.\n\n#### Parse Command\n\nThe parse command requires the following parameters:\n\n```bash\ngql-federation-schema-parser parse [options]\n\nOptions:\n  -d, --directory \u003cpath\u003e     Directory containing GraphQL schema files\n  -s, --service-name \u003cname\u003e  Service name for type prefixing\n  -n, --namespace \u003cname\u003e     Namespace for grouping services\n  -o, --output-file \u003cfile\u003e   Output file name (optional)\n  --write-to-file           Write output to file instead of stdout\n  -D, --debug               Enable debug mode\n  -S, --simple              Disable colors on terminal\n  -h, --help                Display help for command\n```\n\n**Example:**\n```bash\ngql-federation-schema-parser parse -d ./schemas -s users -n platform\n```\n\nTo get help on the CLI, run `--help` or `-h` on any command:\n\n```bash\ngql-federation-schema-parser --help\n# or\ngql-federation-schema-parser -h\n\n# On a specific command\ngql-federation-schema-parser parse --help\n# or\ngql-federation-schema-parser parse -h\n```\n\n### Debug mode\n\nYou can enable debug mode to see detailed logs of the parsing process. This is useful for troubleshooting issues with schema files or understanding how the tool works.\n\nUse `-D` or `--debug` on any command to enable global debug mode:\n\n```bash\ngql-federation-schema-parser parse -d ./schemas -s myService -n myScope -D\n# or\ngql-federation-schema-parser parse -d ./schemas -s myService -n myScope --debug\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e Debug mode is a global setting and will apply to all commands. It will log detailed information about the parsing process, including file paths, and other relevant information.\n\n## How it works\n\nWith the following [schema files](./schemas) in a directory and these settings:\n\n- `--service-name`: `users`\n- `--namespace`: `platform`\n\nThe resulting GraphQL schema will be:\n\n```graphql\n# Graphql root definitions\ndirective @oneOf on INPUT_OBJECT\n\nscalar ID\nscalar String\nscalar Boolean\n\ntype PlatformUsers__Post {\n  id: ID!\n  content: String\n  authorId: ID!\n}\n\ntype PlatformUsers__User {\n  id: ID!\n  name: String\n  email: String\n}\n\ntype PlatformUsersQueries {\n  posts: [PlatformUsers__Post!]!\n  post(id: ID!): PlatformUsers__Post\n  users: [PlatformUsers__User!]!\n  getSubschemaData: String\n}\n\ntype PlatformUsersMutations {\n  createPost: PlatformUsers__Post!\n}\n\ntype PlatformMutations {\n  users: PlatformUsersMutations!\n}\n\ntype PlatformQueries {\n  users: PlatformUsersQueries!\n}\n\ntype Mutation {\n  platform: PlatformMutations!\n}\n\ntype Query {\n  platform: PlatformQueries!\n}\n```\n\nIn gateway you can query the schema like this:\n\n```graphql\nquery {\n  platform {\n    users {\n      # Query, mutate or subscribe to your service operations\n      ...\n    }\n  }\n}\n```\n\nAll GraphQL types will be prefixed with the namespace and service name, allowing you to have multiple services under the same namespace without conflicts. Eg.: `PlatformUsers__User`, `PlatformUsers__Post`, etc.\n\n## Installation\n\nYou can install the `gql-federation-schema-parser` CLI tool using one of the following methods:\n\n- Using NPM\n- On any platform with the pre-built binary\n\n### Using NPM\n\nTo install the CLI tool globally using NPM, run:\n\n```bash\nnpm install -g @tiagoboeing/gql-federation-schema-parser\n# or\npnpm install -g @tiagoboeing/gql-federation-schema-parser\n```\n\nAfter install, run:\n\n```bash\ngql-federation-schema-parser --help\n```\n\n### Pre-built Binary\n\n#### MacOS\n\nOn MacOS a warn will be shown when running the binary for the first time, indicating that it is from an unidentified developer. You can bypass this by following these steps:\n\n```bash\n# Download the latest release from the release page and unzip it\n...\n\n# Trust the binary and make it executable\nxattr -d com.apple.quarantine gql-federation-schema-parser-macos\nchmod +x gql-federation-schema-parser-macos\n\n# Run the binary\n./gql-federation-schema-parser-macos --help\n```\n\n#### Linux\n\nOn Linux, you can download the pre-built binary from the release page and run it directly:\n\n```bash\n# Download the latest release from the release page and unzip it\n...\nchmod +x gql-federation-schema-parser-macos\n\n# Run the binary\n./gql-federation-schema-parser-macos --help\n```\n\n## Development\n\nTo develop this project, you will need Node.js and npm installed. Follow these steps to set up the development environment:\n\n### Testing CLI\n\nTo test the CLI, you can use `tsx` script on `package.json` to run the TypeScript code directly and debug in your IDE:\n\n```bash\npnpm start:dev-ts src/index.ts [args]\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e On VSCode, run from a JavaScript Debug Terminal to enable debugging features like breakpoints and watch variables.\n\nor you can use `bun` to run the TypeScript code (Bun debugger is buggy, so use it only if you don't need to debug):\n\n```bash\npnpm start:dev \n# or\nbun --watch src/index.ts\n\n# Pass arguments to the script\npnpm start:dev ...args\n# Example:\npnpm start:dev parse -d ./schemas -s users -n platform\n```\n\n## Getting Help\n\n### For Users\n\n- **Installation Issues**: Check [installation guide](../README.md#installation)\n- **Usage Questions**: Review [examples](./EXAMPLES.md)\n- **CLI Help**: Run `gql-federation-schema-parser --help`\n- **Bug Reports**: Create an issue on [GitHub](https://github.com/tiagoboeing/graphql-federation-schema-parser/issues)\n\n### For Developers\n\n- **Development Setup**: Follow [development guide](./DEVELOPMENT.md#getting-started)\n- **Contributing**: See [contribution guidelines](./DEVELOPMENT.md#contributing)\n- **API Reference**: Check [API documentation](./API.md)\n- **Architecture**: Review [project structure](./DEVELOPMENT.md#project-structure)\n\n\u003e Example: on Yoga/Hive gateway, you can create a custom plugin to handle `onFetch` hook, capture the namespace and service name, and translate the query to the correct service operation overriding the `setFetchFn()` method.\n\n## Documentation\n\nFor more detailed information, check out the comprehensive documentation:\n\n- **[Examples Guide](./docs/EXAMPLES.md)** - Comprehensive examples and use cases\n- **[Development Guide](./docs/DEVELOPMENT.md)** - Development setup, workflow, and contribution guidelines\n- **[API Reference](./docs/API.md)** - Internal API documentation and architecture details\n- **[Changelog](./CHANGELOG.md)** - Version history and release notes\n\n### Quick links\n\n- **[Basic Usage Examples](./docs/EXAMPLES.md#basic-usage)**\n- **[Advanced Schema Transformations](./docs/EXAMPLES.md#advanced-schema-transformations)**\n- **[Federation Patterns](./docs/EXAMPLES.md#federation-patterns)**\n- **[CI/CD Integration](./docs/EXAMPLES.md#integration-examples)**\n- **[Troubleshooting](./docs/EXAMPLES.md#troubleshooting-examples)**\n\n## Installation\n\nYou can install the `gql-federation-schema-parser` CLI tool using one of the following methods:\n\n- Using NPM\n- On any platform with the pre-built binary\n\n### Using NPM\n\nTo install the CLI tool globally using NPM, run:\n\n```bash\nnpm install -g @tiagoboeing/gql-federation-schema-parser\n# or\npnpm install -g @tiagoboeing/gql-federation-schema-parser\n```\n\nAfter install, run:\n\n```bash\ngql-federation-schema-parser --help\n```\n\n### Pre-built Binary\n\n#### MacOS\n\nOn MacOS a warn will be shown when running the binary for the first time, indicating that it is from an unidentified developer. You can bypass this by following these steps:\n\n```bash\n# Download the latest release from the release page and unzip it\n...\n\n# Trust the binary and make it executable\nxattr -d com.apple.quarantine gql-federation-schema-parser-macos\nchmod +x gql-federation-schema-parser-macos\n\n# Run the binary\n./gql-federation-schema-parser-macos --help\n```\n\n#### Linux\n\nOn Linux, you can download the pre-built binary from the release page and run it directly:\n\n```bash\n# Download the latest release from the release page and unzip it\n...\nchmod +x gql-federation-schema-parser-macos\n\n# Run the binary\n./gql-federation-schema-parser-macos --help\n```\n\n## Development\n\nTo develop this project, you will need Node.js and npm installed. Follow these steps to set up the development environment:\n\n### Testing CLI\n\nTo test the CLI, you can use `tsx` script on `package.json` to run the TypeScript code directly and debug in your IDE:\n\n```bash\npnpm start:dev-ts src/index.ts [args]\n```\n\n\u003e [!NOTE]\n\u003e\n\u003e On VSCode, run from a JavaScript Debug Terminal to enable debugging features like breakpoints and watch variables.\n\nor you can use `bun` to run the TypeScript code (Bun debugger is buggy, so use it only if you don't need to debug):\n\n```bash\npnpm start:dev \n# or\nbun --watch src/index.ts\n\n# Pass arguments to the script\npnpm start:dev ...args\n# Example:\npnpm start:dev parse -d ./schemas -s users -n platform\n```\n\n## Getting Help\n\n### For Users\n\n- **Installation issues**: Check [installation guide](#installation)\n- **Usage questions**: Review [examples](./docs/EXAMPLES.md)\n- **CLI help**: Run `gql-federation-schema-parser --help`\n- **Bug reports**: Create an issue on [GitHub](https://github.com/tiagoboeing/graphql-federation-schema-parser/issues)\n\n### For Developers\n\n- **Development Setup**: Follow [development guide](./docs/DEVELOPMENT.md#getting-started)\n- **Contributing**: See [contribution guidelines](./docs/DEVELOPMENT.md#contributing)\n- **API Reference**: Check [API documentation](./docs/API.md)\n- **Architecture**: Review [project structure](./docs/DEVELOPMENT.md#project-structure)\n\n## Recent Changes\n\nCheck the [CHANGELOG.md](./CHANGELOG.md) for recent updates and new features.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.\n\n## Support\n\n- **GitHub Issues**: [Report bugs or request features](https://github.com/tiagoboeing/graphql-federation-schema-parser/issues)\n- **NPM Package**: [@tiagoboeing/gql-federation-schema-parser](https://www.npmjs.com/package/@tiagoboeing/gql-federation-schema-parser)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiagoboeing%2Fgraphql-federation-schema-parser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftiagoboeing%2Fgraphql-federation-schema-parser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftiagoboeing%2Fgraphql-federation-schema-parser/lists"}