The 8 Commandments Of LLMs

Basic things (and some vocabulary) to know when working with LLM tools.

1. The model will lie to you

When a LLM model doesn’t know the answer to your question, it can –and will– straight up lie to you. You can design elaborate prompts to try to prevent this but it will still happen.

2. Most LLM tools don’t know how to browse the Web (without special plugins)

One of the most common things that trip people up when using LLM tools is that they will convincingly seem to summarize a Web page or pull data from an URL — even though they usually can’t browse the Web. In other words, most answers based on URLs you give them will be 100% made up. If the tool doesn’t have a plugin that is specifically designed to read URLs, assume the model can’t browse the Web.

3. When sharing an answer (or a screenshot), always include the full prompt

Sharing interesting answers is usually useful only if you remember to share the full query and prompt as well. If you share a screenshot, make sure the full question (and the prompt if any) is displayed as well so that the answer can be replicated.

4. Don’t ask LLMs to do calculations

As the name implies, LLMs are based on (natural) languages. As powerful they are with language, most are absolutely terrible with algebra. Do not try to do maths with LLM tools, and if you for some reason need to, force the model to show as many intermediate steps as possible.

5. Instead of a long and complex query, use several shorter ones

Splitting a complex task into several steps usually yields much better results. In general, if you force the model to work with steps, you can guide it easier and hence get much better results.

6. The output of the tool is fully based on the data it was trained on

All LLM models are trained on a known dataset and they literally don’t know anything that is not in that dataset. (They might hallucinate answers, though!)

Related issue is the knowledge cutoff. For example ChatGPT knowledge cutoff is September 2021, it does not know anything that has happened after that date.

7. Mastering these tools takes time and effort

Like any complex tools, LLMs take lots of practice to master. A whole new field of expertise called Prompt Engineering has been born from the experimenting and learnings of the early pioneers working on these tools. Some speculate that in the near future talented prompt engineers are as sought after as talented developers are today.

If you want to learn and keep up, you need to put the time in and start learning.

8. Learn the basic vocabulary

In order to be able to communicate with others and to learn more, you need to know at least the very basic vocabulary. Here’s some basics terms to get you started:

  • AI (Artifical Intelligence) is an umbrella term meaning everything from Siri to ChatGPT. (Think “motorised transport”)
  • LLM (Large Language Model) is a type of a machine learning algorithm for solving problems using computational linguistics and probabilities. (Think “a car” vs a train or a motorcycle)
  • ChatGPT is a prorietary tool by OpenAI, first published in November 2022. (Think “Porsche 911 GT”)

More advanced terms:

  • The trained LLM algorithms are called models. Some known ones are for example GPT-3, GPT-4 and Claude.
  • Prompts are the initial instructions sent to the LLM model when you query it. They can be complex and lengthy, or something very simple like “You are a helpful assistant”. (See Awesome ChatGPT Prompts.)
  • When the LLM model makes stuff up and lies to you, it’s called a hallucination. All models hallucinate, and often they can be very convincing.
  • Temperature is a feature of an LLM model that describes in layman’s terms how “creative” the output is. The scale goes from 0 (no creativity) to 1 (very much creativity).

Demoscene Nostalgy

Last night in my weekly 90s Night (Finnish) radio show I played the soundtrack of a 1993 demo Second Reality, which got some of the listeners chatting about their demoscene memories. I was surprised to learn that the code for the demo has been released on GitHub and there’s also a very cool deep dive review into it by Fabien Sanglard.

I sometimes have these proud moments when I hack on something small and obscure on my own but it would be really cool to do something collaborative and creative like this with other people. I can’t imagine how exciting and fun it might have been working on something like the Second Reality back in 1993 with primitive tools without even source code management. We have a Finnish saying for doing something just for the love of it: rakkaudesta lajiin.

The Value of Knee-Jerk Reactions

The big news today was that Twitter has accepted Elon Musks offer. Twitter doesn’t make it easy but I’ve always tried to avoid only following people who think exactly like I do. It seems that my timeline is about 50% feeling really good about the news and the other 50% are talking about migrating to Mastodon or crawling back to IRC cave with the other luddites. (I’m permanently in that lovely cave myself so I can make fun of these luddites!)

It’s only been a few of months since I last watched in disbelief as many people were loudly leaving Spotify because some big corporations and elite (even the White House!) were actively spreading disinformation about Joe Rogan in order get him cancelled. Full disclosure: I listen about 50% of Joe Rogan episodes. I strongly disagree with many of his views but I have to say that almost everything that was said about him was either wrong or purposefully quoted in a misleading way. It’s actually super easy to see if you just focus a bit; one side is honest (albeit sometimes intentionally trolling and/or attention-seeking), the other side twists the message and uses traditional propaganda tactics. It’s really very transparent.

