Skip to main content

Groqd Playground (Plugin)

Groqd Playground is a plugin for Sanity Studio for testing groqd queries, featuring:

  • a TypeScript editor experience with syntax/type highlighting;
  • parsed response and error messages for when responses fail to pass Zod validation;
  • dataset/api version switchers.

Sample of groqd playground in use

Installation

In your Sanity Studio project, install groqd-playground using your favorite package registry tool.

npm install groqd-playground

The playground tool has the following peer dependencies which are typically already a part of most Sanity Studio implementations:

sanity @sanity/ui @sanity/icons styled-components
caution

This plugin is Studio V3-compatible, and likely will not work in a Studio V2 setup.

Usage with Next.js

Currently, groqd-playground has a dependency on @uiw/react-split which imports its own CSS. This can cause some hiccups in Next.js-embedded studios.

The new /app directory supports global CSS imports, so no extra configuration is needed.

Configuration

Once installed, just add the groqd playground tool to your list of Sanity plugins:

import { defineConfig } from "sanity";
import { groqdPlaygroundTool } from "groqd-playground";

export default defineConfig({
/* ... */
plugins: [groqdPlaygroundTool()],
});

The groqdPlaygroundTool method takes a configuration option as its sole, optional argument with the following options.

keydescriptiondefault
nameName of the plugin"groqd-playground"
titleTitle to show in navbar of Studio"GROQD"
iconIcon to show in navbar of StudioCodeIcon
defaultDatasetDefault dataset to use in playground"production"
defaultApiVersionDefault API version to use in playground"v2021-10-21"

How to use

Groqd Playground behaves very similar to Sanity's Vision Tool, but by writing a groqd query instead of a standard GROQ query.

The standard workflow is:

  1. Pass a groqd query to the playground's runQuery function. For example:
import { runQuery } from "playground";
import { q } from "groqd";

runQuery(
q("*")
.filterByType("pokemon")
.slice(0, 10)
.grab$({
name: q.string()
})
);
  1. Press the Fetch button to run the generated query against your Studio's dataset.
  2. If the response comes back and is parsed successfully, you can inspect the parsed response.
  3. If the response fails validation, the playground will show the validation error(s) and the raw groq response for you to inspect.

Passing parameters to the query

To pass parameter values to your query, pass an object as the second argument to runQuery:

import { runQuery } from "playground";
import { q } from "groqd";

runQuery(
q("*")
.filterByType("pokemon")
.filter("name == $name")
.slice(0, 10)
.grab$({
name: q.string()
}),
// 👇 Pass your parameters here
{
name: "Bulbasaur"
}
);

Editor Keyboard shortcuts

When the editor is focused, the following keyboard shortcuts are available:

  • Cmd + Enter to trigger a fetch call.
  • Cmd + S to copy the share URL to your clipboard.