@liiift-studio/sanity-type-foundry-utilities

Nine safety-locked content utilities for Sanity Studio — bulk-edit, export, clean assets, and trace delivered fonts back to their order from an embedded fingerprint. Drops a single Utilities desk into any type-foundry studio, so you stop re-implementing migration, forensics, and bulk-edit tools in every project.

Overview

The whole suite mounts as one Sanity tool via UtilitiesDesk(): a searchable sidebar (with favorites and recent-ops history) that hosts every utility, grouped by category. Destructive operations are guarded by danger-mode locks and confirmation dialogs for safety.

Architecture

UtilitiesDesk() registers a single tool that hosts all nine utilities. They share the Studio's useClient() content client; the Fingerprint Reader additionally calls your lookupOrder function to resolve a fingerprint to its originating order, and Get Font Data uses fontkit for OpenType metadata.

The diagram below renders natively on GitHub. On the npm registry page (which does not render Mermaid), the SVG underneath it is shown instead.

flowchart TB
    config["sanity.config.ts<br/>tools: [ UtilitiesDesk(config) ]"] --> desk

    subgraph desk["UtilitiesDesk() — single Utilities tool"]
        direction TB
        nav["Searchable sidebar<br/>+ favorites + recent ops<br/>+ global Danger Mode lock"]

        subgraph dm["Data Management"]
            export["Export Data"]
            sadd["Search &amp; Add Data"]
            sdel["Search &amp; Delete"]
            dup["Duplicate &amp; Rename"]
        end
        subgraph at["Asset Tools"]
            assets["Delete Unused Assets"]
        end
        subgraph dev["Development Tools"]
            fp["Fingerprint Reader"]
            fd["Get Font Data"]
            weak["Convert to Weak References"]
            slug["Convert IDs to Slug"]
        end

        nav --- dm
        nav --- at
        nav --- dev
    end

    client["useClient()<br/>Sanity content client"] --> desk
    fp -. "config.fingerprintReader.lookupOrder(fingerprint, client)" .-> order["Originating order<br/>(rendered via renderOrder)"]
    fd -. fontkit .-> meta["OpenType metadata"]

Installation

npm install @liiift-studio/sanity-type-foundry-utilities

Local Development

When developing the utilities package locally, you can use npm link to avoid publishing after every change. This creates a symlink so your Sanity project points directly to your local development folder.

Setup Once

# 1. In the sanity-type-foundry-utilities directory
cd /path/to/sanity-type-foundry-utilities
npm link

# 2. In your Sanity project directory
cd /path/to/your-project/sanity
npm link @liiift-studio/sanity-type-foundry-utilities

Now any changes you make to the utilities package will be instantly available in your Sanity studio (Vite will hot-reload automatically).

When Done Developing

# Unlink and return to the published version
cd /path/to/your-project/sanity
npm unlink @liiift-studio/sanity-type-foundry-utilities
npm install @liiift-studio/sanity-type-foundry-utilities@latest

Development Workflow

1. Make changes to utility components in components/
2. Save the file — Vite hot-reloads instantly
3. Test in your linked Sanity studio
4. When ready to release:
   • Bump version: npm version patch (or minor/major)
   • Publish: npm publish
   • Update consuming projects: npm install @liiift-studio/sanity-type-foundry-utilities@latest

Usage

Basic Usage

Import and use the utilities desk in your Sanity config:

import { UtilitiesDesk } from '@liiift-studio/sanity-type-foundry-utilities';

// In your sanity.config.js
export default defineConfig({
	// ... other config
	tools: [UtilitiesDesk()]
});

Configuring the Fingerprint Reader

The Fingerprint Reader reads the embedded DS-… fingerprint from any delivered font (TTF, OTF, WOFF, WOFF2) or CSS file. To turn that fingerprint into its originating order, pass a fingerprintReader config to UtilitiesDesk(). Without it, the reader still extracts the fingerprint — it just won't look anything up.

import { UtilitiesDesk } from '@liiift-studio/sanity-type-foundry-utilities';

