CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-groq

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

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

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
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/groq@4.10.x
Publish Source
CLI
Badge
tessl/npm-groq badge