quicklook-kit 0.1.0 → 0.2.0

package/package.json

@@ -1,8 +1,21 @@
 {
   "name": "quicklook-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Build macOS QuickLook previews with any Vite-based web framework",
   "license": "MIT",
+  "keywords": [
+    "quicklook",
+    "quicklook-plugin",
+    "sveltekit",
+    "svelte",
+    "astro",
+    "solid",
+    "solid-start",
+    "vue",
+    "nuxt",
+    "angular",
+    "analog"
+  ],
   "type": "module",
   "bin": {
     "quicklook": "./src/cli.ts"

package/readme.markdown

@@ -1,5 +1,9 @@
 # quicklook-kit
 
+![License](https://img.shields.io/npm/l/quicklook-kit?style=for-the-badge)
+[![Version](https://img.shields.io/npm/v/quicklook-kit?style=for-the-badge)](https://www.npmjs.org/package/quicklook-kit)
+[![Build](https://img.shields.io/github/actions/workflow/status/idleberg/quicklook-kit/ci.yml?style=for-the-badge)](https://github.com/idleberg/quicklook-kit/actions)
+
 > Build macOS QuickLook previews with any Vite-based web framework, no Swift required
 
 Your preview is a web page. quicklook-kit builds it with your framework, wraps it in a small native QuickLook extension and installs the resulting app. You never touch Swift or Xcode.
@@ -27,33 +31,34 @@ To start from scratch, use one of the [templates](https://github.com/idleberg/qu
 Create `quicklook.config.ts` in your project root:
 
 ```ts
-import { defineConfig } from 'quicklook-kit';
+import { defineConfig } from "quicklook-kit";
 
 export default defineConfig({
-	name: 'Example Preview', // app name, shown in Finder and System Settings
-	bundleId: 'com.example.ExamplePreview',
-	types: [
-		{
-			id: 'com.example.ExamplePreview.example',
-			description: 'Example File',
-			extensions: ['example'],
-			conformsTo: ['public.plain-text'] // or 'public.data' for binary formats
-		}
-	],
-	framework: 'sveltekit' // or 'astro', 'solid-start', 'nuxt', 'analog'
+  name: "Example Preview",
+  bundleId: "com.example.ExamplePreview",
+  types: [
+    {
+      id: "com.example.ExamplePreview.example",
+      description: "Example File",
+      extensions: ["example"],
+      conformsTo: ["public.plain-text"],
+    },
+  ],
+  framework: "sveltekit",
 });
 ```
 
-To preview a type macOS already knows about, use a plain string like `'public.json'` in place of an object.
+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.
 
 | Key            | Default      |                                                                                    |
 | -------------- | ------------ | ---------------------------------------------------------------------------------- |
-| `name`         | required     | App name                                                                           |
+| `name`         | required     | App name, shown in Finder and System Settings                                      |
 | `bundleId`     | required     | The extension gets `<bundleId>.Extension`                                          |
 | `types`        | required     | File types to preview                                                              |
 | `framework`    | required     | `'sveltekit'`, `'astro'`, `'solid-start'`, `'nuxt'`, `'analog'`, or an integration |
+| `icon`         | none         | Path to an `.icns` file for the app                                                |
 | `macOS`        | `'14.0'`     | Minimum macOS version                                                              |
 | `integrations` | `[]`         | See [Integrations](#integrations)                                                  |
 | `csp`          | locked down  | Directives here replace the defaults of the same name                              |
@@ -66,16 +71,16 @@ Each framework needs a static, client-side build:
 
 | Framework  | Requirement                                            |
 | ---------- | ------------------------------------------------------ |
-| SvelteKit  | `@sveltejs/adapter-static`                             |
+| Analog     | `@analogjs/vite-plugin-angular`                        |
 | Astro      | the default `output: 'static'`                         |
-| SolidStart | `ssr: false`, Nitro's `static` preset prerendering `/` |
 | Nuxt       | `ssr: false`                                           |
-| Analog     | `@analogjs/vite-plugin-angular`                        |
+| SolidStart | `ssr: false`, Nitro's `static` preset prerendering `/` |
+| SvelteKit  | `@sveltejs/adapter-static`                             |
 
 ### 2. Add the Vite plugin
 
 ```ts
-import { quicklook } from 'quicklook-kit/vite';
+import { quicklook } from "quicklook-kit/vite";
 
 // in the framework's Vite config
 plugins: [quicklook()];
@@ -92,7 +97,7 @@ or in `tsconfig.json` under `compilerOptions.types` as `"quicklook-kit/virtual"`
 ### 3. Read the file
 
 ```ts
-import { browserFile, config, nativeFile } from 'virtual:quicklook';
+import { browserFile, config, nativeFile } from "virtual:quicklook";
 
 const file = nativeFile(); // the previewed file inside QuickLook, undefined in the browser
 config.public; // values from quicklook.config.*
@@ -112,24 +117,24 @@ In the dev server, `nativeFile()` returns `undefined`. Pass a dropped or picked
 
 ```json
 {
-	"scripts": {
-		"dev": "quicklook dev",
-		"build": "quicklook build",
-		"register": "quicklook build && quicklook register",
-		"unregister": "quicklook unregister"
-	}
+  "scripts": {
+    "dev": "quicklook dev",
+    "build": "quicklook build",
+    "register": "quicklook build && quicklook register",
+    "unregister": "quicklook unregister"
+  }
 }
 ```
 
 ## CLI
 
-| Command                | Description                                                           |
-| ---------------------- | --------------------------------------------------------------------- |
-| `quicklook dev`        | Starts the framework's dev server                                     |
-| `quicklook build:web`  | Builds the page only, into `.quicklook/web`                           |
-| `quicklook build`      | Builds the app with its extension into `.quicklook/build`             |
-| `quicklook register`   | Copies the built app to `/Applications` and registers the extension   |
-| `quicklook unregister` | Removes the app from `/Applications`                                  |
+| Command                | Description                                                         |
+| ---------------------- | ------------------------------------------------------------------- |
+| `quicklook dev`        | Starts the framework's dev server                                   |
+| `quicklook build:web`  | Builds the page only, into `.quicklook/web`                         |
+| `quicklook build`      | Builds the app with its extension into `.quicklook/build`           |
+| `quicklook register`   | Copies the built app to `/Applications` and registers the extension |
+| `quicklook unregister` | Removes the app from `/Applications`                                |
 
 After `register`, select a file in Finder and press Space. Run `build` and `register` again after every change.
 
@@ -150,22 +155,25 @@ Add `.quicklook` to your `.gitignore`.
 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`.
 
 ```ts
-import type { Integration } from 'quicklook-kit';
+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.
-		'xcode:spec'(spec, config) {
-			spec.targets.ExamplePreviewExtension.info.properties.MyKey = options.key;
-		},
-		// Add Vite plugins wherever quicklook() is used.
-		vite: () => []
-	}
+  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.
+    "xcode:spec"(spec, config) {
+      spec.targets.ExamplePreviewExtension.info.properties.MyKey = options.key;
+    },
+
+    // Add Vite plugins wherever quicklook() is used.
+    vite: () => [],
+  },
 });
 ```
 
@@ -173,7 +181,7 @@ Add it as an object, or by name so JSON and YAML configs can use it too. A name
 
 ```jsonc
 {
-	"integrations": ["quicklook-some-package", ["./my-integration.ts", { "key": "value" }]]
+  "integrations": ["quicklook-some-package", ["./my-integration.ts", { "key": "value" }]],
 }
 ```
 

package/src/cli.ts

@@ -4,7 +4,7 @@
 import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { cp, rm } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { basename, resolve } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 import { $, Glob } from 'bun';
@@ -13,11 +13,11 @@ import {
 	type DeclaredType,
 	loadConfig,
 	serializeCsp,
-	type XcodeSpec
+	type XcodeSpec,
 } from './config.ts';
 
 const config = await loadConfig();
-const { root, name, bundleId, macOS, types, framework } = config;
+const { root, name, bundleId, macOS, types, framework, icon } = config;
 const target = name.replace(/[^A-Za-z0-9]/g, '');
 // Everything generated lives here, away from the framework's own output.
 const work = `${root}/.quicklook`;
@@ -35,7 +35,7 @@ const inlineScript = /<script\b(?![^>]*\ssrc=)[^>]*>([\s\S]*?)<\/script>/gi;
 async function run(command: string[]) {
 	const child = Bun.spawn(['bun', 'run', ...command], {
 		cwd: root,
-		stdio: ['inherit', 'inherit', 'inherit']
+		stdio: ['inherit', 'inherit', 'inherit'],
 	});
 	const code = await child.exited;
 	if (code !== 0) {
@@ -81,20 +81,24 @@ async function build() {
 				CURRENT_PROJECT_VERSION: '1',
 				// Ad-hoc signing: enough for QuickLook to load it, no Apple Developer account needed.
 				CODE_SIGN_STYLE: 'Manual',
-				CODE_SIGN_IDENTITY: '-'
-			}
+				CODE_SIGN_IDENTITY: '-',
+			},
 		},
 		targets: {
 			[target]: {
 				type: 'application',
 				platform: 'macOS',
-				sources: [`${native}/App`],
+				sources: [
+					`${native}/App`,
+					...(icon ? [{ path: resolve(root, icon), buildPhase: 'resources' }] : []),
+				],
 				settings: { PRODUCT_NAME: name, PRODUCT_BUNDLE_IDENTIFIER: bundleId },
 				dependencies: [{ target: `${target}Extension`, embed: true, codeSign: true }],
 				info: {
 					path: `${work}/App/Info.plist`,
 					properties: {
 						CFBundleName: name,
+						...(icon && { CFBundleIconFile: basename(icon, '.icns') }),
 						LSMinimumSystemVersion: macOS,
 						UTExportedTypeDeclarations: types
 							.filter((type): type is DeclaredType => typeof type !== 'string')
@@ -102,10 +106,10 @@ async function build() {
 								UTTypeIdentifier: type.id,
 								UTTypeDescription: type.description,
 								UTTypeConformsTo: type.conformsTo,
-								UTTypeTagSpecification: { 'public.filename-extension': type.extensions }
-							}))
-					}
-				}
+								UTTypeTagSpecification: { 'public.filename-extension': type.extensions },
+							})),
+					},
+				},
 			},
 			[`${target}Extension`]: {
 				type: 'app-extension',
@@ -121,8 +125,8 @@ async function build() {
 						'com.apple.security.files.user-selected.read-only': true,
 						// WKWebView's content process won't launch in a sandbox without this,
 						// even for a page that loads nothing. The page's CSP blocks all requests.
-						'com.apple.security.network.client': true
-					}
+						'com.apple.security.network.client': true,
+					},
 				},
 				info: {
 					path: `${work}/Extension/Info.plist`,
@@ -136,15 +140,15 @@ async function build() {
 							NSExtensionPrincipalClass: 'PreviewViewController',
 							NSExtensionAttributes: {
 								QLSupportedContentTypes: types.map((type) =>
-									typeof type === 'string' ? type : type.id
+									typeof type === 'string' ? type : type.id,
 								),
-								QLSupportsSearchableItems: false
-							}
-						}
-					}
-				}
-			}
-		}
+								QLSupportsSearchableItems: false,
+							},
+						},
+					},
+				},
+			},
+		},
 	};
 	for (const integration of config.integrations) {
 		await integration.hooks?.['xcode:spec']?.(spec, config);

package/src/config.ts

@@ -52,6 +52,8 @@ export interface QuickLookConfig {
 	/** App name, shown in Finder and System Settings. */
 	name: string;
 	bundleId: string;
+	/** Path to the app's .icns icon, relative to the project root. */
+	icon?: string;
 	/** Minimum macOS version. Defaults to 14.0. */
 	macOS?: string;
 	types: FileType[];
@@ -70,7 +72,8 @@ export interface QuickLookConfig {
 export type PageConfig = Pick<ResolvedConfig, 'name' | 'bundleId' | 'types' | 'public'>;
 
 export interface ResolvedConfig
-	extends Required<Omit<QuickLookConfig, 'framework' | 'integrations'>> {
+	extends Required<Omit<QuickLookConfig, 'framework' | 'integrations' | 'icon'>>,
+		Pick<QuickLookConfig, 'icon'> {
 	root: string;
 	framework: Integration & { build: NonNullable<Integration['build']> };
 	/** The framework first, then the configured integrations, in order. */
@@ -84,7 +87,7 @@ export const defaultCsp: Csp = {
 	'style-src': ["'self'", "'unsafe-inline'"],
 	'img-src': ["'self'", 'data:', 'blob:'],
 	'font-src': ["'self'", 'data:'],
-	'media-src': ["'self'", 'data:', 'blob:']
+	'media-src': ["'self'", 'data:', 'blob:'],
 };
 
 export const defineConfig = (config: QuickLookConfig) => config;
@@ -97,7 +100,7 @@ export const serializeCsp = (csp: Csp) =>
 /** `csp` with `sources` appended to `directive`. */
 export const addSources = (csp: Csp, directive: string, ...sources: string[]): Csp => ({
 	...csp,
-	[directive]: [...(csp[directive] ?? []), ...sources]
+	[directive]: [...(csp[directive] ?? []), ...sources],
 });
 
 /**
@@ -114,7 +117,7 @@ const frameworkBuilds: Record<string, [dev: string[], command: string[], outDir:
 	// `solidStart({ ssr: false })` and Nitro's static preset prerendering `/`.
 	'solid-start': [['vite', 'dev'], ['vite', 'build'], '.output/public'],
 	// @sveltejs/adapter-static, writing `build`.
-	sveltekit: [['vite', 'dev'], ['vite', 'build'], 'build']
+	sveltekit: [['vite', 'dev'], ['vite', 'build'], 'build'],
 };
 
 function builtinFramework(name: string, options?: unknown): Integration | undefined {
@@ -125,7 +128,7 @@ function builtinFramework(name: string, options?: unknown): Integration | undefi
 	const [dev, command, outDir] = builtin;
 	return {
 		name,
-		build: { dev, command, outDir: (options as { outDir?: string } | undefined)?.outDir ?? outDir }
+		build: { dev, command, outDir: (options as { outDir?: string } | undefined)?.outDir ?? outDir },
 	};
 }
 
@@ -167,7 +170,7 @@ export async function loadConfig(root = process.cwd()): Promise<ResolvedConfig>
 		csp: { ...defaultCsp, ...config.csp },
 		root,
 		framework: { ...framework, build: framework.build },
-		integrations
+		integrations,
 	};
 	for (const integration of integrations) {
 		await integration.hooks?.['config:resolved']?.(resolved);

package/src/runtime.ts

@@ -22,7 +22,7 @@ export function nativeFile(): QuickLookFile | undefined {
 	return {
 		name: injected.name,
 		extension: injected.extension,
-		bytes: Uint8Array.from(atob(injected.base64), (c) => c.charCodeAt(0))
+		bytes: Uint8Array.from(atob(injected.base64), (c) => c.charCodeAt(0)),
 	};
 }
 
@@ -31,6 +31,6 @@ export async function browserFile(file: File): Promise<QuickLookFile> {
 	return {
 		name: file.name,
 		extension: file.name.includes('.') ? (file.name.split('.').pop() ?? '').toLowerCase() : '',
-		bytes: new Uint8Array(await file.arrayBuffer())
+		bytes: new Uint8Array(await file.arrayBuffer()),
 	};
 }

package/src/vite.ts

@@ -20,8 +20,8 @@ export { browserFile, nativeFile } from 'quicklook-kit/runtime';`;
 			addSources(config.csp, 'script-src', "'unsafe-inline'"),
 			'connect-src',
 			"'self'",
-			'ws:'
-		)
+			'ws:',
+		),
 	);
 
 	return [
@@ -34,8 +34,8 @@ export { browserFile, nativeFile } from 'quicklook-kit/runtime';`;
 					response.setHeader('Content-Security-Policy-Report-Only', devCsp);
 					next();
 				});
-			}
+			},
 		},
-		...config.integrations.flatMap((integration) => integration.hooks?.vite?.() ?? [])
+		...config.integrations.flatMap((integration) => integration.hooks?.vite?.() ?? []),
 	];
 }