I’ll take misinformation over disinformation or plain old censoring every day of the week.

The “funny” thing (I’m not sure what would be the right word here because it’s so tragic) with the Spotify mass migrations was that many people –including Neil Young– jumped over to Amazon, which by almost any measure is much worse than Spotify! Among other things they treat their workers horribly and they go to extremes to avoid paying taxes. In my opinion, at the end of the day, the Washington Post (owned by Jeff Bezos) does much more controlled damage to the society than Spotify does.

But back to Twitter and Mastodon. If Elon Musk buying Twitter causes some people to jump off it, I think it only does good for the whole Web. It’s sad that many still don’t seem to know or understand how easy it is to use multiple sites and apps instead of just hanging at one giant one. It’s good to have alternative communication platforms and different views about things. If these knee-jerk reactions help people to find their way off from the great big walled gardens, it’s new positive for the whole World Wide Web. In the end, even the Spotify migration was probably good for the music industry.

Lastly, I don’t want to come off as being somehow different or better than anyone else. I have my own opinions and pet peeves which get me going. Not too long ago I reacted pretty strongly when 1Password announced some kind of a partnership with some crypto (as in -coin and not in -craphy as they should have) thing which just wwas the last straw for me and I cancelled my account just minutes after reading the news and then virtue signaled about it on Twitter. I’m just like everyone else, but I think I just value free speech more than most.

Hello, WordPress

This blog has seen quite a lot of technical changes since it first launched in 2006. It first run on WordPress.com, I then migrated it to a homemade Django app, then years later into Gridsome app, and now we’re back to (this time self-hosted) WordPress.

Problem with custom blog engines is that they suck. They’re fine for that “12 minute blog” demo but not too much past that. My Gridsome blog deteriorated in few months to a state where I couldn’t get the development site running at all (and I’m an experienced developer) so I decided that it was time to find something that would allow me to write more. So here we are, again, 16 years later.

Hello, WordPress!

The Hidden Value of Magic (and Tailwind CSS)

As I’ve begun the full rewrite process of my Slipmat.io hobby project, I’m astounded how much I’ve been learning from all kinds of things every step of the way, by carefully analysing the old, and making lots of effort in engineering and designing the new. What follows is one of my latest learned lessons that connected some dots between 15 years of working with the Web.

Python is my favourite programming language, and I’ve always stayed firmly with the Django camp as opposed to Flask or any other gazillion alternatives. In the early days of Django (like 15 years ago) I also had lots of reservations against Rails, mostly because I was young and stupid, but also because it had too much magic. The more I’ve worked with JavaScript the more I’ve learned about good architecture and best practises from bad examples, and my views on magic have changed somewhat.

JavaScript is a fascinating language. ECMAscript 2020 is the ultimate lipstick on a pig. The core language is such an awful mess, yet the new syntax is pretty powerful and the modern tooling built around it is truly amazing and wonderful to work with. And as the tools have gotten so much better in a very rapid pace, the community is starting to get the libraries and coding conventions in a better shape as well.

Vue 3 is a great example of this. It’s built totally from ground up using TypeScript, designed with an open RFC process taking feedback from the whole community, and Evan You has done a lot of work shaping the end result into something that’s actually designed to be used and not only something that looks good.

The work on my new Vue 3 project template has advanced to list screens which need various list components, preferably in a form of a powerful datatable component. I had to completely drop the project for a while to get a better understanding what I’d really want here. Today I finally had an epiphany; the thing that’s most wrong in the current Slipmat design are the numerous different random third-party components that even though styled to look somewhat (but not exactly) similar, they all feel different. And this exactly is my issue with glue-in frameworks like Flask as well. Even though the various parts can be easily used together, there’s always something missing compared to tools like Django where everything is built to work together.

So now we get dangerously close to the infamous not invented here syndrome. If gluing up various third-party solutions yields bad results, then surely we should write all components ourselves? Well, no. Firstly, always prefer an existing ui library (like Vuetify for Vue/Material Design) over building anything yourself. Secondly, –and this is again something I realised today– properly architectured third-party components can be not just almost but precisely tweaked to fit your design. And whenever using them, you should take the time to do that design work properly. The main problem with inconsistent Web UIs is handwritten CSS. Whenever a non-designer needs to invent their own styles, the end result will end up looking something that almost matches the thing they did yesterday, but only almost. And this is where Tailwind CSS shows again how brilliant the utility-first idea really is; there is close to zero handwritten css needed for most Tailwind projects which automatically restricts you to a relatively small amount of professionally curated choices. The end result looks automatically not-very-bad and with some tweaking it’s not hard to get absolutely spot-on. (To be fair, it’s not easy either, but unlike trying to manually come up with CSS, it’s way easier!)

