Andrew Welch · Insights · #graphql #PhpStorm #craft-3

Published , updated · 5 min read ·


Please consider 🎗 sponsoring me 🎗 to keep writing articles like this.

GraphQL Schema Auto-Completion with PhpStorm

The JS GraphQL plu­g­in com­bined with a lit­tle mag­ic will give you full auto-com­ple­tion and syn­tax high­light­ing of GraphQL schemas in PhpStorm

GraphQL is a query lan­guage that’s gain­ing in pop­u­lar­i­ty these days, and if you’re using Php­Storm there’s a fan­tas­tic plu­g­in called JS GraphQL that will make your expe­ri­ence much more enjoyable.

Once prop­er­ly con­fig­ured, the JS CraftQL plu­g­in will give you:

  • Syn­tax high­light­ing for GraphQL queries, even embed­ded in React or Vue components
  • Auto-com­ple­tion of your GraphQL schema in Php­Storm, just like in GraphiQL or GraphQL Playground
  • Works with pop­u­lar schema gen­er­at­ing frame­works like Gats­by or Grid­some, or any GraphQL endpoint

…and there’s more too, but these fea­tures alone make it invalu­able if you’re doing much of any­thing with GraphQL.

It also is extreme­ly help­ful when you’re learn­ing GraphQL as well. So let’s get it installed and configured!

Link Make it go

So the first thing you’ll need to do is install the JS GraphQL plu­g­in in Php­Storm by going to Pref­er­ences → Plu­g­ins and click­ing on Mar­ket­place. Then search for the plu­g­in, and install it.

Next you’ll need to cre­ate a file named .graphqlconfig in your project root that looks like this:

{
    "name": "Craft App",
    "schemaPath": "project_schema.graphql",
    "extensions": {
        "endpoints": {
            "Remote GraphQL Endpoint": {
                "url": "http://localhost:8080/___graphql",
                "headers": {
                    "Authorization": "Bearer TOKEN"
                },
                "introspect": true
            }
        }
    }
}

The schemaPath key is the where the schema dump from your GraphQL end­point should be saved. If this file exists, the JS GraphQL plu­g­in will use the schema def­i­n­i­tions in it for auto-com­ple­tion, syn­tax high­light­ing, etc.

If this file does­n’t exist, the JS GraphQL plu­g­in can intro­spect your GraphQL end­point spec­i­fied in url to dump the schema def­i­n­i­tions out to the schemaPath file.

In our case, we’re using the GraphQL end­point pro­vid­ed by Gats­by or Grid­some, run­ning in our local dev environment.

How­ev­er, you can use any GraphQL end­point you like, and con­fig­ure it with Autho­riza­tion head­ers or what­ev­er you like, as per the JS GraphQL plu­g­in doc­u­men­ta­tion.

Once you’ve set up the .graphqlconfig file, there are two ways you can gen­er­ate the ini­tial schema dump. When your project is opened, you’ll see a ​“Toast” that asks you if it should get the schema from the endpoint:

Get GraphQL Schema from End­point Now?

If you click on the Intro­spect link, it’ll then query your GraphQL end­point and dump the schema. How­ev­er, re-open­ing your project just to have it pick up schema changes is a bit much, so you can also click on the ⏩but­ton in the JS GraphQL Tool window:

Update Local Schema button

Pro Tip: make sure your GraphQL end­point is run­ning when you try to dump the GraphQL schema!

Once the schema dump has been gen­er­at­ed, you’ll be able to see the result­ing schema dump file and JS GraphQL status:

GraphQL schema dump result

Once we have our GraphQL schema dump work­ing prop­er­ly, we then just need to tell Php­Storm where we want to do a lan­guage injection.

Php­Storm is pret­ty amaz­ing at doing syn­tax high­light­ing, but if we’re doing GraphQL queries inside of Gats­by or Grid­some com­po­nents (or even just inside of JavaScript), it needs a lit­tle help.

So just select the text that is GraphQL and click on the light­bulb that appears:

GraphQL Lan­guage Injec­tion Selection

Then choose Inject lan­guage or ref­er­ence → GraphQL:

GraphQL lan­guage injection

You only have to do this once, and from then on Php­Storm will auto­mat­i­cal­ly do the lan­guage injec­tion for all files in your project that have the same extension.

Then we have love­ly syn­tax highlighting:

GraphQL syn­tax highlighting

…as well as auto-com­ple­tion of your schema:

The won­der­ful thing about this is that it works inside of Vue tem­plates, React com­po­nents, and with gen­er­a­tors like Grid­some & Gats­by… whatever!

This write­up was based on the gist that Josh Angell and I worked on at the DotAll 2019 conference.

Hap­py querying!