Sanity Delete Unused Assets

A comprehensive asset cleanup utility for Sanity Studio that identifies and removes unused assets to optimize storage and improve performance. Features advanced scanning, filtering, and safety mechanisms.

Features

• 🔍 Smart Asset Scanning: Automatically detects unused images, videos, and files
• 📊 Storage Analysis: Shows file sizes, storage savings, and detailed metrics
• 🎯 Advanced Filtering: Filter by file type, size, age, and custom patterns
• 🛡️ Safety First: Dry-run mode, confirmation dialogs, and exclude patterns
• 📈 Progress Tracking: Real-time scanning progress with detailed feedback
• 🔄 Batch Processing: Handles large asset collections efficiently
• 📱 Responsive UI: Seamless integration with Sanity Studio

Installation

npm install sanity-delete-unused-assets

Quick Start

Basic Usage

import React from 'react'
import { DeleteUnusedAssets } from 'sanity-delete-unused-assets'
import { useClient } from 'sanity'

const AssetCleanup = () => {
  const client = useClient({ apiVersion: '2023-01-01' })

  return (
    <DeleteUnusedAssets
      client={client}
      onComplete={(results) => {
        console.log(`Cleaned up ${results.deleted} assets, saved ${results.spaceSaved} MB`)
      }}
    />
  )
}

As a Sanity Studio Tool

// sanity.config.ts
import { defineConfig } from 'sanity'
import { DeleteUnusedAssetsTool } from 'sanity-delete-unused-assets'

export default defineConfig({
  // ... other config
  tools: [
    DeleteUnusedAssetsTool()
  ]
})

With Custom Filters

<DeleteUnusedAssets
  client={client}
  fileTypes={['image/jpeg', 'image/png']}
  minFileSize={1024} // 1KB minimum
  maxFileSize={10485760} // 10MB maximum
  olderThanDays={30}
  excludePatterns={['hero-*', 'logo-*']}
/>

Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | client | SanityClient | required | Sanity client instance | | fileTypes | string[] | [] | Specific MIME types to scan (empty = all types) | | minFileSize | number | 0 | Minimum file size in bytes | | maxFileSize | number | Infinity | Maximum file size in bytes | | olderThanDays | number | 0 | Only scan assets older than X days | | excludePatterns | string[] | [] | Filename patterns to exclude from deletion | | onComplete | function | undefined | Callback when cleanup completes | | onError | function | undefined | Error handling callback | | batchSize | number | 10 | Number of assets to process per batch | | dryRun | boolean | false | Preview mode without actual deletion |

Usage Examples

1. Basic Asset Cleanup

import { DeleteUnusedAssets } from 'sanity-delete-unused-assets'

const BasicCleanup = () => {
  const client = useClient({ apiVersion: '2023-01-01' })

  return (
    <DeleteUnusedAssets
      client={client}
      onComplete={(results) => {
        console.log(`Cleanup complete:`, {
          deleted: results.deleted,
          spaceSaved: `${results.spaceSaved} MB`,
          errors: results.errors.length
        })
      }}
    />
  )
}

2. Image-Only Cleanup with Size Limits

<DeleteUnusedAssets
  client={client}
  fileTypes={['image/jpeg', 'image/png', 'image/webp']}
  minFileSize={1024} // Skip tiny files
  maxFileSize={5242880} // Skip files larger than 5MB
  onComplete={(results) => {
    console.log(`Cleaned ${results.deleted} images`)
  }}
/>

3. Safe Mode with Exclusions

<DeleteUnusedAssets
  client={client}
  dryRun={true}
  excludePatterns={[
    'hero-*',
    'logo-*', 
    'favicon*',
    '*-backup'
  ]}
  onComplete={(results) => {
    console.log(`Would delete ${results.deleted} assets (${results.spaceSaved} MB)`)
  }}
/>

4. Old Asset Cleanup

<DeleteUnusedAssets
  client={client}
  olderThanDays={90} // Only assets older than 3 months
  onComplete={(results) => {
    console.log(`Cleaned up old assets: ${results.deleted} files`)
  }}
/>

Asset Detection

How It Works

The utility performs a comprehensive scan to identify unused assets:

1. Asset Inventory: Scans all assets in your Sanity dataset
2. Reference Analysis: Checks all documents for asset references
3. Usage Detection: Identifies assets not referenced by any document
4. Filter Application: Applies your specified filters (type, size, age, etc.)
5. Safe Deletion: Removes only confirmed unused assets

Supported Asset Types

• Images: JPEG, PNG, WebP, GIF, SVG
• Videos: MP4, WebM, MOV
• Documents: PDF, DOC, DOCX
• Audio: MP3, WAV, OGG
• Archives: ZIP, RAR
• Custom: Any MIME type

Safety Features

Dry Run Mode

<DeleteUnusedAssets client={client} dryRun={true} />

• Preview what would be deleted without making changes
• Test filters and exclusion patterns safely
• Validate storage savings estimates

Exclude Patterns

excludePatterns={[
  'hero-*',      // Exclude hero images
  'logo-*',      // Exclude logos
  '*-backup',    // Exclude backup files
  'temp/*'       // Exclude temp folder
]}

Confirmation Dialogs

• All delete operations require explicit confirmation
• Clear warnings for destructive actions
• Detailed summary before deletion

Batch Processing

• Large cleanup operations are processed in batches
• Prevents timeout issues with large asset collections
• Progress feedback during long operations

Storage Analysis

The component provides detailed storage metrics:

• Total Assets: Count of all assets in dataset
• Unused Assets: Count of assets not referenced
• Storage Used: Total storage consumed by unused assets
• Potential Savings: Storage that would be freed
• File Size Distribution: Breakdown by file size ranges
• File Type Analysis: Usage by MIME type

Performance Tips

Large Datasets

• Use batchSize to control processing speed
• Apply filters to reduce scan scope
• Run during off-peak hours for large cleanups

Incremental Cleanup

// Clean up assets older than 30 days
<DeleteUnusedAssets
  client={client}
  olderThanDays={30}
  batchSize={5}
/>

Memory Optimization

// Process smaller batches for memory efficiency
<DeleteUnusedAssets
  client={client}
  batchSize={3}
  maxFileSize={10485760} // 10MB limit
/>

Requirements

• Sanity Studio v3+
• React 18+
• @sanity/ui v1+
• TypeScript 4.5+ (optional)

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to help improve this utility.