Ideas for improving the Developer Experience and Feature Discoverability

[FluorescentHallucinogen]

This issue acts as the central place for all discussions of ideas around improving the Developer Experience (DX), Feature Discoverability, Usability and UI design.

1. It would be great to be able to insert all fields of type (check all nested checkboxes at once and then uncheck only unnecessary instead of check them only one by one). This is very useful for types with a large number of fields.

2. If a field is 1) non-null AND 2) leaf (terminal / uncollapsible / has no child fields), it should be 1) checked AND 2) disabled (so the user could not uncheck it).

I've visualized these two ideas. Here's my vision (a slightly modified version of Explorer tab from Playground v2 concept):

Compare it with the original:

[FluorescentHallucinogen]

@dwwoelfel @sgrove @rofrischmann PTAL. 😉

[FluorescentHallucinogen]

I've improved some things:

• It would be great to visually separate the input fields (arguments) from the output (asked) fields by

1. placing input fields into brackets
2. using different colors for input and output fields

• I've used the same colors for the same things in Explorer and Query editor (green for output fields, orange for input fields, etc.).

• I've realized that "Insert all fields" feature should check nested checkboxes only for all output fields, not for input fileds.

• If the input field (argument) is required (non-null), it must be 1) checked by default AND 2) disabled (so the user could not uncheck it) to avoid generating invalid query.

• If the output field is 1) leaf (terminal / uncollapsible / has no child fields) AND 2) the only field of the (parent) type [see the count in the lastMonth on the attached image], it must be 1) checked by default AND 2) disabled (so the user could not uncheck it) to avoid the Field 'xxx' of type 'YYY' must have a sub selection error.

[FluorescentHallucinogen]

Added one small, but very useful thing — field descriptions on hover:

[FluorescentHallucinogen]

Let me explain some important things about checkboxes and rotating triangles that may not be obvious.

1. Rotating triangles indicate that a field has child fields. Leaf (terminal) fields has no rotating triangles. In the current implementation there is no visual difference between leaf (terminal) fields and not, the user can't predict what will happen when he clicks on the checkbox (will it expand child fields or just check it).

2. Only clicking on the checkboxes checks all child fields (checkboxes):

Clicking on the rotating triangles and field names only expand child fields without checking (inserting) them:

This is because inserting all child fileds in GraphQL is, generally speaking, bad practice, and can't be the default behavior. The one of the main ideas of GraphQL is to solve the overfetching problem (when API return additional data that's not needed), it gives you the power to ask (show) for what data you need and get exactly that, nothing more and nothing less. Inserting all child fileds may help to overfetching (if the user doesn't care about removing unnecessary fields). But in some cases the inserting all child fileds feature improves the DX (developer experience), e.g. in the case of very complex (auto-generated) API that has large number of types and large number of fields in each type. In this case, it is faster to check all nested checkboxes at once and then uncheck only unnecessary instead of check them only one by one.

That's why inserting all child fileds should be here, but shouldn't be the default behavior.

[FluorescentHallucinogen]

Here's the updated mockup based on the preview of the new Explorer version:

Please note that I've added a button for adding fragments along with buttons for adding queries, mutations and subscriptions.

[FluorescentHallucinogen]

Everything is clear with the addition of new queries/mutations/subscriptions/fragments, but what about the deletion?

I've added icons to clone (with all checked fields) and delete queries:

These icons are displayed when hovering over the query.

[FluorescentHallucinogen]

Have added support for GraphQL aliases:

You can clone any node (with all child field) as GraphQL alias using the "Clone" icon that is displayed when hovering over the node:

You can remove any alias using the "Delete" icon:

You can rename and edit aliases in your own:

[FluorescentHallucinogen]

The preview of the new Explorer version has one interesting feature — "Jump to definition" via Alt+Shift-click on the field in code editor. But, IMO, it has low feature discoverability. How users learn about this hotkeys?

What about a "View" icon that is displayed when hovering over the field in code editor to focus on this field in Explorer, and vice versa? 😉

[FluorescentHallucinogen]

@JakeDawkins PTAL. What about something like that for Apollo GraphQL for VS Code extension?

[JakeDawkins]

@JakeDawkins PTAL. What about something like that for Apollo GraphQL for VS Code extension?

👋 Yeah! This is beautiful! I'd love to see something like this in the future. We have a bit of work to do in VS Code around stability and service federation before this could be prioritized, but I'll keep it in mind :)

[FluorescentHallucinogen]

I've added icons to refactor/transform any input fields to variables (see altair-graphql/altair#745 for more info). These icons are displayed when hovering over the input fields:

[FluorescentHallucinogen]

@JakeDawkins

I'd love to see something like this in the future.

