New user documentation and experience is challenging

[wilhuff]

Hi there! New user here. I found your library and read through "Why?" and found myself nodding along. I was pumped.

However, there's a massive barrier between deciding to use this library and actually getting it working. Problems I've encountered:

• In Installation, if I'm going to add this as a dependency to a Swift Package Manager project, there's no details about how to do it if I have my own Package.swift.
  • For example, within your package, there are multiple products: which one do I make my runtime depend upon?
  • Are there trade-offs?
  • I think I should depend upon SwiftGraphQLClient but that was only after reading through your Package.swift on GitHub.
  • I'm still not even sure though because I don't need web socket support and don't want to pay the binary size for it.
  • Here's a great example of how to do this well.
• Given such a dependency in my package, you don't actually mention how to build the CLI.
  • I had to figure out that what I wanted was swift build -c release --product swift-graphql and now the binary is in .build/arm64-apple-macosx/release/swift-graphql.
  • I'm not keen on having an unversioned dependency via homebrew because it makes it very hard to coordinate upgrades amongst a team.
  • SPM plugins seem like they'd be a great help (but I see these are on your radar).
• Most importantly, you haven't documented how to have a reasonable workflow if you control both the client and the server. I would expect to be able to run the generator against a GraphQL schema file. Having to stand up a local server just to be able to run the schema generator is highly suboptimal. If I try to run against the schema file I get this error:

  Generating SwiftGraphQL Selection 🚀
  ⠋ Fetching GraphQL SchemaThe data couldn’t be read because it isn’t in the correct format.
  Error: Couldn't reach GraphQL server at given endpoint.
  

  The swift-graphql utility says that it takes a "GraphQL server endpoint or local file path from the current location" but what contents are expected to be in the local file path is completely opaque to me. I can only get this to work against a running server, which is a nonstarter.
• Examples are seemingly incomplete? The command-line utility says that it has a required argument of the endpoint-or-file, but the GitHub Stars example does not indicate which endpoint to use. It's possible that this works due to some implicit mechanism (convention over configuration) but if so, it's important to document what your expectations are for people unfamiliar with the conventions.

I realize that a bunch of your developer experience is in flux based on currently open discussions, but it is a big chasm to cross to get from swift-graphql-curious to actually having it integrated. Given the open discussions, maybe this perspective will help.

For what it's worth, I would be grateful if you were more opinionated about setup. For example, the Relay.swift docs show a method for getting code generation going using npx. This isn't something I would necessarily want, but it gives a default direction, and things to study if I don't like it. By contrast, your documentation is entirely silent on how to actually invoke the code generator, which is still a big stumbling block for me.

Expected behavior:
As a new user, I'd expect to have instructions that I could follow for getting a Swift-based GraphQL client working. I'd be very appreciative of an end-to-end working example. Some places call this a tutorial, and I'm OK with that too.

Desktop:

This isn't relevant, but I've included it just in case.

• OS: macOS Sonoma 14.6.1
• Browser Safari
• Version 17.6

Feel free to just close this issue if your pending rewrites/devx changes have this in hand, but I'm still pretty stumped on how to use this thing effectively. Don't consider this issue to be a support request unless you particularly want to.