export default defineConfig({
	// ... other config
	tools: [
		UtilitiesDesk({
			fingerprintReader: {
				// Resolve a fingerprint to its order. `client` is the Studio's Sanity client.
				// Return the order (any shape) or null if no match.
				lookupOrder: async (fingerprint, client) => {
					return client.fetch(
						`*[_type == "order" && fingerprint == $fp][0]`,
						{ fp: fingerprint }
					);
				},
				// Optional: custom renderer for the matched order.
				// Defaults to an object inspector when omitted.
				renderOrder: (order) => `Order ${order.orderNumber} — ${order.customerEmail}`
			}
		})
	]
});

| Config key | Type | Description | |---|---|---| | fingerprintReader.lookupOrder | async (fingerprint, client) => order \| null | Resolves an extracted fingerprint to its originating order. Optional — omit to disable order lookup. | | fingerprintReader.renderOrder | (order) => ReactNode | Optional renderer for the matched order. Defaults to an object inspector. |

Available Components

All utility components are exported individually if you need custom implementations:

import {
	ConvertIdsToSlug,
	ConvertToWeakReferences,
	DangerModeWarning,
	DeleteUnusedAssets,
	DuplicateAndRename,
	ExportData,
	FingerprintReader,
	GetFontData,
	SearchAddData,
	SearchAndDelete,
	UtilitiesDesk
} from '@liiift-studio/sanity-type-foundry-utilities';

Utilities Included

At a glance — every utility lives under the single Utilities desk, grouped by category:

| Category | Utility | What it does | |---|---|---| | Data Management | Export Data | Export documents to CSV or JSON, with optional reference population. | | Data Management | Search & Add Data | Bulk add/replace field data (Full Replace · Find & Replace · Prepend · Append · Transform). | | Data Management | Search & Delete | Find and permanently delete documents matching criteria, with confirmation dialogs. | | Data Management | Duplicate & Rename | Copy field values to new field names across documents of a type. | | Asset Tools | Delete Unused Assets | Scan for unreferenced images/files and bulk-delete with preview thumbnails. | | Development Tools | Fingerprint Reader | Read the embedded fingerprint from a delivered font/CSS and look up its originating order. | | Development Tools | Get Font Data | Analyze uploaded fonts with fontkit — metadata and OpenType properties. | | Development Tools | Convert to Weak References | Transform strong document references into weak references. | | Development Tools | Convert IDs to Slug | Migrate auto-generated document IDs to slug-based IDs, updating all references. |

The detailed descriptions below match the order shown in the desk:

1. Convert IDs to Slug

Converts font document IDs from auto-generated to slug-based IDs, updating all references across your content.

2. Convert to Weak References

Transforms strong document references into weak references across matching documents.

3. Delete Unused Assets

Scans for unreferenced image and file assets and allows bulk deletion with preview thumbnails.

4. Duplicate and Rename

Copies field values to new field names across all documents of a specific type.

5. Export Data

Exports documents to CSV or JSON formats with optional reference population.

6. Fingerprint Reader

Reads embedded fingerprint data from font files (WOFF2, TTF, OTF) and looks up the originating Sanity order. See Configuring the Fingerprint Reader to wire up the order lookup.

7. Get Font Data

Analyzes uploaded font files using fontkit, displaying metadata and OpenType properties.

8. Search & Add Data

Bulk add or replace field data with multiple modes:

• Full Replace
• Find & Replace
• Prepend
• Append
• Transform (toLowerCase, toUpperCase, trim)

9. Search & Delete

Searches for and deletes documents matching specific criteria with confirmation dialogs.

Safety Features

• Danger Mode Locks: Destructive operations require unlocking danger mode
• Warning Modals: 48-hour suppression option for danger mode warnings
• Confirmation Dialogs: Double confirmation for bulk delete operations
• Preview Features: See what will be affected before taking action

Requirements

• Sanity Studio v3, v4, or v5
• React 18 or 19
• @sanity/ui v1, v2, or v3
• @sanity/icons v2 or v3
• fontkit v2+ (optional — only required if using GetFontData or UtilitiesDesk)

Links

• npm: https://www.npmjs.com/package/@liiift-studio/sanity-type-foundry-utilities
• Repository: https://github.com/Liiift-Studio/sanity-type-foundry-utilities
• Publishing & integration guide: SETUP.md

License

MIT © Liiift Studio. Maintained for internal Liiift Studio foundry projects.

Support

For issues or questions, please contact the Liiift Studio development team.