Skip to content

Commit 4cd9738

Browse files
tiagoboeingtiagoboeing
committed
docs: add comprehensive documentation and improve README
The commit adds extensive documentation to the project, including: - Expanded README with table of contents, features, and usage examples - New documentation files (API.md, DEVELOPMENT.md, EXAMPLES.md) - Improved code documentation with JSDoc comments - Better organization of installation and development sections - Added troubleshooting, support, and license information
1 parent 49f0e31 commit 4cd9738

File tree

9 files changed

+1558
-13
lines changed

9 files changed

+1558
-13
lines changed

‎README.md‎

Lines changed: 202 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,78 @@
55

66
![](./docs/terminal.png)
77

8-
This project provides a CLI tool to parse GraphQL schemas and generate TypeScript definitions for use in a GraphQL Federation gateway.
8+
## Table of Contents
99

10-
Run it on a directory containing GraphQL schema files, and it will output TypeScript definitions 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.
10+
- [Overview](#overview)
11+
- [Usage](#usage)
12+
- [How it works](#how-it-works)
13+
- [Documentation](#documentation)
14+
- [Installation](#installation)
15+
- [Development](#development)
16+
- [Getting Help](#getting-help)
17+
- [License](#license)
18+
- [Support](#support)
19+
20+
## Overview
21+
22+
This 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.
23+
24+
Run 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.
1125

1226
For what purpose should you use this tool?
1327
- 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.
1428

15-
| Feature | Description | Supported |
16-
| ------------------------ | ----------------------------------------------------------------- | --------- |
17-
| Recursive schema parsing | Parses all `.graphql` files in a directory and its subdirectories | ✅ |
29+
### Quick Example
30+
31+
```bash
32+
# Parse GraphQL schemas in the ./schemas directory
33+
gql-federation-schema-parser parse -d ./schemas -s users -n platform
34+
35+
# This transforms your schemas into a federated format:
36+
# User -> PlatformUsers__User
37+
# Query.user -> Query.platform.users.user
38+
```
39+
40+
### Features
41+
42+
| Feature | Description | Supported |
43+
| -------------------------- | -------------------------------------------- | --------- |
44+
| **Recursive schema parsing** | Parses all `.graphql` files in a directory and its subdirectories | ✅ |
45+
| **Type prefixing** | Add namespace and service prefixes to types | ✅ |
46+
| **Federation support** | Generate federated query structures | ✅ |
47+
| **Directive preservation** | Maintain GraphQL directives in output | ✅ |
48+
| **Multiple type support** | Support for all GraphQL type kinds (scalars, enums, interfaces, unions, inputs, objects) | ✅ |
1849

1950
## Usage
2051

2152
### Commands
2253

23-
- `parse`: Parses GraphQL schema files and generates TypeScript definitions.
54+
- `parse`: Parses GraphQL schema files and generates federated GraphQL schemas.
2455
- `help`: Displays help information for the CLI tool.
2556

57+
#### Parse Command
58+
59+
The parse command requires the following parameters:
60+
61+
```bash
62+
gql-federation-schema-parser parse [options]
63+
64+
Options:
65+
-d, --directory <path> Directory containing GraphQL schema files
66+
-s, --service-name <name> Service name for type prefixing
67+
-n, --namespace <name> Namespace for grouping services
68+
-o, --output-file <file> Output file name (optional)
69+
--write-to-file Write output to file instead of stdout
70+
-D, --debug Enable debug mode
71+
-S, --simple Disable colors on terminal
72+
-h, --help Display help for command
73+
```
74+
75+
**Example:**
76+
```bash
77+
gql-federation-schema-parser parse -d ./schemas -s users -n platform
78+
```
79+
2680
To get help on the CLI, run `--help` or `-h` on any command:
2781

2882
```bash
@@ -124,14 +178,124 @@ query {
124178

125179
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.
126180

127-
### Where to use this tool
181+
## Installation
182+
183+
You can install the `gql-federation-schema-parser` CLI tool using one of the following methods:
184+
185+
- Using NPM
186+
- On any platform with the pre-built binary
187+
188+
### Using NPM
189+
190+
To install the CLI tool globally using NPM, run:
191+
192+
```bash
193+
npm install -g @tiagoboeing/gql-federation-schema-parser
194+
# or
195+
pnpm install -g @tiagoboeing/gql-federation-schema-parser
196+
```
197+
198+
After install, run:
199+
200+
```bash
201+
gql-federation-schema-parser --help
202+
```
203+
204+
### Pre-built Binary
205+
206+
#### MacOS
207+
208+
On 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:
209+
210+
```bash
211+
# Download the latest release from the release page and unzip it
212+
...
213+
214+
# Trust the binary and make it executable
215+
xattr -d com.apple.quarantine gql-federation-schema-parser-macos
216+
chmod +x gql-federation-schema-parser-macos
217+
218+
# Run the binary
219+
./gql-federation-schema-parser-macos --help
220+
```
221+
222+
#### Linux
223+
224+
On Linux, you can download the pre-built binary from the release page and run it directly:
225+
226+
```bash
227+
# Download the latest release from the release page and unzip it
228+
...
229+
chmod +x gql-federation-schema-parser-macos
230+
231+
# Run the binary
232+
./gql-federation-schema-parser-macos --help
233+
```
234+
235+
## Development
236+
237+
To develop this project, you will need Node.js and npm installed. Follow these steps to set up the development environment:
238+
239+
### Testing CLI
240+
241+
To test the CLI, you can use `tsx` script on `package.json` to run the TypeScript code directly and debug in your IDE:
128242

129-
Use this CLI at the service level to prepare schema before publish it to the Schema Registry. It will generate a final GraphQL Schema file with the merged definitions. The gateway need to be prepared to translate the namespace and service name into the correct GraphQL operations at the service level.
243+
```bash
244+
pnpm start:dev-ts src/index.ts [args]
245+
```
130246

131247
> [!NOTE]
132248
>
249+
> On VSCode, run from a JavaScript Debug Terminal to enable debugging features like breakpoints and watch variables.
250+
251+
or you can use `bun` to run the TypeScript code (Bun debugger is buggy, so use it only if you don't need to debug):
252+
253+
```bash
254+
pnpm start:dev
255+
# or
256+
bun --watch src/index.ts
257+
258+
# Pass arguments to the script
259+
pnpm start:dev ...args
260+
# Example:
261+
pnpm start:dev parse -d ./schemas -s users -n platform
262+
```
263+
264+
## Getting Help
265+
266+
### For Users
267+
268+
- **Installation Issues**: Check [installation guide](../README.md#installation)
269+
- **Usage Questions**: Review [examples](./EXAMPLES.md)
270+
- **CLI Help**: Run `gql-federation-schema-parser --help`
271+
- **Bug Reports**: Create an issue on [GitHub](https://github.com/tiagoboeing/graphql-federation-schema-parser/issues)
272+
273+
### For Developers
274+
275+
- **Development Setup**: Follow [development guide](./DEVELOPMENT.md#getting-started)
276+
- **Contributing**: See [contribution guidelines](./DEVELOPMENT.md#contributing)
277+
- **API Reference**: Check [API documentation](./API.md)
278+
- **Architecture**: Review [project structure](./DEVELOPMENT.md#project-structure)
279+
133280
> 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.
134281
282+
## Documentation
283+
284+
For more detailed information, check out the comprehensive documentation:
285+
286+
- **[Examples Guide](./docs/EXAMPLES.md)** - Comprehensive examples and use cases
287+
- **[Development Guide](./docs/DEVELOPMENT.md)** - Development setup, workflow, and contribution guidelines
288+
- **[API Reference](./docs/API.md)** - Internal API documentation and architecture details
289+
- **[Changelog](./CHANGELOG.md)** - Version history and release notes
290+
291+
### Quick links
292+
293+
- **[Basic Usage Examples](./docs/EXAMPLES.md#basic-usage)**
294+
- **[Advanced Schema Transformations](./docs/EXAMPLES.md#advanced-schema-transformations)**
295+
- **[Federation Patterns](./docs/EXAMPLES.md#federation-patterns)**
296+
- **[CI/CD Integration](./docs/EXAMPLES.md#integration-examples)**
297+
- **[Troubleshooting](./docs/EXAMPLES.md#troubleshooting-examples)**
298+
135299
## Installation
136300

137301
You can install the `gql-federation-schema-parser` CLI tool using one of the following methods:
@@ -213,4 +377,33 @@ bun --watch src/index.ts
213377
pnpm start:dev ...args
214378
# Example:
215379
pnpm start:dev parse -d ./schemas -s users -n platform
216-
```
380+
```
381+
382+
## Getting Help
383+
384+
### For Users
385+
386+
- **Installation issues**: Check [installation guide](#installation)
387+
- **Usage questions**: Review [examples](./docs/EXAMPLES.md)
388+
- **CLI help**: Run `gql-federation-schema-parser --help`
389+
- **Bug reports**: Create an issue on [GitHub](https://github.com/tiagoboeing/graphql-federation-schema-parser/issues)
390+
391+
### For Developers
392+
393+
- **Development Setup**: Follow [development guide](./docs/DEVELOPMENT.md#getting-started)
394+
- **Contributing**: See [contribution guidelines](./docs/DEVELOPMENT.md#contributing)
395+
- **API Reference**: Check [API documentation](./docs/API.md)
396+
- **Architecture**: Review [project structure](./docs/DEVELOPMENT.md#project-structure)
397+
398+
## Recent Changes
399+
400+
Check the [CHANGELOG.md](./CHANGELOG.md) for recent updates and new features.
401+
402+
## License
403+
404+
This project is licensed under the MIT License. See the [LICENSE](./LICENSE) file for details.
405+
406+
## Support
407+
408+
- **GitHub Issues**: [Report bugs or request features](https://github.com/tiagoboeing/graphql-federation-schema-parser/issues)
409+
- **NPM Package**: [@tiagoboeing/gql-federation-schema-parser](https://www.npmjs.com/package/@tiagoboeing/gql-federation-schema-parser)

0 commit comments

Comments
 (0)