or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-groq

Tagged template literal for Sanity.io GROQ queries with editor integration support

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/groq@4.10.x

To install, run

npx @tessl/cli install tessl/npm-groq@4.10.0

index.mddocs/

GROQ

GROQ is a lightweight tagged template literal utility for Sanity.io GROQ queries. It provides editor integration support including syntax highlighting and development tooling, while acting as a pass-through function that returns input strings unchanged. The package is designed primarily for developer experience improvements when working with Sanity's Graph Oriented Query Language.

Package Information

  • Package Name: groq
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install groq

Core Imports

ESM imports:

// Default export
import groq from "groq";

// Named export
import { defineQuery } from "groq";

// Package metadata (for version checking)
import pkg from "groq/package.json" assert { type: "json" };

CommonJS imports:

// Default export
const groq = require("groq");

// Named export
const { defineQuery } = groq;

Basic Usage

Using the groq template tag:

import groq from "groq";

// Basic GROQ query with template tag
const query = groq`*[_type == 'products'][0...10]`;

// Query with template interpolation
const contentType = 'articles';
const limit = 5;
const query = groq`*[_type == '${contentType}'][0...${limit}]`;

Using defineQuery for better TypeScript integration:

import { defineQuery } from "groq";

// Query with type inference support
const query = defineQuery(`*[_type == 'products'][0...10]`);

// With string interpolation
const contentType = 'articles';
const query = defineQuery(`*[_type == '${contentType}'][0...10]`);

Capabilities

GROQ Template Tag

Primary template tag function for GROQ queries that enables editor tooling integration.

/**
 * Pass-through groq template tag. This is a no-op, but it helps editor integrations
 * understand that a string represents a GROQ query in order to provide syntax highlighting
 * and other features.
 * @param strings - Template string parts
 * @param keys - Template string keys
 * @returns The same string as the input
 */
function groq(strings: TemplateStringsArray, ...keys: any[]): string;

Usage Example:

import groq from "groq";

// Simple query
const basicQuery = groq`*[_type == 'post']`;

// Query with variables
const category = 'technology';
const limit = 10;
const complexQuery = groq`*[_type == 'post' && category == '${category}'][0...${limit}]{
  title,
  slug,
  publishedAt
}`;

Define Query Function

Alternative function for defining GROQ queries with enhanced TypeScript type inference capabilities.

/**
 * Define a GROQ query. This is a no-op, but it helps editor integrations
 * understand that a string represents a GROQ query in order to provide syntax highlighting
 * and other features.
 *
 * Ideally the `groq` template tag would be used, but we cannot infer types from it until
 * microsoft/TypeScript#33304 is resolved. Otherwise, there is no difference between this
 * and the `groq` template tag.
 * @param query - The GROQ query string
 * @returns The same string as the input
 */
function defineQuery<const Q extends string>(query: Q): Q;

Usage Example:

import { defineQuery } from "groq";

// Query with preserved literal type
const typedQuery = defineQuery(`*[_type == 'product']{name, price}`);

// The return type preserves the exact string literal for better tooling
const dynamicQuery = defineQuery(`*[_type == '${contentType}']`);

Architecture

The GROQ package follows a simple pass-through architecture:

  • Runtime Behavior: Both functions return their input unchanged - they perform no parsing, validation, or transformation
  • Development Benefits: Enable editor integrations to recognize GROQ query strings for syntax highlighting and tooling support
  • Type Safety: defineQuery provides better TypeScript integration by preserving string literal types
  • Future-Proof: The pass-through design allows for future enhancements (parsing, validation, optimization) without breaking changes

Integration Notes

  • Editor Support: Works seamlessly with vscode-sanity extension for syntax highlighting
  • Zero Dependencies: No runtime dependencies, minimal package footprint
  • Build Tool Friendly: Compatible with all major bundlers and build systems
  • Sanity Integration: Designed specifically for use with Sanity.io CMS and GROQ query language

Additional Exports

Package Metadata

Access to package.json for version information and metadata.

// Available as a subpath export
import pkg from "groq/package.json" assert { type: "json" };

Usage Example:

import pkg from "groq/package.json" assert { type: "json" };

console.log(`Using GROQ version: ${pkg.version}`);

Choice Between Functions

  • Use groq template tag for most cases - provides natural template literal syntax with interpolation
  • Use defineQuery when working with @sanity/codegen or when you need preserved string literal types for enhanced TypeScript tooling
  • Both functions are functionally equivalent at runtime - the choice is based on development experience preferences