After I watched Adam Wathan build this select component, I was convinced that this would be the way I should build the few components (button, toggle-switch, modal, toast, data table / list component, datepicker, tag input) I need for the Slipmat rewrite.

(Yes. NIH. I’d love to use some third-party library here but at the moment there just aren’t too much to choose from for Vue 3 and Tailwind.)

Datatable experiment

The first iterations don’t need to be anything too fancy so I’m confident that building all of these from scratch instead of trying to modify third-party alternatives won’t be an issue. I’m also fully prepared to switch to using @tailwindui/vue or some other library in the future if maintaining these eats too much time. Just to get a feeling of what the API would maybe feel like I created an experiment project and pushed it to GitHub (not GitLab because on GH I get Dependabot updates automatically).

So this story has been a bit of a rambling journey from back in the early days of Web frameworks to Vue 3 and Tailwind CSS. What I’m finding common between all these projects is the meticulous attention to detail regarding almost every aspect of the tool, especially to API design. Great tools aren’t born by accident, they are engineered. And after working with JavaScript for few years now I’m starting to appreciate the metaprogramming powers of Python which makes it possible to write super clean —and somewhat magical— APIs. A good amount of magic really makes a difference in developer experience when it’s done right. I still do think that having a pluralization engine that automatically fetches one Octopus and many Octopi is way too much but I also do appreciate the attention to detail in Rails the more I get to see language restricted not-so-beautiful designs in JavaScript land.

So the lesson of the day: invest in API design and the most value from magic comes from those situations where you can’t see it.

Howto Rename Git Master Branch

While Git uses the term master in the sense of “master record”, it’s clear that master as a term has connotations to master-slave methaphor which is both technically and historically inaccurate according to The Internet Engineering Task Force. Here’s how to rename Git master branch both in your local repository and on GitLab.

1. Rename Git Master Branch

First, rename master and push the change to origin, then update local references to this new name. (I’m using trunk here as the new name but you can use main or whatever you wish. Just change the commands accordingly.)

git checkout master git branch -m master trunk git push -u origin trunk  git branch --unset-upstream git branch -u origin/trunk git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/trunk

2. Change GitLab Default Branch (And Delete master)

Navigate to Settings > Repository and set the new default branch. (In GitHub you’ll find the same setting under repository Settings > Branches.)

Settings

Lastly you may want to delete the old master branch but you need to remove protected branch status from GitLab before being able to do that. Go to Protected Branches on this same Settings > Repository page and Unprotect the master branch if it’s protected. (Don’t forget to add the same protections back to the new branch!) Now we can delete the old master branch:

git push origin --delete master

Bonus: Change Default Git Branch For New Repositories

Since Git version 2.28 you can easily set the default branch name for all new repos with a simple command:

git config --global init.defaultBranch trunk

Congrats for participating in making the word just a little bit better place for all of us!

Weeknotes 35/2020

Many of my developer peers seem to have picked up the practise of publishing weeknotes. I’ve been meaning to do this for a long time, so here goes.

Shaping Up

I discovered Shape Up originally via Adam Wathan who posted absolutely brilliant Twitter thread about becoming a succesful independent maker. It took me a wihe to manage to actually read it, but now that I finally did, it left me with some good ideas about shaping up (pun intended) my own work practises.

Shape Up is a very Basecamp-y look on modern development workflow and work practises. It narrows down on an idea of a 6-week work cycle where the team works on a pre-planned (shaped) project with external phases for planning and also for bug-fixing (what they call cooldown). Reading this felt really good as it is very similar what I’ve been doing with many teams of various sizes for a long time now.

I’ve found out that with most agile teams the idea of a 10-day sprint that inludes design and retro phases are just way too short. It forces the work to be planned and scheduled too much from the top down and leaves the team very little time for independent organization. If the work is instead planned (shaped up) beforehand with a smaller and more experienced team, and there is a separate bugfixing (or cooldown) period after the actual work phase (which is longer than two weeks) the probability of succesful delivery grows drastically.

