@eleventy-plugin-themer/build-vite 0.1.0

package/plugins/minify-html.mjs

@@ -0,0 +1,66 @@
+import fs from 'fs/promises';
+
+import { minify } from 'html-minifier-terser';
+
+import { processFiles } from '../utils/file-processor.mjs';
+import { GLOB_PATTERNS } from '../utils/constants.mjs';
+
+export async function minifyHTML(outputDir, userOptions = {}) {
+  // outputDir is guaranteed to be provided by the orchestrator
+  const defaultOptions = {
+    collapseBooleanAttributes: true,
+    collapseWhitespace: true,
+    conservativeCollapse: false,
+    decodeEntities: true,
+    html5: true,
+    includeAutoGeneratedTags: false,
+    minifyCSS: true,
+    minifyJS: true,
+    preserveLineBreaks: false,
+    preventAttributesEscaping: true,
+    removeAttributeQuotes: true,
+    removeComments: true,
+    removeEmptyAttributes: true,
+    removeOptionalTags: false,
+    removeRedundantAttributes: true,
+    removeScriptTypeAttributes: true,
+    removeStyleLinkTypeAttributes: true,
+    sortAttributes: true,
+    sortClassName: true,
+    useShortDoctype: true,
+  };
+
+  const options = { ...defaultOptions, ...userOptions };
+
+  return processFiles({
+    pattern: GLOB_PATTERNS.html(outputDir),
+    outputDir,
+    taskName: 'HTML Minification',
+    errorTip:
+      'Check if HTML is valid and properly formed. Invalid HTML can cause minification to fail.',
+    processor: async (file) => {
+      const html = await fs.readFile(file, 'utf-8');
+      const originalSize = Buffer.byteLength(html, 'utf8');
+      const minified = await minify(html, options);
+      const minifiedSize = Buffer.byteLength(minified, 'utf8');
+
+      await fs.writeFile(file, minified);
+
+      const savings = ((1 - minifiedSize / originalSize) * 100).toFixed(1);
+
+      return {
+        message: ` (${savings}% smaller)`,
+        stats: { originalSize, minifiedSize },
+      };
+    },
+    calculateStats: (results) => {
+      const totalOriginal = results.reduce((sum, r) => sum + r.stats.originalSize, 0);
+      const totalMinified = results.reduce((sum, r) => sum + r.stats.minifiedSize, 0);
+      const totalSavings = ((1 - totalMinified / totalOriginal) * 100).toFixed(1);
+
+      return {
+        'total reduction': `${totalSavings}% (${(totalOriginal / 1024).toFixed(1)} KB → ${(totalMinified / 1024).toFixed(1)} KB)`,
+      };
+    },
+  });
+}

package/plugins/preserve-non-html.mjs

@@ -0,0 +1,55 @@
+/**
+ * Preserve Non-HTML Files
+ * Copies non-HTML files (XML, TXT, XSL) from Vite temp folder to output
+ * Ensures feed files and other static assets are included in build
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+
+import { glob } from 'glob';
+import { logger } from '@eleventy-plugin-themer/core/logger';
+
+/**
+ * Copy non-HTML files from .11ty-vite to _site
+ * @param {string} outputDir - Output directory (default: '_site')
+ * @param {Object} options - Configuration options
+ * @param {string} options.temp - Vite temp directory (required)
+ * @param {string[]} options.extensions - File extensions to preserve (default: [])
+ */
+export async function preserveNonHtmlFiles(outputDir, options = {}) {
+  const { temp: tempDir, extensions = [] } = options;
+
+  if (!tempDir) {
+    logger.warn('⚠️  preserveNonHtmlFiles: tempDir option is required');
+    return;
+  }
+
+  if (extensions.length === 0) {
+    return;
+  }
+
+  logger.info('\n📋 Preserving non-HTML files...\n');
+
+  const pattern = `${tempDir}/**/*.{${extensions.join(',')}}`;
+  const files = await glob(pattern);
+
+  if (files.length === 0) {
+    logger.info('   No non-HTML files to preserve\n');
+    return;
+  }
+
+  let copiedCount = 0;
+
+  for (const file of files) {
+    const dest = path.join(outputDir, path.relative(tempDir, file));
+    await fs.mkdir(path.dirname(dest), { recursive: true });
+    await fs.copyFile(file, dest);
+    copiedCount++;
+
+    const relativePath = path.relative(outputDir, dest);
+    logger.info(`   ✓ ${relativePath}`);
+  }
+
+  logger.info(`\n✅ Preserved ${copiedCount} non-HTML file(s)\n`);
+}