PTAL at https://marketplace.visualstudio.com/items?itemName=GabrielNordeborn.vscode-graphiql-explorer. 😉

[FluorescentHallucinogen]

Currently, GraphiQL Explorer doesn't support GraphQL list (array) inputs. This is essential feature.

It would be really nice to have the support with ability to:

• insert (append) new field to the list after selected field (Ctrl+Ins)
• duplicate (clone) selected field (Ctrl+D)
• remove (delete) selected field from the list (Ctrl+Del)
• reorder (sort) fields in the list by dragging (moving) selected field (Alt+Shift+Arrows)

Here's my vision:

[FluorescentHallucinogen]

Since we covered all GraphQL built-in scalar types, what about visual forms for commonly used custom scalars like DateTime? 😉

[FluorescentHallucinogen]

File upload is a recent addition to GraphQL. It allows to upload files directly to GraphQL API in addition to sending text data. It uses an Upload scalar. It would be really nice to have a visual form for it too. 😉

[FluorescentHallucinogen]

@Nishchit14 @10S10 PTAL. 😉

[Nishchit14]

You are a gem @FluorescentHallucinogen 🙌 , These all are the killing features.

The most challenging feature I can say is File uploading directly from the explorer, I would say User would be able to upload multiple files as well.

Also, date-picker is nicer, but It'll add extra CSS/JS cost in bundle (plugin system would work great here), later we can add options of formating (dd-mm-yy, ts, ISO, tz, etc)

We're working on a new design of Firecamp desktop app, and to use explorer I need to plan some customization with it. I'll keep sharing suggestions/feedback on DX improvement :)

[FluorescentHallucinogen]

@Nishchit14

I would say User would be able to upload multiple files as well

The user would be able to upload multiple files if so provided by the GraphQL schema, i.e. the mutation argument is an array (list) of Upload scalars — [Upload!]!.

If the mutation argument is an array, it's assumed that the file upload dropzone uses <input type="file" multiple> under the hood. So the user would be able to drag'n'drop multiple files at once, and for each file a new element in the array will be created automatically.

The most challenging feature I can say is File uploading directly from the explorer

Just realized that GraphQL multipart form requests spec requires to use variables to upload file(s).

So I've visualized my vision of the "Variables" panel:

[FluorescentHallucinogen]

Also a variable can be an object:

[Nishchit14]

