quicklook-kit

quicklook-kit

Build Quick Look previews for macOS and Windows with Vite-based web frameworks, no Swift or C# required

Your preview is a web page. quicklook-kit builds it with your framework and wraps it in a small native host: a Quick Look extension on macOS, a QuickLook plugin on Windows. You never touch Swift, C# or Xcode.

Built-in support for SvelteKit, Astro, SolidStart, Nuxt and Analog. Any other framework that builds with Vite and writes a static index.html works through an integration.

Requirements

• Node.js 22.17 or later, which runs the quicklook CLI
• For macOS: macOS 14 or later, with Xcode and XcodeGen installed
• For Windows: the .NET SDK, on any OS. Testing the plugin needs Windows with QuickLook and the Microsoft Edge WebView2 Runtime, which ships with Windows 11

Installation

npm install --save-dev quicklook-kit

To start from scratch, run pnpm create quicklook instead.

Setup

1. Configure

Create quicklook.config.ts in your project root:

import { defineConfig } from 'quicklook-kit';

export default defineConfig({
	name: 'Quick Look Example',
	macos: {
		bundleId: 'com.example.QuickLookExample',
		types: [
			{
				id: 'com.example.QuickLookExample.example',
				description: 'Example File',
				extensions: ['example'],
				conformsTo: ['public.plain-text'],
			},
		],
	},
	windows: {
		id: 'QuickLook.Plugin.Example',
		extensions: ['example'],
	},
	framework: 'sveltekit',
});

Each platform group is optional, but you need at least one: leave out windows to build for macOS only, or macos for Windows only.

A new type conforms to public.plain-text for text formats, or public.data for binary ones. To preview a type macOS already knows about, use a plain string like 'public.json' in place of an object.

The config can also be quicklook.config.js, .json, .yaml or .toml, or a .quicklookrc. The keys are the same in every format.

Under macos:

Under windows:

Upgrading from a version without platform groups? The old top-level bundleId, icon, macOS and types now live under macos, with macOS renamed to minimumVersion.

A framework can take options as a [name, options] pair, e.g. ['sveltekit', { outDir: 'dist' }] when your adapter writes somewhere other than the default.

Each framework needs a static, client-side build:

2. Add the Vite plugin

import { quicklook } from 'quicklook-kit/vite';

// in the framework's Vite config
plugins: [quicklook()];

For TypeScript, add the types of the virtual module, either in a .d.ts file:

/// <reference types="quicklook-kit/virtual" />

or in tsconfig.json under compilerOptions.types as "quicklook-kit/virtual".

3. Read the file

import { browserFile, config, nativeFile } from 'virtual:quicklook';

const file = nativeFile(); // the previewed file, undefined in the browser
config.public; // values from quicklook.config.*

Decode bytes however your format needs: new TextDecoder().decode(file.bytes) for text, or a parser for binary formats.

In the dev server, nativeFile() returns devFile if you set one, and undefined otherwise. Pass a dropped or picked File to browserFile() to get the same shape.

4. Add scripts

{
	"scripts": {
		"dev": "quicklook dev",
		"build": "quicklook build",
		"register": "quicklook build && quicklook register",
		"unregister": "quicklook unregister"
	}
}

CLI

build takes --platform macos or --platform windows to build just one. The Windows plugin builds on any OS; the macOS app only on a Mac, so elsewhere build skips it. Run build and register again after every change.

On macOS, register copies the app to /Applications and registers its extension. Select a file in Finder and press Space. If the preview doesn't show up, check pluginkit -mAv | grep <your macos.bundleId>, and make sure no other app claims the same file type.

On Windows, register copies the plugin to %APPDATA%\pooi.moe\QuickLook\QuickLook.Plugin\<windows.id>. Quit and restart QuickLook, then select a file in Explorer and press Space.

Add .quicklook to your .gitignore.

Things to know

• Nothing can be loaded from the network. The native host serves your build from disk with a strict Content Security Policy, on both platforms. Import images, fonts and CSS normally and they get bundled. The dev server only reports violations in the console, without blocking them.
• Inline scripts are allowed by hash. Frameworks that bootstrap with inline <script> tags keep working; the hashes are added to the CSP at build time.
• Test in Safari and Edge. macOS previews run in WebKit, like Safari; Windows previews in WebView2, like Edge.
• The light/dark theme follows the system. Use prefers-color-scheme in CSS.
• The macOS app is signed ad hoc. Other people have to allow it in System Settings → Privacy & Security on first launch. Distributing it without that step requires an Apple Developer account and notarization.
• Windows users install the .qlplugin from .quicklook/build/windows by previewing it in QuickLook and clicking the install button.

Releasing

Projects made with create quicklook include a release workflow. Push a tag like v1.0.0 and it builds every configured platform and attaches <App>-v1.0.0-macos.zip and <App>-v1.0.0-windows.qlplugin to a GitHub release.

If you publish a Homebrew cask, its URL needs the -macos suffix once you move to a release with platform groups.

Settings

settings declares options the user can change. On macOS, the app shows a control for each entry, picked by its type:

settings: {
  theme: {
    type: "string",
    default: "light",
    enum: [{ value: "light", description: "Light" }, "dark"],
    radio: true,
  },
  wrap: { type: "boolean", default: true, description: "Wrap **long** lines" },
  fontSize: { type: "integer", default: 13, minimum: 9, maximum: 32 },
  editor: {
    type: "object",
    properties: { tabSize: { type: "integer", default: 2, enum: [2, 4, 8] } },
  },
},

Every entry except object needs a default. title defaults to the key in words (fontSize becomes "Font Size"), description is inline Markdown, and order sorts entries. enum entries are plain values or { value, description }. A schema with an unknown type or field, a field on the wrong type, a key containing ., or a default that doesn't fit its type, enum or bounds fails the build with the key path, e.g. settings.editor.tabSize: default 0 is below minimum 1.

The page reads the values, nested like the schema, with settings():

import { settings } from 'virtual:quicklook';

const { wrap, editor } = settings();

In the dev server, settings() returns the defaults.

Windows has no settings window. Users set values in %APPDATA%\pooi.moe\QuickLook\<windows.id>.config, with nested keys joined by dots, and restart QuickLook. Values that don't fit the schema fall back to the default.

<?xml version="1.0" encoding="utf-8"?>
<Settings>
  <theme>dark</theme>
  <editor.tabSize>4</editor.tabSize>
</Settings>

Integrations

An integration is an object with a name and any of these hooks. They run in order: the framework first, then each entry in integrations.

import type { Integration } from 'quicklook-kit';

export default (options: { key: string }): Integration => ({
	name: 'my-integration',
	hooks: {
		// Adjust the resolved config.
		'config:resolved'(config) {},

		// Post-process the framework's static output before it's bundled.
		async 'build:done'({ outDir, config }) {},

		// Edit the generated XcodeGen spec: Info.plist keys, entitlements, targets. macOS only.
		'xcode:spec'(spec, config) {
			spec.targets.QuickLookExampleExtension.info.properties.MyKey = options.key;
		},

		// Add Vite plugins wherever quicklook() is used.
		vite: () => [],
	},
});

Add it as an object, or by name so JSON and YAML configs can use it too. A name is imported from the project: a package or a relative path, whose default export is the integration or a function returning it.

{
	"integrations": ["quicklook-some-package", ["./my-integration.ts", { "key": "value" }]]
}

A framework is an integration with a build field:

framework: {
	name: 'my-framework',
	build: {
		dev: ['vite', 'dev'],
		command: ['vite', 'build'],
		outDir: 'dist'
	}
}

The commands run with the project's own binaries.

License

This work is licensed under The MIT License.