Path to GraphiQL v2

[timsuchanek]

We have ambitious plans for the future of GraphiQL and want to go there step by step.

This is the path I suggest to move forward:

1. Implement new design with existing components

• Implement new design with CodeMirror 5 #2325

2. Modernize components step by step

As the new design has a slightly different layout, in Step 1, the components can already be modernized as needed.
If necessary, we'll create a separate issue for tracking work that's left.

3. Introduce monaco

• Integrate monaco-graphql into main GraphiQL #2326

4. Implement the new sidebar.

The new sidebar is quite ambitious, that's why we want to work on it last.

• Implement new docs explorer #2327

Additional tasks

While working on this, we want to revisit and consolidate the boards @acao created:

• GraphiQL Roadmap (view)
• GraphiQL Roadmap (view)
• GraphiQL Roadmap (view)
• GraphiQL Roadmap (view)

Some of the issues will be fixed by our tasks above, some are additional improvements, bug fixes, and features.

We'll have @thomasheyenbrock from GraphCDN focus on steps 1-4 in the coming weeks.
Anyone who's interested in collaborating, please let us know and we can organize code pairing sessions!

We also commit to 1h of issue triaging per week, as some of them grew a bit old. We start May 2nd at 4 pm UTC. Let me know if you want to join. Calendar link:

https://calendar.google.com/calendar/u/0/embed?src=linuxfoundation.org_ik79t9uuj2p32i3r203dgv5mo8@group.calendar.google.com

You can either answer here or join the graphiql Discord channel.

[timsuchanek]

See for reference #2122, which also tracks complementary issues

[acao]

@timsuchanek the github project tabs are just filters based on label, you can remove them readily but then you'll have a huuuge list if that's ok! the main goal was to separate out monaco-graphql related work so as not to scare away folks who just want to work on the react side of things.

there are still some final things we need to add for monaco-graphql, such as providing API options so graphiql can navigate to the right doc entry when clicking on keywords (for example, click on a field and watch!), and similarly for hover and completion docs, so that we can have feature parity. There is a user defined spec for this floating around in our issues.

[timsuchanek]

Awesome, thanks for the context, we'll have a look into those tasks once we tackle any monaco-graphql related things. I'll also ping you again before working on it just to make sure we don't miss anything, as you have most of the context.

[acao]

Oh perhaps you missed the discussion on discord where I will be working on monaco editor adoption in parallel!

i was just commenting on this:

While working on this, we want to revisit and consolidate the boards @acao created:

[n1ru4l]

How will this path be represented in releases?
When I think that each step could be an individual release step 1 would already be a huge breaking change if shipped 🤔 .

The following order seems to make more sense to me:

1. Modernize components step by step (new minor)
   1.1. move to hooks
   1.2. use context API where it makes sense
2. Introduce Monaco (new minor as there are no APIs for directly hooking into codemirror AFAIK)

Entering breaking change land

3. Implement new design with existing components (major - alongside with this release it might then also make sense to revisit GraphiQL props and adjust the API)
4. Implement the new sidebar (new minor)

[acao]

this makes sense to me! this is almost the exact same roadmap we took in 2020 and it worked out great. the only mistake we made is that we didn't release incrementally as you indicate

we had most of the components converted to hooks and context two years ago, so that should be a great point of reference for anyone who wants to embark on this again! Just ignore the monaco specifics, and localisation, and take into account all the functionality we've added since

the move to context allowed us to seperate out the business logic into context providers and react useReducer(), leaving graphiql.tsx at only 800 LOC!

[acao]

monaco itself will also incur a ton of breaking changes implicitly, such as entirely different keybindings, entirely different customTheme prop values, etc, so it might warrant a 2.0 itself, and the redesign a 3.0

[thomasheyenbrock]

Just to clarify @n1ru4l @acao: Would you release the redesign with a new major version even when there wouldn't be changes to the API (exported methods, component props, etc.)? Or do you just think it's not possible to avoid breaking changes there given the new design?

[acao]

@thomasheyenbrock sorry, to clarify, adding monaco-graphql would necessitate breaking changes to the GraphiQL props API. as nice as it would be to just be able to swap out the underlying implementations, we have props that map very specifically to codemirror settings, and also tons of keybindings that users use every day that would just stop working, so it would feel like a major breaking change to users

monaco may also be incur some breaking changes to configuration setup, especially for CDN users

[acao]

@thomasheyenbrock I don't think they need to go hand in hand. one can happen without the other, in whichever order. I indicated differently to @timsuchanek at one point but I've changed my mind after spending some more time on it again.

the WIP that comes second will need to rebase for the upstream, but it will be worth seperating the efforts

the editor components have almost no associated styling in either case, so it should be pretty straightforward in that regard

[thomasheyenbrock]

I agree, Monaco is for sure a breaking change. I agree, introducing Monaco and reworking the UI are two separate tasks that don't have to be done in one release 👍 Also, I don't have anything against releasing the redesign as v3 since the way we'll change the UI can be considered breaking even though there might not be actual API changes if we do Monaco in a separate release.

[acao]

yes, the only API changes caused by the monaco release will be to the editorTheme prop, and a few other GraphiQL props. very minor breaking changes. from a release-notes-as PR/FAQ method, we can propose the monaco release will work like this:

congrats! there are only a few breaking changes in this release, such as allowed values for editorTheme prop. the greatest breaking change will involve learning the new keybindings. here is a document that explains the new monaco keybindings. if you're used to vscode, you'll find a lot of familiarity :)