This is what we have in @firecampapp (https://firecamp.app)

point no.
2. Single/Multiple File upload
4. Interactive Query Variables
https://dev.to/nishchit14/here-is-the-fastest-graphql-playground-3bci

Although it's an old UI in the blog GIF, but a new design will be up in a week.

[FluorescentHallucinogen]

@Nishchit14 Isn't Firecamp open-source? 🤔 Just checked the GitHub repo and haven't found any source codes.

[Nishchit14]

@FluorescentHallucinogen

It's not open source yet, but we've planned for it in the future. we're working on cloud-sync and team-collaboration. Once we release it then start thinking on the OSS model.

[FluorescentHallucinogen]

Since Explorer is just another (visual) representation of code, everything that could be possible via code should be possible via Explorer, and vice versa.

So here's the equivalent of "Insert child (nested) fields" feature described in #10 (comment) and #10 (comment):

Some thoughts: what about removing the field from the autocomplete list if it's already inserted into the query? 🤔 This may improve UX by helping to avoid duplication of fields.

[FluorescentHallucinogen]

Here's my vision of equivalent of "Extract to variable" feature described in #10 (comment):

Also it would be really nice to have the inverse feature — "Inline variable":

[orta]

Agree - to my knowledge this should be feasible in the graphical plugin system! :D

[acao]

agreeing with @orta, should be possible with graphiql plugins via monaco. might be trickier with vscode but maybe there's things I don't know. @rebornix what do you think?

[FluorescentHallucinogen]

@nikolasburk @schickling Looks like Explorer-like autocomplete could be applied to GraphQL code-first approaches too. 😉

It would be really nice to have something like this in Prisma Studio for visual constructing of data filters.

BTW, thanks a lot to @kuldar from @prisma team for sharing a Figma project with me. All mockups in this thread were made using it.

It seems Explorer-like autocomplete could be applied to any TypeScript code. If so, it would be really nice to have this in VSCode (as a plug-in or built-in).

@orta WDYT?

[FluorescentHallucinogen]

The combo of gqless by @samdenty and Explorer-like autocomplete pictured in #10 (comment) would be a DX game-changer! 🤯

[samdenty]

Damn these are pretty cool ideas!

For gqless I have been toying around with the idea, of creating an all-in-one devtools.

gqless will be able to do stuff like auto-dispatch mutations, when you update the cache. So stuff like the Table plugin shown above could be live-editable.

This would require direct integration with the gqless Client (but should be usable without one too)

With the clients Cache keying logic, we can display "references" to GraphQL data (instead of Query -> temporary response) in the devtools.

This would turn the devtools from a REPL, to a full-blown GraphQL data explorer (like MongoDB compass, Prisma's data editor etc.)

[acao]

@samdenty sounds great! we are working with vscode on the monaco-editor LSP immplementation as we speak for GraphiQL plugins, that will make building out these experiences very powerful. We will have a GraphiQL Explorer plugin that uses this new monaco service soon! Codemirror Mode will still be available for folks to support, if they want to add the new GraphQL 15 language features

learn more about all of this work in our roadmap

[FluorescentHallucinogen]

Here's my vision of search options for #28 (#30):

[FluorescentHallucinogen]

I like the idea to combine documentation viewing and query building in Apollo Studio.

4 months ago I proposed this idea for Explorer. See the end of this comment: #44 (comment).

Altair by @imolorhe has a similar feature (adding queries and fragments to code right from docs) for years. See https://altair.sirmuel.design/docs/features/add-queries-and-fragments.html.

@acao What about something like this in GraphiQL?

[acao]

@FluorescentHallucinogen any RFC proposals are still welcome!

if you want to join our plugin API RFC effort so that you can build whatever plugins you want, you are also welcome to join!

we have some different schema/DX approaches we plan on implementing for some plugins, you are free to propose anything you like, and we decide in working groups which plugins to prioritize.

this discussion would have been great for our working group call today, maybe next time?

[FluorescentHallucinogen]

After some thought, I realized that combining docs viewing and query building (while remaining interesting idea/experiment) may be not a good idea from a practical perspective. And here's why:

• They solve different problems. Docs should display some schema things like directives, interface details (like "implemented by" and "required by"), union and type extension (extend type ...) details that don't matter alone out of query building context.

• Navigation is far from perfect for query building. Docs (current Apollo Studio implementation) displays details of each field (level) on separate page. So to add a specific field, you need to open a bunch of pages, and then press the back button many times to go back.

@jglovier @acao cc.

[FluorescentHallucinogen]

BTW, looks like currently there is no integration between GraphiQL Explorer and GraphiQL Docs. It would be really nice if e.g. Ctrl+Click on a specific field in the GraphiQL Explorer would open that field in the GraphiQL Docs.

[acao]

@FluorescentHallucinogen there is integration between the operation editor and the schema explorer at least, when you click a type name on hover. we will be improving the APIs for this, however an API is already available for this, so this capability you suggest could be introduced with a PR to this repository

[FluorescentHallucinogen]

Another crazy idea has came to my mind: a tool similar to GraphQL Editor, but GraphQL Editor is for visual building of GraphQL schemas, and my tool is for visual building of GraphQL queries, similar to GraphiQL Explorer.

@aexol cc.

[FluorescentHallucinogen]

Expanding/collapsing arguments:

[FluorescentHallucinogen]

Marking deprecated fields with an icon and strikethrough text:

[FluorescentHallucinogen]

As a follow-up of my idea of displaying field description popup on hover in #10 (comment) and #10 (comment), here's a visualization of opening docs for the field by clicking on the icon next to it:

BTW, docs for the field can also be opened right from the links in the field hover popup.

This requires the integration between GraphiQL Explorer and GraphiQL Docs.

[mmailaender]

@FluorescentHallucinogen are you programming that, or is that currently only design? And is there any timeline/priority on this? Because I see the issue started already three years ago :)

[FluorescentHallucinogen]

@mmailaender That's currently the only design. I've programmed some of my ideas, but my contribution (see #49 as an example) for some reason is just ignored by project authors without any feedback. :(

[mmailaender]

@FluorescentHallucinogen seems this project is not really active maintained anymore, based what I see from the commit history. Do you know if GraphiQL has any plans about including your suggestions directly into the main product?

[FluorescentHallucinogen]

@mmailaender

Do you know if GraphiQL has any plans about including your suggestions directly into the main product?

I hope so, but I don't know for sure.

See graphql/graphiql#2216. I'm not sure that all my proposals will be implemented, but some of them definitely will be.

GraphiQL has already taken a different path of combining operation building (GraphiQL Explorer) and docs viewing (GraphiQL Docs) into one tool. But my vision is that this is not a good idea, because they solve different problems and this creates visual noise.

[FluorescentHallucinogen]

I've visualized how adding directives and constructing their arguments might look like:

@Nishchit14 @jonathanawesome @thomasheyenbrock @acao @daniman @aexol @imolorhe @doc-jones PTAL.