package/plugins/prism-theme.mjs

@@ -0,0 +1,61 @@
+/**
+ * Vite plugin for config-driven PrismJS theme loading
+ *
+ * Provides a virtual module `virtual:prism-theme` that resolves to
+ * the configured PrismJS theme CSS and optional diff-highlight plugin.
+ *
+ * Theme is configured via theme.json `config.codeHighlighting.prismTheme`.
+ * Users override in their `theme.config.mjs`.
+ */
+
+const VIRTUAL_MODULE_ID = 'virtual:prism-theme';
+const RESOLVED_VIRTUAL_MODULE_ID = '\0' + VIRTUAL_MODULE_ID;
+
+/**
+ * Valid PrismJS theme names (bundled with prismjs package)
+ */
+const VALID_THEMES = new Set([
+  'prism',
+  'prism-coy',
+  'prism-dark',
+  'prism-funky',
+  'prism-okaidia',
+  'prism-solarizedlight',
+  'prism-tomorrow',
+  'prism-twilight',
+]);
+
+/**
+ * @param {Object} options
+ * @param {string} [options.prismTheme='prism-tomorrow'] - PrismJS theme name (without .css)
+ * @param {boolean} [options.diffHighlight=true] - Include diff-highlight plugin CSS
+ * @returns {import('vite').Plugin}
+ */
+export function prismThemePlugin(options = {}) {
+  const { prismTheme = 'prism-tomorrow', diffHighlight = true } = options;
+
+  if (!VALID_THEMES.has(prismTheme)) {
+    const available = [...VALID_THEMES].join(', ');
+    throw new Error(`[prism-theme] Invalid theme "${prismTheme}". Available themes: ${available}`);
+  }
+
+  return {
+    name: 'eleventy-themes-prism-theme',
+
+    resolveId(id) {
+      if (id === VIRTUAL_MODULE_ID) {
+        return RESOLVED_VIRTUAL_MODULE_ID;
+      }
+    },
+
+    load(id) {
+      if (id === RESOLVED_VIRTUAL_MODULE_ID) {
+        let code = `import 'prismjs/themes/${prismTheme}.css';\n`;
+        if (diffHighlight) {
+          code += `import 'prismjs/plugins/diff-highlight/prism-diff-highlight.css';\n`;
+        }
+        return code;
+      }
+    },
+  };
+}

package/plugins/purge-css.mjs