This is very interesting topic for me and I’ll propably write more about it in the future. With some new inspiration from these ideas I reorganized my near future personal work in a new way. I converted my monthly plan from two sprints into a one cycle with a proper Iteration Plan (idea stolen from VS Code team) that has just one properly shaped and planned goal and clear dates for work phase. My cycle lasts for three weeks after which there is a one-week cooldown for bugfixes and planning for the next cycle. This method lets me keep monthly release cycle and hopefully allows me to actually ship something every single release. I may report back on the success of this model in the future.

New Vue 3 + TypeScript Project Template

For my end goal of shipping a totally new Vue 3 + TypeScript powered frontend for Slipmat users and artists I need a good and tested base for which to build on. To experiment with this I started a new project from scratch to remake the current admin views which have become a bit of a dumpster fire.

I’m using Tailwind UI components as a base which makes getting started really easy and fast. Unfortunately all the components are based on very bright color themes so I’ve had to come up with my own dark color scheme as Slipmat needs to be dark by default. I spent a week with the initial design and refactoring some old API views to get some basic dummy data for developing. The end result looks pretty good as a starting point, I’m sure the final product will work out great. (This is just a proof of concept after all!)

Vue 3 is now in RC phase and using it with TypeScript feels really solid already. The tooling (devtools in particular) is lagging a little bit behind but it’s early days still. I’ve got the project base pretty much nailed, it has fully automated CI/CD pipeline with end to end tests with Cypress and Mirage JS with coverage monitoring that fails the build if coverage drops below 80%.

I’ve also tried to keep everything as lean and as close to native JavaScript as possible. Most of the usual go-to libraries have had a tough screening and for example Moment.js (70k) had to go in favor of Day.js (2k). So far I’ve managed not to load lodash either, although it might come back at some point as practicality beats purity. I might do a write up of these most used third-party libraries as well when I’m starting the final production projects.

Here’s the full list of my current dream stack that powers the new project:

JavaScript Search Engines

Proper search is something that I’ve never got time to build for Slipmat yet but especially for admin tools it’s very important. We do run Elastic on our backend stack but I wanted to investigate if I could whip up something very fast and totally in-browser so I studied few JavaScript search engines.

Turns out there aren’t that many serious contenders. There’s Fuse.js which is great for small datasets (say less than few thousands of objects). I’ve used it in the past for some projects but I wanted something a bit more serious for this. There’s also Lunr.js and Elasticlunr.js both of which are loosely based on Solr. These are serious search engines with lots of options for tweaking the results and proper indexing.

I ended up picking MiniSearch which is a tiny (6k min+zip) yet “proper” and modern search engine that has no external dependencies and can do all kinds of nice things like fuzzy matching, auto suggestions, field boosting and realtime index updating. It can also export and import the built index which makes the initialization very fast. I’m testing the system with a 2Mb json file that has few thousand latest instances of about every model one might want to search (offline) from the admin dashboard. The biggest overhead comes from downloading this first json. Initializing the engine takes about 300ms but when you save the index it shrinks to about 1,5Mb and initializing that only takes about 50ms. As an initial proof of concept the simple pre-warmed and cached json works well enough though.

I’m not yet sure if having a offline-capable frontend-only search is worth it when everything is already indexed in Elasticsearch but this was an interesting one-day experiment in any case. Here’s the search in action:

Search Demo

Okay so this weeks notes were a bit on the long side but hey, it’s been a while. But let’s try to do this again next week! In the meanwhile, find the RSS-feed and @Uninen on Twitter 🙂

Howto Add TypeScript to Your Existing Vue Project

The more I work with scripting languages like JavaScript with modern tools like VS Code, the more I learn to appreciate the powers of static typing. TypeScript is a typed superset of JavaScript that compiles to plain JavaScript, and with good tools it can seriously improve your productivity.

Vue has a somewhat mixed TS story. On the other hand most notable packages support it well but then there are also large painpoints like Vuex that can make your life miserable. Upcoming Vue 3 is completely rewritten in TypeScript which will improve TypeScript support hugely. In attempt to future-proof a rewrite of a large existing Vue app, I decided to start gradually typing it with TypeScript. Here are some of the initial notes from my experience.

(Disclaimer: even though I’m an experienced Vue developer, I’m a complete TS-newbie so YMMV.)

The Unbearable Lightness of Starting Slow

Problem with most TypeScript tutorials and simple examples is that they expect you to either start from scratch or completely convert all of your code to TypeScript from the very first step. For an existing codebase, that’s obviously not going to happen. I would also personally advice against it even if there were tons of tests and all the time in the world to do it, especially if you’re new to TypeScript.

