A new path for graphql-cli - help us decide on the roadmap!

[Urigo]

Hi everyone!

I'm @Urigo the founder of The Guild.

As recently been announced on the Prisma blog, we are taking over the maintenance of this library going forward.
I've expressed it in the blog post in more details but I would like to start by thanking Prisma for conceiving, creating and maintaining this library so far and also for doing the selfless act of providing it with fresh life by handing over the maintenance to us.

We already have a certain plan in mind going forward, some of it we've specified in the blog post, but we want you, the users and community of the library to be part of influencing the roadmap going forward.

One thing to note about The Guild - We place all the open source packages we maintain under individual person's Github profile instead of under a GitHub org or a company.
That is part of our philosophy - it puts more accountability on the maintainer and it also lowers the barrier of creating successful competing forks.
So we will transfer that repository from under its current org as part of the transition.

I'm looking forward to start the discussion here below.
Please share how and why you use the library today, what are your biggest pain points today and ideas and features you would like to see in the future.

I will add points into the description here as we go.

Let's make this happen!

[joelbowen]

I'm really excited to see graphql-cli get attention and commitment! I'm also big fans of how Prisma has created and shepherded so many valuable OSS offerings in this space, so this move is fitting to their selflessness and interest in ensuring the long term value of these tools.

I'll share my use-cases and experiences, which are fairly simple but may resonate with others, as well as a few wish-list items. I'm also interested in helping out in whatever way makes sense.

Many of my use-cases involve introducing people to a GraphQL ecosystem/API during an architecture/planning phase or introducing devs to GraphQL concepts for the first time during new application development.

Personal Use Cases