@@ -0,0 +1,64 @@
+import fs from 'fs/promises';
+
+import { PurgeCSS } from 'purgecss';
+
+import { processFiles } from '../utils/file-processor.mjs';
+import { GLOB_PATTERNS } from '../utils/constants.mjs';
+
+export async function purgeCSSFiles(outputDir, options = {}) {
+  const { safelist: extraSafelist = {} } = options;
+
+  // Default safelist — generic patterns the build plugin always preserves
+  // Theme-specific patterns belong in theme.json under build.purgeCSS.safelist
+  const defaultSafelist = {
+    standard: [/^is-/, /^has-/, /^js-/, /^page-/],
+    deep: [],
+    greedy: [],
+  };
+
+  // Merge theme/user safelist with defaults (strings become RegExp)
+  const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const toRegExp = (v) => (v instanceof RegExp ? v : new RegExp(escapeRegExp(v)));
+  const mergedSafelist = {
+    standard: [...defaultSafelist.standard, ...(extraSafelist.standard || []).map(toRegExp)],
+    deep: [...defaultSafelist.deep, ...(extraSafelist.deep || []).map(toRegExp)],
+    greedy: [...defaultSafelist.greedy, ...(extraSafelist.greedy || []).map(toRegExp)],
+  };
+
+  // outputDir is guaranteed to be provided by the orchestrator
+  return processFiles({
+    pattern: GLOB_PATTERNS.css(outputDir),
+    outputDir,
+    taskName: 'PurgeCSS',
+    processor: async (file) => {
+      const stat = await fs.stat(file);
+      const originalSize = stat.size;
+
+      const results = await new PurgeCSS().purge({
+        content: [GLOB_PATTERNS.html(outputDir)],
+        css: [file],
+        safelist: mergedSafelist,
+        defaultExtractor: (content) => {
+          const matches = content.match(/[^<>"'`\s]*[^<>"'`\s:]/g) || [];
+          return matches;
+        },
+        keyframes: true,
+        fontFace: true,
+        variables: true,
+        rejected: false,
+        rejectedCss: false,
+      });
+
+      await fs.writeFile(file, results[0].css);
+
+      const newStat = await fs.stat(file);
+      const newSize = newStat.size;
+      const reduction = ((1 - newSize / originalSize) * 100).toFixed(1);
+
+      return {
+        message: ` (${reduction}% smaller)`,
+        stats: { originalSize, newSize, reduction },
+      };
+    },
+  });
+}

package/plugins/validate-links.mjs

@@ -0,0 +1,164 @@
+/**
+ * Link Validation
+ * Validates internal links and images after build
+ * Catches broken links before deployment
+ */
+
+import path from 'path';
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+
+import { glob } from 'glob';
+import { parse } from 'node-html-parser';
+import { logger } from '@eleventy-plugin-themer/core/logger';
+
+import { GLOB_PATTERNS } from '../utils/constants.mjs';
+
+/**
+ * Check resources (links or images) in parsed HTML for broken references
+ *
+ * @param {Object} root - Parsed HTML root from node-html-parser
+ * @param {Object} options
+ * @param {string} options.selector - CSS selector (e.g., 'a[href]', 'img[src]')
+ * @param {string} options.attribute - Attribute to check (e.g., 'href', 'src')
+ * @param {string[]} options.skipPrefixes - URL prefixes to skip
+ * @param {string} options.errorType - Error type label (e.g., 'broken-link', 'missing-image')
+ * @param {string} options.errorPrefix - Error message prefix
+ * @param {string} options.outputDir - Build output directory
+ * @param {string} options.baseDir - Directory of the HTML file
+ * @param {string} options.relativePath - Relative path of the HTML file
+ * @returns {{ count: number, errors: Array }}
+ */
+function checkResources(root, options) {
+  const {
+    selector,
+    attribute,
+    skipPrefixes,
+    errorType,
+    errorPrefix,
+    outputDir,
+    baseDir,
+    relativePath,
+  } = options;
+
+  const elements = root.querySelectorAll(selector);
+  const errors = [];
+  let count = 0;
+
+  for (const el of elements) {
+    const value = el.getAttribute(attribute);
+    if (!value || skipPrefixes.some((prefix) => value.startsWith(prefix))) {
+      continue;
+    }
+
+    count++;
+
+    const cleanValue = value.split('#')[0].split('?')[0];
+
+    let targetPath;
+    if (cleanValue.startsWith('/')) {
+      targetPath = path.join(outputDir, cleanValue);
+    } else {
+      targetPath = path.join(baseDir, cleanValue);
+    }
+
+    const fileExists = existsSync(targetPath);
+    const indexExists = !fileExists && existsSync(path.join(targetPath, 'index.html'));
+
+    if (!fileExists && !indexExists) {
+      errors.push({
+        file: relativePath,
+        type: errorType,
+        target: value,
+        message: `${errorPrefix}: ${value}`,
+      });
+    }
+  }
+
+  return { count, errors };
+}
+
+const LINK_SKIP_PREFIXES = ['http://', 'https://', 'mailto:', 'tel:', '#'];
+const IMAGE_SKIP_PREFIXES = ['http://', 'https://', 'data:'];
+
+/**
+ * Validate links and images in built HTML.
+ * Throws an error if validation fails.
+ * @param {string} outputDir - Output directory to validate
+ * @param {Object} options - Validation options (currently unused but reserved)
+ */
+export async function validateLinks(outputDir, _options = {}) {
+  logger.info('\n🔗 Validating links and images...\n');
+
+  const htmlFiles = await glob(GLOB_PATTERNS.html(outputDir));
+
+  const errors = [];
+  let totalLinks = 0;
+  let totalImages = 0;
+
+  for (const htmlFile of htmlFiles) {
+    try {
+      const html = await fs.readFile(htmlFile, 'utf-8');
+      const root = parse(html);
+
+      const relativePath = path.relative(outputDir, htmlFile);
+      const baseDir = path.dirname(htmlFile);
+      const common = { outputDir, baseDir, relativePath };
+
+      const links = checkResources(root, {
+        ...common,
+        selector: 'a[href]',
+        attribute: 'href',
+        skipPrefixes: LINK_SKIP_PREFIXES,
+        errorType: 'broken-link',
+        errorPrefix: 'Broken internal link',
+      });
+
+      const images = checkResources(root, {
+        ...common,
+        selector: 'img[src]',
+        attribute: 'src',
+        skipPrefixes: IMAGE_SKIP_PREFIXES,
+        errorType: 'missing-image',
+        errorPrefix: 'Missing image',
+      });
+
+      totalLinks += links.count;
+      totalImages += images.count;
+      errors.push(...links.errors, ...images.errors);
+    } catch (error) {
+      errors.push({
+        file: path.relative(outputDir, htmlFile),
+        type: 'parse-error',
+        message: `Failed to parse HTML: ${error.message}`,
+      });
+    }
+  }
+
+  // Report results
+  if (errors.length > 0) {
+    logger.error(`❌ Link validation failed: ${errors.length} errors found\n`);
+
+    const grouped = {
+      'broken-link': { icon: '🔗', label: 'Broken Links' },
+      'missing-image': { icon: '🖼️ ', label: 'Missing Images' },
+      'parse-error': { icon: '⚠️ ', label: 'Parse Errors' },
+    };
+
+    for (const [type, { icon, label }] of Object.entries(grouped)) {
+      const items = errors.filter((e) => e.type === type);
+      if (items.length === 0) continue;
+
+      logger.error(`\n${icon} ${label} (${items.length}):`);
+      items.forEach(({ file, target, message }) => {
+        logger.error(`   ${file}${target ? ` → ${target}` : `: ${message}`}`);
+      });
+    }
+
+    logger.error('\n💡 Tip: Fix broken links and missing images before deployment\n');
+
+    throw new Error(`Link validation failed with ${errors.length} error(s). Fix issues above.`);
+  }
+
+  logger.info(`✅ Link validation passed: ${totalLinks} links, ${totalImages} images\n`);
+}

package/postcss.mjs

@@ -0,0 +1,113 @@
+/**
+ * Theme-aware PostCSS preset for consumer `postcss.config.mjs` files.
+ *
+ * Themes can declare a `build.postcss.plugins` array in `theme.json` listing
+ * preferred PostCSS plugin packages (with options). Consumers call
+ * `createPostcssConfig({ themeMetadata, userPlugins })` from their own
+ * `postcss.config.mjs` to get a ready-to-export config that defers to theme
+ * defaults but lets the user append project-specific plugins.
+ *
+ * Example `theme.json`:
+ *   "build": {
+ *     "postcss": {
+ *       "plugins": [
+ *         { "package": "postcss-preset-env", "options": { "stage": 3 } },
+ *         {
+ *           "package": "cssnano",
+ *           "options": { "preset": "default" },
+ *           "production": true
+ *         }
+ *       ]
+ *     }
+ *   }
+ *
+ * Each plugin entry:
+ *   - `package` (string, required): the npm package name to dynamic-import.
+ *   - `options` (object, optional): passed to the plugin factory.
+ *   - `production` (boolean, optional): if `true`, only loaded when
+ *     `process.env.NODE_ENV === 'production'`.
+ */
+
+import { createRequire } from 'module';
+import path from 'path';
+import { pathToFileURL } from 'url';
+
+/**
+ * NOTE: PostCSS config files are loaded synchronously at module-import time,
+ * before Eleventy's async config function runs — so a consumer's
+ * `postcss.config.mjs` cannot read the themer context off `eleventyConfig`
+ * (it doesn't exist yet). It therefore re-reads `theme.json` via
+ * `resolveThemeMetadata`. The cost is one static-file read per process; if
+ * the same Node process also instantiates `createThemerProject` from
+ * `eleventy.config.mjs`, `resolveThemeMetadata`'s module-level cache
+ * collapses both calls to a single disk read.
+ *
+ * @param {Object} args
+ * @param {Object} args.themeMetadata - Output of `resolveThemeMetadata`.
+ * @param {string} [args.projectRoot] - Project root used for resolving
+ *   theme-declared plugin packages. Defaults to `process.cwd()` (which is
+ *   correct when called from a consumer's `postcss.config.mjs`).
+ * @param {Array} [args.userPlugins] - Already-instantiated PostCSS plugins to
+ *   append after the theme defaults. Use this to add project-specific
+ *   plugins or to override theme plugins (PostCSS evaluates in order).
+ * @param {boolean} [args.production] - Override env detection (defaults to
+ *   `process.env.NODE_ENV === 'production'`).
+ * @returns {Promise<{ plugins: Array }>} A PostCSS config object.
+ */
+export async function createPostcssConfig({
+  themeMetadata,
+  projectRoot,
+  userPlugins = [],
+  production,
+} = {}) {
+  if (!themeMetadata) {
+    throw new Error('createPostcssConfig: themeMetadata is required');
+  }
+
+  const isProduction =
+    typeof production === 'boolean' ? production : process.env.NODE_ENV === 'production';
+
+  const declared = themeMetadata?.build?.postcss?.plugins;
+  const themePluginEntries = Array.isArray(declared) ? declared : [];
+  if (themePluginEntries.length === 0) {
+    return { plugins: [...userPlugins] };
+  }
+
+  // Resolve packages relative to the consumer's project root rather than this
+  // build-vite file. Plugin packages are dependencies of the consumer, not of
+  // build-vite.
+  const cwd = projectRoot || process.cwd();
+  const requireFromProject = createRequire(path.join(cwd, 'package.json'));
+
+  const themePlugins = [];
+  for (const entry of themePluginEntries) {
+    if (!entry || typeof entry !== 'object') continue;
+    const { package: pkgName, options, production: prodOnly } = entry;
+    if (!pkgName || typeof pkgName !== 'string') continue;
+    if (prodOnly && !isProduction) continue;
+
+    let resolvedPath;
+    try {
+      resolvedPath = requireFromProject.resolve(pkgName);
+    } catch (cause) {
+      throw new Error(
+        `createPostcssConfig: PostCSS plugin "${pkgName}" declared by the theme is not ` +
+          `installed in the consumer project. Add it to your dependencies.`,
+        { cause },
+      );
+    }
+
+    const mod = await import(pathToFileURL(resolvedPath).href);
+    const factory = mod.default ?? mod;
+    if (typeof factory !== 'function') {
+      throw new Error(
+        `createPostcssConfig: PostCSS plugin "${pkgName}" did not export a callable default.`,
+      );
+    }
+    themePlugins.push(options !== undefined ? factory(options) : factory());
+  }
+
+  return {
+    plugins: [...themePlugins, ...userPlugins],
+  };
+}