|
| 1 | +--- |
| 2 | +title: "Minify" |
| 3 | +description: "Minify inline script and style tag content during SSR rendering. Zero-dependency lightweight minifiers for edge and serverless, with support for custom minifiers." |
| 4 | +navigation.title: "Minify" |
| 5 | +--- |
| 6 | + |
| 7 | +**Quick Answer:** The Minify plugin strips comments, collapses whitespace, and minifies inline `<script>` and `<style>` content during SSR rendering. It uses lightweight pure-JS minifiers by default — zero native dependencies, safe for edge and serverless. |
| 8 | + |
| 9 | +## What Does This Plugin Do? |
| 10 | + |
| 11 | +The Minify plugin hooks into the SSR render pipeline and minifies: |
| 12 | + |
| 13 | +- **Inline scripts** — strips comments, collapses whitespace, preserves string literals and ASI safety |
| 14 | +- **Inline styles** — strips comments, collapses whitespace, removes trailing semicolons, strips leading zeros |
| 15 | +- **JSON-LD / application/json** — re-serializes to remove pretty-printing whitespace |
| 16 | + |
| 17 | +It automatically skips `speculationrules` and `importmap` script types, and never increases content length. |
| 18 | + |
| 19 | +## How Do I Set Up the Plugin? |
| 20 | + |
| 21 | +Register the plugin when creating your head instance: |
| 22 | + |
| 23 | +::code-block |
| 24 | +```ts [Input] |
| 25 | +import { MinifyPlugin } from 'unhead/plugins' |
| 26 | + |
| 27 | +const head = createHead({ |
| 28 | + plugins: [ |
| 29 | + MinifyPlugin() |
| 30 | + ] |
| 31 | +}) |
| 32 | +``` |
| 33 | +:: |
| 34 | + |
| 35 | +## What Options Can I Configure? |
| 36 | + |
| 37 | +::code-block |
| 38 | +```ts [Input] |
| 39 | +export interface MinifyPluginOptions { |
| 40 | + /** |
| 41 | + * Custom JS minifier function. Set to `false` to disable JS minification. |
| 42 | + * Defaults to built-in lightweight minifier. |
| 43 | + */ |
| 44 | + js?: false | ((code: string) => string) |
| 45 | + /** |
| 46 | + * Custom CSS minifier function. Set to `false` to disable CSS minification. |
| 47 | + * Defaults to built-in lightweight minifier. |
| 48 | + */ |
| 49 | + css?: false | ((code: string) => string) |
| 50 | + /** |
| 51 | + * Minify JSON script types (application/ld+json, application/json). |
| 52 | + * @default true |
| 53 | + */ |
| 54 | + json?: boolean |
| 55 | +} |
| 56 | +``` |
| 57 | +:: |
| 58 | + |
| 59 | +### Disable Specific Minifiers |
| 60 | + |
| 61 | +::code-block |
| 62 | +```ts [Input] |
| 63 | +MinifyPlugin({ |
| 64 | + js: false, // skip script minification |
| 65 | + json: false, // skip JSON-LD minification |
| 66 | +}) |
| 67 | +``` |
| 68 | +:: |
| 69 | + |
| 70 | +### Custom Minifiers |
| 71 | + |
| 72 | +Provide your own synchronous minifier function for heavier optimization: |
| 73 | + |
| 74 | +::code-block |
| 75 | +```ts [Input] |
| 76 | +MinifyPlugin({ |
| 77 | + js: (code) => myCustomJSMinify(code), |
| 78 | + css: (code) => myCustomCSSMinify(code), |
| 79 | +}) |
| 80 | +``` |
| 81 | +:: |
| 82 | + |
| 83 | +Note: The `ssr:render` hook runs synchronously, so custom minifiers must be synchronous. |
| 84 | + |
| 85 | +## Build-Time Minification |
| 86 | + |
| 87 | +For build-time minification of static string literals inside `useHead()` / `useServerHead()` calls, use the Vite/Webpack transform plugin from `@unhead/addons`. This runs at build time using heavier tools (rolldown/esbuild for JS, lightningcss for CSS) that never enter your SSR runtime bundle. |
| 88 | + |
| 89 | +::code-group |
| 90 | + |
| 91 | +```bash [pnpm] |
| 92 | +pnpm add -D @unhead/addons |
| 93 | +``` |
| 94 | + |
| 95 | +```bash [yarn] |
| 96 | +yarn add -D @unhead/addons |
| 97 | +``` |
| 98 | + |
| 99 | +```bash [npm] |
| 100 | +npm install -D @unhead/addons |
| 101 | +``` |
| 102 | + |
| 103 | +:: |
| 104 | + |
| 105 | +Configure the Vite plugin with minifier functions: |
| 106 | + |
| 107 | +::code-block |
| 108 | +```ts [vite.config.ts] |
| 109 | +import UnheadVite from '@unhead/addons/vite' |
| 110 | +import { createJSMinifier } from '@unhead/addons/minify/rolldown' |
| 111 | +import { createCSSMinifier } from '@unhead/addons/minify/lightningcss' |
| 112 | + |
| 113 | +export default defineConfig({ |
| 114 | + plugins: [ |
| 115 | + UnheadVite({ |
| 116 | + minify: { |
| 117 | + js: createJSMinifier(), |
| 118 | + css: createCSSMinifier(), |
| 119 | + } |
| 120 | + }) |
| 121 | + ] |
| 122 | +}) |
| 123 | +``` |
| 124 | +:: |
| 125 | + |
| 126 | +Available minifier backends: |
| 127 | + |
| 128 | +| Package | Function | Use case | |
| 129 | +|---------|----------|----------| |
| 130 | +| `@unhead/addons/minify/rolldown` | `createJSMinifier()` | JS minification (Vite 8+) | |
| 131 | +| `@unhead/addons/minify/esbuild` | `createJSMinifier()` | JS minification (Vite 7) | |
| 132 | +| `@unhead/addons/minify/lightningcss` | `createCSSMinifier()` | CSS minification | |
| 133 | + |
| 134 | +## Standalone Minifier Utilities |
| 135 | + |
| 136 | +The built-in minifiers are also available as standalone functions for use in custom build pipelines: |
| 137 | + |
| 138 | +::code-block |
| 139 | +```ts [Input] |
| 140 | +import { minifyCSS, minifyJS, minifyJSON } from 'unhead/minify' |
| 141 | + |
| 142 | +const minifiedJS = minifyJS('// comment\nvar x = 1;') |
| 143 | +const minifiedCSS = minifyCSS('body { margin: 0; }') |
| 144 | +const minifiedJSON = minifyJSON('{ "name": "test" }') |
| 145 | +``` |
| 146 | +:: |
| 147 | + |
| 148 | +## Related |
| 149 | + |
| 150 | +- [Build Plugins](/docs/head/guides/advanced/vite-plugin) - Vite and Webpack build optimizations |
| 151 | +- [Validate Plugin](/docs/head/guides/plugins/validate) - Catch common SEO and head tag mistakes |
| 152 | +- [Inner Content](/docs/head/guides/core-concepts/inner-content) - Working with innerHTML and textContent |
0 commit comments