• This CLI is an incredibly easy way to get someone up and running with a .graphqlconfig file via graphql init. If the API already exists, step 1 for me is to install this CLI and start exploring the data.
• Step 2 is graphql get-schema as I really appreciate the .graphql file instead of .json since it's much easier to poke around and show fellow devs what's there.
• Step 3 is usually to add in the Voyager plugin, this view is really comfortable for people especially if GraphQL is a new concept for them.
• Step 4 (that I haven't been doing) is to automate the pull of the schema file at build time. Recently I've been working with teams developing APIs on AWS so when we use GraphQL it has been AppSync serving (oftentimes) an SPA or static site. I would like a build hook that pulls the schema and validates all the client queries against it - however, the vulnerabilities reported by npm have kept me from being able to include the CLI as a dependency. So it's a manual task right now. On a recent install of graphql-cli npm reported: found 70 vulnerabilities (64 low, 1 moderate, 4 high, 1 critical) which is not ideal to add to a new project for a client 😏.

Wish List

• Mock data API server. For a while on the README it has listed graphql-cli-faker as "coming soon". In lieu of something I could run from this CLI within dev/test scripts I make a very simple express server that lives alongside the app and uses makeExecutableSchema and addMockFunctionsToSchema from graphql-tools to get a mock API endpoint up and running quickly based on an existing schema. It would be great if the CLI could do this for me, and accept mocks and typeDefs modules as arguments to override or extend functionality.
• Playground is nice, but I really like graphiql-explorer as it is such an easy way to show the power of GraphQL query building.

---

I hope some of this is helpful to hear or resonates with other users of this CLI. Looking forward to seeing where this goes!

[jexp]

Thanks a lot for picking it up that's really appreciated. I also like to use graphql-cli for new APIs.
And agree on the storage of a schema as a plain file instead of JSON.

Something I would love to see in graphql-init is the addition of auth parameters for the graphql endpoint.

The use case I wrote a plugin for graphql-cli is to ease import of data into new graphql-apis using their mutations fed from CSV/JSON files.

https://github.com/neo4j-graphql/graphql-cli-load

I'm more of a JS noob so I guess my plugin would need more work to make it robust and great, but I'm happy to invest in it.

It would be good to learn about API and other changes of graphql-cli and perhaps even have some means of automatic testing for plugins with new builds.

[ZenSoftware]

Cheers my friends! Congratulations on the partnership between Prisma and The Guild.

Primary Use Case

We use the command graphql codegen to generate our Typescript Prisma bindings.

The Node.js framework Nest has a Nest + Prisma Recipe which makes heavy use of graphql-cli. The recipe makes it extraordinarily simple to create a GraphQL gateway to a Prisma v1 server. The recipe uses prisma/prisma-binding as the generator for graphql-cli to generate the prisma.binding.ts file. This file does all the heavy lifting for the schema delegation to Prisma v1. Combining these technologies together allows for a declarative, idiomatic way of writing GraphQL resolvers for any new type defined in the datamodel.prisma. You get so much for free by leveraging off of code generation and a Prisma server:

• Code generated Typescript static types for great dev tooling.
• Access to Prisma GraphQL connections (cursor based data paging)
• Access to Prisma server Subscription endpoints to react to any mutations occurring on a GraphQL type. Reactive, type safe, real-time networking over websockets for free!
• Prisma data loader optimizations for resolving queries efficiently (solving the N+1 problem)
• Prisma generated GraphQL SDL file to allow for remote schema introspection (query code completion)

The data layer has never had such a great dev experience. Really good code generation has enabled front-end devs to finally contribute to the back-end. (an industry first?) Allowing them to modifying the server's data model with confidence, and write their own GraphQL resolvers in a declarative manner. This gives teams much more agility than was previously possible. The following are code snippets that are deployed in production. You get all the listed above for free by simply writing something akin to:

"datamodel.prisma"

type TuDefinition {
  id: Int! @id
  word: String!
  definition: String!
}

"tu-definition.resolver.ts"

import { UseGuards } from '@nestjs/common';
import { Query, Mutation, Resolver, Args, Info } from '@nestjs/graphql';
import { GqlGuard, Roles } from '../../auth';
import { PrismaService } from '../../prisma';

@Resolver('TuDefinition')
@UseGuards(GqlGuard)
@Roles('EDITOR') // This gives those with this role read/write access to this GraphQL type
export class TuDefinitionResolver {
  constructor(private readonly prisma: PrismaService) {}

  @Query()
  @Roles('REGISTERED')
  async tuDefinition(@Args() args, @Info() info) {
    return await this.prisma.binding.query.tuDefinition(args, info);
  }

  @Query()
  @Roles('REGISTERED')
  async tuDefinitions(@Args() args, @Info() info) {
    return await this.prisma.binding.query.tuDefinitions(args, info);
  }

  @Query()
  @Roles('REGISTERED')
  async tuDefinitionsConnection(@Args() args, @Info() info) {
    return await this.prisma.binding.query.tuDefinitionsConnection(args, info);
  }

  @Mutation()
  async createTuDefinition(@Args() args, @Info() info) {
    return await this.prisma.binding.mutation.createTuDefinition(args, info);
  }

  @Mutation()
  async updateTuDefinition(@Args() args, @Info() info) {
    return await this.prisma.binding.mutation.updateTuDefinition(args, info);
  }

  @Mutation()
  async updateManyTuDefinitions(@Args() args, @Info() info) {
    return await this.prisma.binding.mutation.updateManyTuDefinitions(args, info);
  }

  @Mutation()
  async upsertTuDefinition(@Args() args, @Info() info) {
    return await this.prisma.binding.mutation.upsertTuDefinition(args, info);
  }

  @Mutation()
  async deleteTuDefinition(@Args() args, @Info() info) {
    return await this.prisma.binding.mutation.deleteTuDefinition(args, info);
  }

  @Mutation()
  async deleteManyTuDefinitions(@Args() args, @Info() info) {
    return await this.prisma.binding.mutation.deleteManyTuDefinitions(args, info);
  }
}

---

Deprecated dependency concern

graphql-cli@latest has a dependency on apollo-codegen@0.20.2.

$ npm view apollo-codegen
DEPRECATED!! - The 'apollo-codegen' command has been replaced with the more-powerful 'apollo' CLI. Switch to 'apollo' to ensure future updates and visit https://npm.im/apollo#code-generation for more information.

$ npm ls graphql
+-- graphql-cli@3.0.14
| +-- apollo-codegen@0.20.2
| | `-- graphql@0.13.2         ←------- Notice this dependency
| +-- graphql@14.5.4  deduped
| `-- graphql-schema-linter@0.2.1
|   `-- graphql@14.5.4  deduped

Due to apollo-codegen being a deprecated library, it is pulling in an old version of graphql. This mismatch in graphql versions is causing npm to not dedupe the dependency. #366 (comment) This has caused me problems with apollographql/apollo-tooling in the same project as graphql-cli. Apollo would force me to only have 1 version of graphql in my node_modules folder. I would have to manually delete the old version of the pulled in graphql dependency every time I did a npm install. Fortunately, in recent updates, this issue of having only one version of graphql in the node_modules folder no longer seems to be an issue for us. At any rate, it would be really nice if there could be something done about this deprecated dependency.

[andycmaj]

One thing i liked about graphql-cli's vs graphql-codegen is the ability to generate a full graphql typescript client with query/mutation/subscription functions that mirror all the possible graphql types.

for example (from hasura schema):

const userConnections = await client.query.userDataSource({
    where: {
      dataSourceId: { _eq: 'pocket' },
      _or: [
        { lastSuccessfulPoll: { _is_null: true } },
        { lastSuccessfulPoll: { _lte: '2019-09-01T22:02:07.000Z' } },
      ],
    },
  });

AFAICT, graphql-codegen only supports generating the types themselves, and you then have to use apollo client or similar to execute the queries...

can you talk a little bit about how the client-generation fits into your roadmap? This is fairly important to me as I use the generated Binding types and client in node projects (non-react, for example) that use graphql data access.

(cross posted from dotansimha/graphql-binding#325 (comment). not sure which is the appropriate place to discuss this use case)

[wtrocki]

@joelbowen

Mock data API server. For a while on the README it has listed graphql-cli-faker as "coming

This is already possible using https://github.com/Urigo/graphql-cli/blob/master/packages/commands/serve/src/index.ts

To make it more roboust this can be the responsibility of the generate command that will have some layers that developers can use.

Step 3 is usually to add in the Voyager plugin

This will be awesome as app template that has voyager enabled.
It will be awesome to get a separate issues to facilitate discussion,.

---

Access to Prisma GraphQL connections (cursor-based data paging)
Access to Prisma server Subscription endpoints to react to any mutations occurring on a GraphQL type. Reactive, type safe, real-time networking over websockets for free!
Prisma data loader optimizations for resolving queries efficiently (solving the N+1 problem)
Prisma generated GraphQL SDL file to allow for remote schema introspection (query code completion)

@ZenSoftware Those are the use cases that generate command can provide. Underlying lib (https://graphback.dev)) will support data-loading layer along with connections etc. All in the next release. Current generate is very simple as we wanted to integrate as fast as possible for feedback

---

@andycmaj

This is currently possible using graphql generate command. All queries are generated. If you like to have a separate command for this purpose let us know.
Additionally, we are going to extract current logic to graphql-code-generator so all capabilities can be used in more seamless fashion.
See aerogear/graphback#410

[peterdresslar]

Integrate GraphQL Boilerplates?

From Discord (humarkx / ardatan )

who does maintain https://github.com/graphql-boilerplates/typescript-graphql-server/tree/master/advanced ?

graphql-boilerplates

[peterdresslar]

Docs pages, create them

[remorses]

Stop splitting the code in dozens of packages, why should i download all these different plugins before using the cli?

The reasons to stop using “plugin system” are obvious to me:

• The time spent resolving the packages from npm is greater than simply download all the code,
• conflicts between packages will be inevitable given that there are plenty of peer dependencies that the user should update manually (i won’t even remember the names of all these plugins)
• difficult local development

[dotansimha]

@remorses I can under your point of view. But, we would like to have a generic CLI for GraphQL, that isn't too much opinionated.

• The plugin packages are less than 1KB is most cases, so I can't see why it will make Yarn/npm too much time to download. Do you really consider that as something that might delay Yarn or Npm? you already install a huge amount of dependencies every time.
• Conflicts are easy to resolve - just use the same version for all plugins. We are publishing with --exact and --force-publish for that exact reason.
• Development is super easy with Yarn Workspaces - just yarn in the root and all links are being set. Changes in the source code should be compiled during dev time - personally, I don't think it's a big deal, takes less than a second, and in the CLI case, it's just a matter of one common lib.

I think it's a matter of preference, and the reasons for choosing a plugin system are:

• Create a basic CLI with the core functionality and allow others to extend it.
• Less opinionated about tooling (for example: GraphQL Code Generator or Apollo Codegen).
• Easier for the community to create new plugins and build community around their tools.
• Easier to create local plugins for custom behaviour (no need to publish to NPM).
• We are using --exact always, so it makes it easier to avoid conflicts.
• We implemented a similar solution in GraphQL Code Generator and ever since it's easier to maintain and have the community on board.

We are thinking about adding some plugins as default, it might make it a bit opinionated but will reduce the need for installing all default plugins.

One more thing, we encourage people that are building GraphQL tools that has CLI to build a simple plugin instead of maintaining their own CLI wrapper, and have the benefit of using GraphQL Config and GraphQL CLI which loads schema and documents in an easy way.

I hope this covers the background for choosing that. If you really think it's something we should improve - feel free to share an alternative solution that answers the requirements above :)

[Diluka]

auto detect eslint config and ask to add @graphql-eslint/eslint-plugin and do configurations