The great secret of TypeScript is that you can start as small as you like and add typings gradually. By doing it this way you’ll probably find some problems with your existing code and get the chance to refactor it properly as you move forward. Granted, you won’t get the full benefits of TypeScript before you reach a certain critical point of typing completeness, but starting it small will cost you almost nothing so its very easy to get started. Life with legacy codebases is all about compromises and this path will at least give you a chance for better future.

Step 1: Initial Installation

If you’re vue project is created with vue-cli, adding typescript looks easy: just vue add typescript. Problem is, the defaults may not be that good for you and you should know what they mean. Here’s what I answered to the installer questions:

Use class-style component syntax? ❌No

By default this plugin suggests you to use class-style components which are an easy way to get started with Vue and TypeScript. Class based api was supposed to be the future of Vue, but the class syntax is in many ways problematic and if you plan to upgrate to Vue 3, you will want to consider composition api instead.

Note that many tutorials and existing TypeScript code for Vue uses class syntax. If you opt out here you have much less refactoring to do with your JavaScript and you are more future-proof with Vue 3, but you will also lose a big chunk of the examples and tutorials out there right now.

Use Babel alongside TypeScript (required for modern mode, auto-detected polyfills, transpiling JSX)? ✓ Yes

If you have an existing project where you use Babel, you’ll definitely want to keep using it with TypeScript as well.

Convert all .js files to .ts? ❌No

This is the most problematic suggestion of them all. Sure, if you’re converting a small app with five files for fun, do it. But if you’re adding TypeScript to a larger project, definitely do not rename all of your JavaScript files in one go, that’s just asking for trouble.

Allow .js files to be compiled? ❌No

As the documentation on the whole plugin is very thin, I don’t exactly know what this option even means but I assume it’s one more toggle to help you bruteforce TypeScript into your project. By default any JavaScript code will stay JavaScript and only .ts files and script tags with lang="ts" will be compiled, and that’s the way you’ll want it to be when starting gradually.

Step 2: Cleaning Up

The “helpful” installer will modify your existing code so you’ll need to do a bit of cleanup before getting back to business. First, you’ll want to delete the re-appeared src/components/HelloWorld.vue as I’m quite sure no one is actually using that in a real project (right??). You also want to fix the havoc in your src/App.vue while you’re at it. The main.js is now renamed to main.ts. This is a good change as it reminds you immediately that this project uses TypeScript even though most of the files might still be JavaScript.

The newly added tsconfig.json includes somewhat strict settings that may or may not work with your project. The stricter the rules, the more benefits you get from TypeScript, but on the other hand the stricter the rules, the harder it is to make your existing code valid. For me one of the first steps with an existing project was to disable strict checking. This allowed me to gradually add typings to complex files without spending hours and hours in debugging or adding the file full of ignores. Note that by loosening the checking you will lose some of the most powerful gains you could have from your editor and TS in general so evaluate yourself if you can leave it on or not.

(For example, with strict checking on, when editing a method inside a Vue component, the editor will know that this refers to a specific Vue instance. This is super powerful when it works. When strict checking is disabled, this inside of a component method is inferred as any type which will not help you at all.)

I would not tweak tsconfig too much more before you understand better the challenges in your specific project. Give yourself time to test and experiment before committing to any specific rule.

Step 3: Start Adding Typings

Now you are ready to start adding your first types! I’d suggest to start in a file that is large or otherwise not so easy to read at a first glance — this is where you’ll get most gains.

This is not a tutorial on TypeScript itself, you’ll find plenty of them elsewhere. The migrating from JavaScript document is a good read and Using TypeScript with Vue Single File Components was very helpful to me as well. Vue + TypeScript Cookbook is a brilliant source of practical advice and it also points out some of the long standing issues such as the problems with Vuex.

Oh yes, Vuex. Have a plan for Vuex. Almost all larger projects use Vuex and for example the mapState helper, so you’ll immediately be in a world of trouble as Vuex does not have proper TypeScript support and no simple solution has been found by the community. This does not mean that you can’t use Vuex with TypeScript or that there are no solutions. It just means that there are no good universal solutions. You need to experiment and evaluate which of the dozens of proposed workarounds works best for you. And know that if it at some point stops working in your specific edge case, you’re alone with your problem as there is no officially supported way. This obviously sucks big time, but there is at least some light at the end of this tunnel as Vue 3 will eventually bring proper TypeScript support to Vuex as well.

