0
# GROQ
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: groq
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install groq`
10

11
## Core Imports
12

13
ESM imports:
14

15
```typescript
16
// Default export
17
import groq from "groq";
18

19
// Named export
20
import { defineQuery } from "groq";
21

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

26
CommonJS imports:
27

28
```javascript
29
// Default export
30
const groq = require("groq");
31

32
// Named export
33
const { defineQuery } = groq;
34
```
35

36
## Basic Usage
37

38
Using the `groq` template tag:
39

40
```typescript
41
import groq from "groq";
42

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

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

52
Using `defineQuery` for better TypeScript integration:
53

54
```typescript
55
import { defineQuery } from "groq";
56

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

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

65
## Capabilities
66

67
### GROQ Template Tag
68

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

71
```typescript { .api }
72
/**
73
 * Pass-through groq template tag. This is a no-op, but it helps editor integrations
74
 * understand that a string represents a GROQ query in order to provide syntax highlighting
75
 * and other features.
76
 * @param strings - Template string parts
77
 * @param keys - Template string keys
78
 * @returns The same string as the input
79
 */
80
function groq(strings: TemplateStringsArray, ...keys: any[]): string;
81
```
82

83
**Usage Example:**
84

85
```typescript
86
import groq from "groq";
87

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

91
// Query with variables
92
const category = 'technology';
93
const limit = 10;
94
const complexQuery = groq`*[_type == 'post' && category == '${category}'][0...${limit}]{
95
  title,
96
  slug,
97
  publishedAt
98
}`;
99
```
100

101
### Define Query Function
102

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

105
```typescript { .api }
106
/**
107
 * Define a GROQ query. This is a no-op, but it helps editor integrations
108
 * understand that a string represents a GROQ query in order to provide syntax highlighting
109
 * and other features.
110
 *
111
 * Ideally the `groq` template tag would be used, but we cannot infer types from it until
112
 * microsoft/TypeScript#33304 is resolved. Otherwise, there is no difference between this
113
 * and the `groq` template tag.
114
 * @param query - The GROQ query string
115
 * @returns The same string as the input
116
 */
117
function defineQuery<const Q extends string>(query: Q): Q;
118
```
119

120
**Usage Example:**
121

122
```typescript
123
import { defineQuery } from "groq";
124

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

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

132
## Architecture
133

134
The GROQ package follows a simple pass-through architecture:
135

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

141
## Integration Notes
142

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

148
## Additional Exports
149

150
### Package Metadata
151

152
Access to package.json for version information and metadata.
153

154
```typescript { .api }
155
// Available as a subpath export
156
import pkg from "groq/package.json" assert { type: "json" };
157
```
158

159
**Usage Example:**
160

161
```typescript
162
import pkg from "groq/package.json" assert { type: "json" };
163

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

167
## Choice Between Functions
168

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