@apollo/explorer
v0.1.0TypeScript
This repo hosts the source for Apollo Studio's Embeddable Explorer
0/weekUpdated 2 weeks agoMITUnpacked: 88.9 KB
Published by packages@apollographql.com
Apollo Studio Embeddable Explorer
This repo hosts the source for Apollo Studio's Embeddable Explorer
Using the @apollo/explorer npm package
You can download the @apollo/explorer npm package with npm install @apollo/explorer. Then, you can import the ApolloExplorer class or ApolloExplorer component like so:
``
import { ApolloExplorer } from '@apollo/explorer';
import { ApolloExplorer } from '@apollo/explorer/react';
When you call the EmbeddedExplorer constructor with a target of an html div you have in your app, the Explorer will show up in an iframe in that element. Check out all the configuration options for your graph.
$3
`
import { ApolloExplorer } from '@apollo/explorer/react';
function App() {
return (
endpointUrl='https://acephei-gateway.herokuapp.com',
initialState={{
document: query Example {
me {
id
}
},`
variables: {
test: 'abcxyz',
},
displayOptions: {
showHeadersAndEnvVars: true,
},
}}
/>
);
}
$3
`
import { ApolloExplorer } from '@apollo/explorer';
function App() {
...
new ApolloExplorer({
target: '#embeddableExplorer',
graphRef: 'acephei@current',
endpointUrl: 'https://acephei-gateway.herokuapp.com',
initialState: {
document: query Example {
me {
id
}
},
variables: {
test: 'abcxyz',
},
displayOptions: {
showHeadersAndEnvVars: true,
},
},
})
...
}
...
// style the iframe for your site
`
$3
- Embedding a registered public graph
- Usage by directly passing in schema
Developing embedded Explorer
into packages/explorer and run npm run build:umd to build umd files where EmbeddedExplorer is exposed on window.Open
examples/embeddedExplorer/localDevelopmentExample.html to test your changes. (if origin is not set, run localDevelopmentExample.html from Live Server)Install the
Live Server extension on VSCode, then go to localDevelopmentExample.html and click 'Go Live'
$3
cd into packages/explorer and run npm run build:cjs-esm to build cjs & esm files where ApolloExplorer & ApolloExplorer React are named exports.We have a React example app that uses our ApolloExplorer React component to render the embedded Explorer located in src/examples/react-example. To run this example,
npm run build and npm run start in react-example. Make sure you delete the .parcel-cache folder before you rebuild for new changes. (TODO remove parcel caching)$3
#### Connecting to unregistered graphs by directly passing in schema
`mermaid
sequenceDiagram
participant Parent as Parent Page
participant Embed as Embedded Explorer note over Parent: Render iframe loading embed and start listening for messages.
Parent->>Embed: Embed loads with initial state
(gql operation, variables, headers, persistence preference etc)
in the query params of the iframe.
note over Embed: Loaded and sets initial state
from query params.
note over Embed: Start listening for messages
Embed->>Parent: Handshake message asking for schema
Parent->>Embed: Responds with schema
note over Embed: Loads in given schema to explorer
Embed --> Parent: Set up finished
note over Embed: User submits operation
Embed->>Parent: Send request contents
note over Parent: Makes actual network request via
handleRequest()
Parent->>Embed: Send network response back
note over Embed: Processes and renders response
#### Connecting to registered graphs by authentication
mermaid
sequenceDiagram
participant Parent as Parent Page
participant Embed as Embedded Explorer
participant Login as Studio Login Page at
studio.apollographql.com note over Parent: Render iframe loading embed and start listening for messages.
Parent->>Embed: Embed loads with initial state
(gql operation, variables, headers, persistence preference etc)
in the query params of the iframe.
note over Embed: Loaded and sets initial state
from query params.
note over Embed: Start listening for messages
Embed->>Parent: Handshake message asking for graphRef,
account id & account invite token if provided
Parent->>Embed: Responds with graphRef, account id, account invite token
Embed->>Parent: Authentication message asking for second half of
authentication token from parent page local storage
alt when parent page has authentication token or graph is public
Parent->>Embed: Responds with half auth token
from parent page local storage
else when parent page doesn't have authentication token
note over Embed: Renders login page
note over Embed: User clicks 'login' on embed
Embed ->>Login: Embed opens a new tab to
login page via window.open
note over Login: Asks user to authenticate and
authorize this embed to use account
note over Login: User accepts
note over Login: Login page generates new
Studio API Key for this user
Login ->> Embed: Sends Studio API Key over
postMessage via window.opener
note over Embed: Splits key in 2,
stores half in local storage
Embed ->> Parent: Sends other half of key to parent page
note over Parent: Stores half of key in local storage
Parent->>Embed: Responds with half auth token
from parent page local storage
end
note over Embed: Merges half key from parent page & half from embed local storage.
Uses this key for all future requests to Studio backend.
note over Embed: Loads in schema & operation
collections for given graphRef from Studio servers
Parent --> Login: Set up finished
note over Embed: User submits operation
Embed->>Parent: Send request contents
note over Parent: Makes actual network request via
handleRequest()
Parent->>Embed: Send network response back
note over Embed: Processes and renders response