Try not to ignore code. Alarm bells should ring if your TypeScript code starts gathering // @ts-ignore-lines more than actual refactoring. It’s the same with linting: the point is to make your code better, not to work around your tooling. Sure, there are situations where practicality beats purity but make a mental note for yourself to keep those situations exceptions. If you find a file too hard to convert, just leave it be until you or your tools become smarter.

There are a couple of good rules of thumb you should keep in mind. First, all new code should be typed. This is kind of obvious but also easy to forget. Add documentation and processes in place to make sure that from now on, all new code in the project is written in TypeScript instead of JavaScript. You can help this process with CI scripts and other tools: ban adding .js files and if you have tools that generate new files, convert them to generate .ts.

Secondly, try not to change too much in one go. It’s very easy to stumble down into the rabbit hole and use hours and hours adding typings with very little practical gains. As you learn more and as Vue world matures, you’ll be getting more and more out of TypeScript. And then some day when you understand more about your project and the tools, you’ll see more clearly when it is the right time to take the last step of converting all the remaining code to TypeScript. Remember, cleaning up your codebase is not a race, it’s a neverending journey.

Things Will Break — It’s a Good Thing

The thing with TypeScript that makes it both helpful and painful at the same time is the fact that it’s much more unforgiving to mistakes that you’ve used to with JavaScript. My very first steps with TS in a real world project involved several hours of debugging a file that would not compile no matter what I did. Turns out it was due to a missing import in a legacy method that was never called. You’ll never find out things like this in JavaScript but they will bite you with TypeScript as soon as you turn it on, so be mentally prepared.

Legacy code is difficult in many ways and hunting down new bugs that previously weren’t there can feel frustrating. But remember that this is exactly why you want to use TypeScript in the first place: to see and fix those bugs early. It’s very likely that your old production code is relying on a bug you didn’t even know was there and turning on TypeScript will now break that code. Learn to embrace these growing pains because fixing them will make your code better and keep your productivity high in the long run.

Hello Comments!

For this weeks weekend project I decided to dive a bit deeper into Google Firebase and built a commenting system for this Gridsome-based blog from scratch. It was definitely not worth the time in the sense of adding commenting possibility to a blog but as a learning journey I’d say this was a fun little project.

Gridsome is a JAMstack tool which means that features like commenting need to be implemented either as a third-party solution or by using a separate backend functionality be it serverless functions, a traditional REST backend or something similar. Firebase is an interesting app development platform startup that was aquired by Google in 2014. What makes Firebase intresting for this kind of applications is its realtime database and hosted pluggable authentication system. Google offers a fairly generous free tier for the services so testing it out for a personal project like this is costs you only your time.

I’ll write more in depth about technical details later but for now, I’m happy to get this thing published. The biggest lesson learned here was that as with any tehcnologies, even though the 2 minute demo seems really clean and easy, most real worl implementations need to focus on details that are hard to get right if you care about user experience and security.

(Obviously, this first implementation is very unpolished and not feature-complete, but it should work, that’s the most important thing for now.)

Better GraphQL Explorer for Gridsome

Gridsome data layer is built on GraphQL and the development server comes bundled with a graphical UI for studying the schema building queries. This UI, however, is not very useful if you don’t already know GraphQL. I recently found out that there is a much better tool called graphiql-explorer that allows you to build GraphQL queries graphically and that it can be very easily used with Gridsome as a VS Code plugin.

GraphiQL Explorer inside VS Code

(Note: if you happen to use some other editor, you should be able to install graphiql-explorer by adding it in the dev server config with configureServer-hook.)

The 1-minute install

  1. Install the vscode-graphiql-explorer-extension.
  2. In your repository root, while your development server is running, generate a GraphQL schema for the plugin with following command: npx get-graphql-schema http://localhost:8080/___graphql > schema.graphql (the first part of the URL should be your development server URL). You might want to add schema.graphql to gitignore as well.
  3. Profit!11

You can now use the GraphiQL explorer inside your VS Code. Run Explore schema with GraphiQL command to see it in action.

Notes

  • The two other commands added by this extension don’t currently work with the custom Gridsome GraphQL blocks inside -vue files. What you can do is either copy the code in an open explorer window or open it in a new file and then run the explore-command. I opened a ticket for fixing this, it seems that it might be fixed quite soon.
  • graphiql-explorer is bundled with Gatsby and according to Gridsome developers, they might switch to using it in Gridsome as well. There’s actually an old ticket about this, too.
  • Shout-out to @eunjae_lee for leading me into this rabbit hole 🙂