Discussion: The interface for a graphiql plugin

[orta]

This does not aim to be definitive, but to start discussion based on some rough ideas based on safe design assumptions.

Someone can probably think a bit more about how it can architecturally work, but using this as a general reference:

I think each sidebar tab should be owned by a plugin e.g. the documentation :

Is a system default plugin. Which is where this could be first built out, as a part of refactoring the current graphiql.

Systems owned by graphiql core

All the UI to the right hand side.

• Keeping an in-memory copy of the schema
• Handline text editing
• Handling making the request
• Handling the response view

Plugins should be able to

• read / edit the query (+vars) (e.g. the selecting a saved query, a query builder plugin )
• read the schema (for search, or documentation)
• act on making a request (customizing request, changing headers, keeping query history)
• extend the in-memory schema for a particular field (for example the table in postgraphile, or syntax examples for other Langs)
• provide warnings/errors (I'd expect syntax should live in core, but I could see plugins wanting to provide more strict rules around deprecations etc)

[orta]

Other potential avenues:

• On launch, a plugin could declare it should be at the forefront (e.g. you could do a hyperlink to the documentation of a type)
• Every plugin could receive a request for query params (in terms of the browser URL) which can be saved
• The graphiql core could offer to a plugin a highlight hex code for GraphiQL, so that a company can brand the colour scheme

[benjie]

Great start, @orta. I'll be writing up my thoughts in the next couple weeks when I get a chance.

[acao]

This looks great so far!
These all sound like things that could be accomplished with simple react component composition, an exported, shared context and useContext() with react hooks, and styled-components themes. Creating and maintaining our own plugin system could potentially distract us from what the intended purpose of graphiql, which is a minimal IDE implementation. I'll come back with a proof of concept here shortly, but it could look like this (psuedocode):

import { GraphiQLContext } from 'graphiql'
import GraphiQL from 'graphiql-components'

import MyGraphiQLComponent from 'graphiql-component-custom'

// configure store
GraphiQLContext.configure({
  storage: window.localStorage,
  namespace: 'myGraphiQLExample'
})

const myTheme = {
  main: 'red',
  secondary: 'blue',
  fontFamily: 'Helevtica',
}

export default = () => (
<GraphiQL theme={myTheme} {...configOptions}>
  {({ currentQuery })=> {
    <GraphiQL.Wrapper logo={'ourlogo.png'}>
      <GraphiQL.Tabs />
        <MyGraphiQLComponent  />
        <DocExplorer  />
        <QueryHistory  />
      </GraphiQL.Tabs>
      <QueryEditor >
      <ResultViewer >
    </GraphiQL.Wrapper>
  }}
</GraphiQL>
)

// MyGraphiQLComponent.js
import React, { useContext } from 'react'
import { GraphiQLContext } from 'graphiql'
import { styled } from 'styled-components'

const MyGraphiQLComponent = () => {
  const { currentQuery } = useContext(GraphiQLContext)
  return <div>{currentQuery}</div>
}

export default styled.MyGraphiQLComponent`
  background: black;
`

With our underlying components already utilizing the same default context

[SwiftSafe]

IoT is a platform to connect the things which have an internet. A connected device is a complex solution, with various potential entry doors for an attacker. A connected device pentest IoT includes tests on the entire object ecosystem. That is electronic layer, embedded softwares, communications protocol, servers, web and mobile interface. The pentest on the electrical side,embedded softwares, and communication protocol concern vulnerabilities more specifically the IoT.
There are three types of attacks on connected objects and embedded systems. Software attack, non-invasive and invasive hardware attacks. The first take advantage of software vulnerabilities, the second recover information from the hardware without damaging it while the third involve opening the components and therefore destroying them in order to be able to extract secrets. While the first two types of attacks do not require many resources, this is not thecase for invasive attacks, for which very expensive equipment is requires.

1. Increase Visibility Across Siloed Business Functions to Improve Business Maturity.
2. Drive Innovation with Data Analytics.
3. Improve Efficiency with Fleet Monitoring
4. Gain Real-time Insights from Connected Assets.
5. Increase Production with Data Analytics.
6. Monitor Workers to Mitigate Risk.

[acao]

On second thought, I'm inclined towards a lightweight plugin interface, as per benjie's comments on #828

[benjie]

(Comments were in #828)

[acao]

@benjie in addition to your own experience with postgraphile, and my own experience with a microservices-based plugin system, here's some good prior art, via our friends at insomnia:

plugins: https://github.com/getinsomnia/insomnia/tree/develop/plugins
themes: https://github.com/getinsomnia/insomnia/tree/develop/plugins/insomnia-plugin-core-themes/themes
plugin interface: https://github.com/getinsomnia/insomnia/blob/develop/packages/insomnia-app/app/plugins/index.js (they're using electron, so they get to leverage node.js framework modules)
theme interface: https://github.com/getinsomnia/insomnia/blob/develop/packages/insomnia-app/app/plugins/misc.js

I still vote for styled-components for themes, and what seems to be missing here is how to provide react components via plugins, but I don't think that'll be terribly difficult.

I also like your idea of the eslint-style configuration, so that the server or browser-level config can be composed as presets or line-by-line plugins with optional configuration.

Also, to counterpoint my other suggestions further, we can obviously export components from the plugins themselves. So, if you had a project where you wanted just the doc explorer component, you could do:
import { DocExplorer } from graphiql-plugin-doc-explorer/components

[imolorhe]

I think another well implemented plugin system would be the gatsby plugin system:

https://github.com/gatsbyjs/gatsby/tree/master/packages

https://www.gatsbyjs.org/docs/plugins/

I wonder if there is a way to allow plugins to be installed at runtime, rather than at build time, assuming all I want is just a way to test graphql queries, as opposed to having to build my own GraphiQL mix and running it on a server somewhere.

PS: I am trying to explore that in Altair at the moment, although it would be less efficient than a plugin added at build time.

[BrunoScheufler]

@imolorhe maybe this at-runtime idea could be realized by finding a way to load plugins from external sources dynamically and hooking them into specific workflows, although that might become very hacky. Another idea could be to simplify the steps of setting up a graphiql instance with your plugins of choice so lowering the entry barrier of setting up a new server instance running graphiql w/ plugins, maybe some tooling.

[benjie]

Another plugin system worth researching is that used in the https://unified.js.org/ family of text (markdown, HTML, natural language) utilities - it's very comfortable for users to consume.

[eapache]

One addition I think we should make to the "Plugins should be able to" list is changing the target schema and/or triggering a reload of the schema. At Shopify we have several use cases for a GraphiQL plugin that could e.g. change which schema or which version of a schema is being hit. The actual request is probably covered under "act on making a request (customizing request, changing headers, keeping query history)" but it's equally important to be able to make sure the correct schema is loaded for documentation, autocomplete, etc.

[acao]

@BrunoScheufler @imolorhe agreed with installing plugins at runtime!
possibly we could use dynamic imports and CDN packages, similar to how jsfiddle or codesandbox might handle it. not to get too into implementation details, but using the import() polyfill and/or https://github.com/jamiebuilds/react-loadable might be an approach?

that said, there will be a default build of graphiql for that case @imolorhe, probably on a CDN. @benjie had the idea of using an eslint style configuration format, so it would essentially be graphiql:recommended, whereas the barebones simple editor without history/doc explorer?/etc would just be a graphiql preset, so to speak

[acao]

Update: As per an email discussion, it looks like @schickling is interested in the new graphql-playground possibly shipping as a build of the new GraphiQL 1.0 and prisma's own custom plugins/themes.

His words are:

The plans for 1.0 sound great and indeed like you said seem like a fantastic foundation for the next version of GraphQL Playground.

He's very busy ATM and will be participating in these discussions more after Prisma Day. But this is exciting, it looks like we have almost the entire third party GraphQL IDE ecosystem on board with the new plugin interface concept!

[acao]

What do folks prefer in terms of state management? React Hooks? Apollo withClientState perhaps? Trying to imagine how we can allow plugins to access and extend a common, pluggable store.

[benjie]

Whatever we use for state should be simple and have good longevity. We don’t want to have to update our state store when a vendor updates their library. Before we can make a proper decision we need to understand how plugins may affect state - i.e. should GraphiQL Explorer have a separate state store, or should it extend GraphiQL’s built in state with it’s own concerns? I loke shared state as it means plugins can build on other plugins, but care needs to be taken about namespacing.

[Neitsch]

Hey all, I'm super excited about the plans of having a monorepo for IDE + GraphiQL. Unfortunately I missed the GraphiQL WG, but was at the GraphQL WG...

I love the idea of a plugin architecture! Here at FB we had to remove the GraphQL LSP, since it does not have a configurable way to load the schema. Here I echo @eapache's comment that it would be good if this aspect is pluggable. If I recall correctly in the WG group @acao mentioned that the plugin system will be implemented in GraphiQL. Would it be possible to implement it for the LSP as well to support other forms of schema loading?

As a side note, the current way the LSP loads the schema is particularly slow due to usage of graphql-config I think. If we can make the LSP pluggable I'd be happy to help clean this up & test on the FB schema :)

[benjie]

It's not yet clear where the plugin system lives or what it does, but it is clear that different people want different things from GraphiQL, and a plugin system is a great way of achieving this whilst keeping a stable core.

I've been thinking that we need to dip into underlying systems for plugins too, however this doesn't necessarily need to be part of one over-arching plugin system at the GraphiQL level; for example the need that you describe @Neitsch could probably be achieved with some kind of "adaptor" in a similar way to how Express has various session adaptors (stores) to store sessions into different places.

It's not yet clear what the correct direction is, so surfacing these kinds of needs is extremely valuable for helping us figure out what's needed from the plugin system before we get too deep into architecting it. Your input is greatly appreciated, @Neitsch, as is your offer to help! 🙏

[acao]

@Neitsch thats a really great point. Would be great to have you and others here at the next GraphiQL WG next tuesday:

https://github.com/graphql/graphiql/blob/master/wg-agendas/06-18-2019.md

I'm relatively new to maintaining this ecosystem, so pardon me if I need too much explanation. Do you mean making the LSP GraphQLCache pluggable? I could see that being done at the interface level. I could see how cacheing the schema by reading/writing to an SDL file wouldn't scale very well for large schemas like FBs. Are there other parts that you would like to make pluggable? @lostplan what do you think?

@asiandrummer at the the first GraphiQL WG meeting last month gave us a summary of these scaleability and performance issues on the facebook side, maybe we can do a more in-depth study of how we can learn from this for other large scale schemas? I doubt Facebook is the only company running into this issue, and it's a natural consequence of the GraphQL best practice design patterns, so we'd better account for it!

It also seems like there's a need for either or codemirror and monaco-editor in the future, thus different underlying GraphQL LSP implementations themselves could be a possibility, though there is a call for GraphQL Foundation and Apollo to join forces on a single, standardized LSP, which is another issue, but would impact how we would carry this out.

I could see us making this confirgurable at the graphql-language-service-interface level, and then exposing that configuration when configuring graphiql?

As a side note, do you think it could also be compounded by fetching the entire introspection query over the wire when graphiql didMount, and calling buildClientSchema on that result all at once? This is how the schema is initially fetched before it's handed down to codemirror-graphql and thus the LSP. There are users asking for hot loading of this schema which seems like it would be quite an issue for gigantic schemas like FB's (we would make the hot loading optional of course). We utilize a streaming parser already, but possible a streaming fetcher for this would be helpful? Though I'm not sure how buildClientSchema would work without a complete schema?

[benjie]

Hot schema loading already works with GraphiQL, FWIW, you just feed the schema in externally and update that prop when the schema changes. The main issue is that the doc explorer context gets reset. Making as much of the state as possible survive schema replacement is one of my goals (based on our work in PostGraphile); but that shouldn't inflict any performance penalties (compared to the status quo) on users who don't want hot schema replacement.

[mohsen1]

I often use GraphiQL to make a request, copy the response from the API into browser console to do some data massaging to get what I was looking for. A plugin that I will be interested in would be a JavaScript code editor that allows me to do that data massaging without having to copy/paste often large payloads. Hope the plugin API allows such plugins

[benjie]

A plugin that manipulates the data received from the server before displaying definitely seems in scope.

I think you can achieve this with the current GraphiQL by changing what the fetcher function returns; e.g.

const fetcher = async params => {
  const response = await fetch(GRAPHQL_ENDPOINT, {
    method: 'POST',
    headers: {
      Accept: 'application/json',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(params),
  });

  let result = await response.json();

  // TODO: mangle result here

  return result;
}

Be careful not to mangle the introspection results (should be easy to avoid - just don't mangle any properties that start with two underscores __).

[mohsen1]

Let me clarify: I want to write code in the browser UI. Not modifying any of my own application code. Like a 3rd panel that I can manipulate the response and print it out or copy it for my use.

[benjie]

Adding additional panels such as OneGraph’s explorer, header editor, etc is definitely in scope 👍

[acao]

One of the most important developments for this has been our work with the vscode team to adopt monaco for GraphiQL. Part of that is mounting the LSP in the browser, which allows us to add a plugin system much like Typescript's built in LSP plugin system. This LSP already offers many features folks have requested of GraphiQL or Codemirror GraphiQL, for example being able to insert custom fragments in diagnostics and declarations using graphql config files. Adding a plugin system to that, we will be able to allow folks to introduce these plugins at any layer - when invoking the LSP server, when instantiating a monaco editor using our mode, or when creating or configuring a GraphiQL instance.

[acao]

Here is the roadmap to get here:
#983

[ttzztztz]

Should we consider adjusting it to the mobile screen?

[gorfadvijay]

Hello everyone, I am Vijay Gorfad from India.
I am pursuing B-Tech in Mechanical Engineering in NIT, Surat, but I loved programming so I'm a full-stack developer and DevOps Engineer, Looking forward to work on GraphiQL
how can I start ??

[Nishchit14]

@gorfadvijay ask in discord channel, Team is very helpful over there.

[acao]

do folks want to start proposing the literal interfaces for GraphiQL plugins they'd like to use for upvotes here?

I've been prototyping a few different ones, using object literals and functional components and such. Would like to see what folks have in mind!

[baba-ali-graph]

Hello everyone. I'm currently searching for a way to extend GraphiQL and I came across this thread. What's the update on this?

I don't know if this has been implemented. If not, and we have a formal spec, I'm happy to comtribute

[acao]

see the existing plugins in the repo and read e to see how! we are about to rewrite the underlying implementation to use a different state management approach, but the existing hooks API will remain mostly the same, and we will be adding more types of plugins, such as renderless (non presentational), toolbar and per-pane plugins instead of only sidebar plugins. You can find userland plugins in the wild, including one that uses chatgpt!

[acao]

Here is probably the most replete example:

https://github.com/graphql/graphiql/blob/main/packages/graphiql-plugin-explorer/src/index.tsx

Here is an early stage example of a toolbar button plugin, that will soon be more easily available by adding a pluginType: "operationsToolbar" or some such to the metadata

there should be a lot more activity in the coming month, and there are open PRs to add shared tooling and more plugin docs, I can ping you if you'd like to contribute and/or help review!