GraphiQL Working Group 10th March 2020

Agenda

1. Introductions
2. re-architecting GraphiQL
3. GraphiQL Plugins
4. Redesign implementation
5. Surprise Item

Promoting the WG Meetings & Scheduling

• Rikki:
• Initially announced this via Twitter and Discord; that was not sufficient - sorry!
• Emailed people directly yesterday, but unfortunately late notice for some
• Plan to make an email chain
• There’s support for a bi-monthly working group (every fortnight / two weeks)
• Orta: who’s interested in that?
• Justin: increased cadence may be better for people actively working on the project
• Rikki: another option is once a month for LSP, another for GraphiQL
• Justin: Relay integration at Artsy is important; there’s a lot of things happening in the Relay ecosystem - we’re keeping an eye on it and will look to get involved in future if need be.
• Rikki: awesome! Help on the LSP in particular would be helpful
• Justin: there’s no committed resources at this time, but it’s something that we’re keeping an eye on and may be able to help in future
• Benjie: we can spawn out sub-groups to work together more tightly on specific issues, like the GraphQL WG does.
• Benjie: I think we should differentiate between what should be done (responsibility of the working group) to how it should be done (responsibility of individuals within WG, who can self-organize through GitHub/Discord/etc)
• Rikki: I was considering doing “office hours” - an open zoom call for an hour every week where people can ask questions/learn how to collaborate whilst I work on stuff.
• [RELEVANT TO NON-ATTENDEES] Rikki: let us know if this timezone doesn’t work for you.

Re-architecting GraphiQL

• Rikki: GraphiQL launched in 2015, did a great job of using the first class features of React at the time like this.setState, which worked well. However, the more modern React state management capabilities combined with context and things like useReducer might be one of the best ways to share state and event handlers/capabilities with plugins without having to pass props around a bunch. State is best kept within a component, so useReducer is probably better for more complex state management concerns - this is the approach we’re taking.
• There’s a working PR #1359
  • Breaks some interfaces
  • Re-architects how state is managed
  • See “useSessionContext” from “GraphiQLSessionProvider”
  • This branch works; not for multiple operations in a query, but it does work.
  • We’re removing state from the root GraphiQL component.
  • A lot of progress has been made.
  • The goal is to get an API like [INSERT NOTION LINK]
• Justin: how are the phases defined?
• Rikki: See the “Feature Roundup” GitHub project in the GraphiQL repo - this is effectively the MVP for v1.0
  • We may move some of these features out if we need to
  • Maybe we’ll assign them to milestones?
• Justin: that makes sense - having an idea of what items need to be fixed to get to alpha/beta would help people know what’s going on.
• Rikki: right now we’re focussed on core
• There’s an alpha release of GraphiQL out there - conversion to TypeScript and some bugfixes. After the state refactor we’ll release another alpha so people can start testing it for regressions. Then we’ll start integrating Monaco with GraphiQL for the next alpha release.
• The reason we are adding Monaco so early on is because the plugin API will be building heavily on Monaco.
• One issue with Monaco is that it relies on web workers, so we’re going to make sure there’s some nice abstractions and that we can leverage the webpack plugin and have guides for other bundlers to show how to put GraphiQL Beta into your project and ensure all the web-workers are working.
• Justin: we need to be careful to not re-render too frequently with reducers.
• Justin: I’m concerned about the complexity of exposing too much external state from plugins.
• Rikki: I wanted to try and keep it simple at first, but because there was complex demands with GraphQL Explorer and various other IDE projects that need access to the deeper internals.
• Justin: my main concern is the specific reducers because it means that plugins need to have knowledge of the state, and then the internal state becomes an API which means we cannot change things easily.
• Benjie: we shouldn’t expose the reducers directly, and we should expose something like selectors rather than the state itself - that way we can change how the underlying state is structured without breaking downstream applications.
• Benjie: all callbacks should be passed an object argument so that more properties can be added later.
• Lazy AST generation should be done in such a way that intermediate states can be skipped (e.g. if a user types 12 characters quickly whilst the first AST is still being generated, the next AST can skip to the end rather than having to be built for each character added)
• onChange callbacks need both the text and the cursor position
• Rikki: I’m trying to use “operation” rather than “query” because it could be a mutation too
• Benjie: agreed; the GraphQL HTTP Spec uses query/variables/operationName for backwards compatibility; if you think this is worth changing we should raise it as an issue for GraphQL HTTP 1.0 spec.
• Justin: exposing hooks that abstract away what we’re doing under the hood gives us the ability to refactor internals for performance. We need to be careful that things don’t misuse context and cause serious performance issues.
• Two important things raised - useReducers - does it have negatives? And context - does it introduce performance issues?
• We won’t merge the PR until we’ve fully evaluated these things. We need to profile it and test performance and make sure that the React profiler is happy.

GraphiQL Plugins

Redesign Implementation

• Rikki: Laura has been using theme-ui to build Orta’s design system for the new GraphiQL in Storybook. That includes a ThemeProvider in context for managing your theme object, this allows you to register themes as plugins - really exciting.
• Cosmetic changes need to be put on the back burner because we’ll be stripping out CSS and making significant changes using different components.
• This design system allows plugins to use these styles to add tabs, views, etc. Plugin developers shouldn’t have to think about theming. (They can if they want, but they don’t have to.)

Documentation

• We’ll have a Gatsby documentation site
• We already have a TSDoc documentation which is a great way to keep abreast of how GraphiQL is advancing
• What do we think about ide.graphql.org? Devtools.graphql.org? graphql.org/dev ? graphiql.graphql.org ? dev.graphql.org?

Surprise item

• GraphQL Playground is merging efforts with GraphiQL
• GraphQL Playground will become a set of plugins, themes and configuration for the new GraphiQL

Other

• https://hotchocolate.io/docs/batching
• Defer/stream
• AST should be generated in a debounced way, e.g. using a background worker or idle callback, so that we don’t suffer performance issues
• Multiple operations can use the debounced AST, or calculate AST when clicked
• Introspection queries are becoming dynamic

Google Summer of Code

• Deadlines
• Interns for GraphiQL plugins
• Rikki is taking time to help people form proposals for plugins that they can write to help with GraphiQL v1.0 via GSoC.
• Rikki plans to tag tickets with “good first time plugin” / “good first time issue” to help people find things to do
• Sean: recovering parser could be a good GSoC task because currently prettifying drops comments