@ulu/vite-virtual-modules-sanity-loader

A Vite plugin that wraps @ulu/sanity-loader to expose Sanity.io content as virtual modules in Vite applications, designed for use with @ulu/vite-plugin-virtual-modules.

This plugin allows you to fetch content from Sanity.io at build time and expose it to your application as virtual modules, which can be imported like any other ES module. It handles data fetching, caching, and asset management under the hood.

Core Concepts

This library is a bridge between the core @ulu/sanity-loader and your Vite project, leveraging the file-based approach of @ulu/vite-plugin-virtual-modules.

The workflow is as follows:

1. You create a central src/sanity/index.js file to configure and export a virtualModulesLoader instance.
2. In your src, you create a "loader" file (e.g., src/data/siteSettings.js). This file imports the virtualModulesLoader and uses its defineLoader method to generate its default export.
3. In your application, you import the loader file with the ?virtual-module suffix.
4. At build time, @ulu/vite-plugin-virtual-modules executes your loader, which uses @ulu/sanity-loader to fetch data and generate the final module content.

Installation

This package has peerDependencies on vite and @sanity/client, which you should have installed in your project.

npm install @ulu/vite-virtual-modules-sanity-loader @ulu/sanity-loader @ulu/vite-plugin-virtual-modules @sanity/client

Quick Start

Here’s how to set up the loader using the file-based approach.

1. Project Setup

Let's assume you have a project structure like this:

.
├── src/
│   ├── sanity/
│   │   ├── index.js            // Central API setup lives here
│   │   ├── queries/
│   │   │   └── siteSettings.groq
│   │   └── cache/
│   ├── data/
│   │   └── siteSettings.js   // This will be our virtual module loader
│   └── main.js
└── vite.config.js

2. Vite Configuration

Your vite.config.js is simple. It only needs to register the virtual modules plugin.

// vite.config.js
import { defineConfig } from 'vite';
import virtualModules from '@ulu/vite-plugin-virtual-modules';

export default defineConfig({
  plugins: [
    virtualModules()
  ]
});

3. Sanity API Setup

Create a central file to configure your connection to Sanity. This code runs in Node.js during the build.

// src/sanity/index.js
import { createSanityLoader } from '@ulu/sanity-loader';
import { createVirtualModulesLoader } from '@ulu/vite-virtual-modules-sanity-loader';
import { createClient } from '@sanity/client';

// 1. Create a Sanity client
const sanityClient = createClient({
  projectId: 'your-project-id',
  dataset: 'your-dataset',
  useCdn: false, // `false` if you want to ensure fresh data
  apiVersion: '2023-05-03',
});

// 2. Create the core Sanity loader instance
const sanityLoader = createSanityLoader({
  client: sanityClient,
  paths: {
    queries: './src/sanity/queries',
    cache: './src/sanity/cache',
    assets: './public/assets/sanity',
    assetsPublic: '/assets/sanity'
  },
  verbose: true // Enable logging for debugging
});

// 3. Create and export the virtual modules loader instance
export const virtualModulesLoader = createVirtualModulesLoader(sanityLoader);

4. Create the Virtual Module Loader

This file imports the virtualModulesLoader and uses it to create a loader for a specific piece of data.

// src/data/siteSettings.js
import { virtualModulesLoader } from '../sanity/index.js';

// defineLoader returns a function that becomes this module's default export.
// This is what @ulu/vite-plugin-virtual-modules will execute.
export default virtualModulesLoader.defineLoader({
  queryName: 'siteSettings', // From queries/siteSettings.groq
  cacheEnabled: true
});

5. Use in Your Application

Now, import the loader file in your application with the ?virtual-module suffix.

// src/main.js
import siteSettings from './data/siteSettings.js?virtual-module';

console.log(siteSettings.siteTitle);

API Reference

createVirtualModulesLoader(sanityLoader, globalOptions)

This function is the main entry point. It accepts two arguments:

1. sanityLoader: A pre-configured instance returned from createSanityLoader in the core @ulu/sanity-loader library.
2. globalOptions (optional): An object with global settings for all loaders created by this instance. It can contain watch, watchOptions, and watchEvents.

virtualModulesLoader.defineLoader(options)

This is a factory function that generates the entire default export needed by a loader file for @ulu/vite-plugin-virtual-modules. It accepts the same options as defineLoader from the core library, but also includes Vite-specific options:

• Core Options: See the @ulu/sanity-loader documentation for all available loader options (queryName, transform, etc.).
• Vite Options:
  • watch (string[] | null): Override global watch patterns for this specific loader.
  • watchOptions (object): Override global watcher options for this loader.
  • watchEvents (string[]): Override global watch events for this loader.

The defineLoader function automatically wraps the result in a JSON module for you.

All other utilities (imageUrl, utils, client) are available on the virtualModulesLoader object and are passed through from the core loader.

License

MIT