@eleventy-plugin-themer/build-vite 0.1.0

package/theme-config.mjs

@@ -0,0 +1,245 @@
+/**
+ * Vite configuration helper for Eleventy themes
+ *
+ * Provides theme-agnostic Vite configuration with auto-import support
+ */
+
+import path from 'path';
+
+import { getThemeRoot } from '@eleventy-plugin-themer/core/internal/api';
+import { DEFAULT_ASSET_ENTRIES } from '@eleventy-plugin-themer/core/internal/defaults';
+import { logger } from '@eleventy-plugin-themer/core/logger';
+import { UNSAFE_KEYS } from '@eleventy-plugin-themer/core/internal/safe-keys';
+
+import { themeAutoImportPlugin } from './plugins/auto-import.mjs';
+import { featureServePlugin } from './plugins/feature-serve.mjs';
+import { prismThemePlugin } from './plugins/prism-theme.mjs';
+import { runOptimizations } from './utils/plugin-orchestrator.mjs';
+import { getFeaturePathsForBuild } from './utils/features.mjs';
+import { deepMergeViteConfig } from './utils/merge-config.mjs';
+import { mergeStringArrays } from './utils/merge-arrays.mjs';
+
+/**
+ * Merge theme build hints into user optimization config.
+ *
+ * Themes declare build hints (e.g. PurgeCSS safelist) in `theme.json#build`.
+ * These are merged with the user's `optimizations` config so the underlying
+ * optimization plugin receives the union.
+ *
+ * Merge precedence:
+ *   - Theme defaults come **first** (preserved at the head of array merges).
+ *   - User values **append** (deduped) for safelist arrays so user input
+ *     never silently shadows theme requirements, but also can't break
+ *     greedy patterns relied on by the theme.
+ *   - Object merges put user values **last** (user wins for primitive fields).
+ *
+ * Unsafe keys (`__proto__`, `constructor`, `prototype`) on `themeBuild` are
+ * silently skipped to prevent prototype pollution via parsed JSON.
+ *
+ * @param {Object} optimizations - User-supplied optimization config.
+ * @param {Object} themeBuild - Theme-supplied `build` block from `theme.json`.
+ * @returns {Object} Merged optimizations object (new reference).
+ */
+function mergeThemeBuildHints(optimizations, themeBuild) {
+  if (!optimizations || !themeBuild) return optimizations;
+
+  const merged = { ...optimizations };
+
+  for (const [pluginName, themeConfig] of Object.entries(themeBuild)) {
+    if (UNSAFE_KEYS.has(pluginName)) continue;
+    if (!(pluginName in merged) || !merged[pluginName]) continue;
+
+    if (merged[pluginName] === true) {
+      merged[pluginName] = { ...themeConfig };
+    } else if (typeof merged[pluginName] === 'object') {
+      if (themeConfig.safelist || merged[pluginName].safelist) {
+        const userSafelist = merged[pluginName].safelist || {};
+        const themeSafelist = themeConfig.safelist || {};
+        merged[pluginName] = {
+          ...merged[pluginName],
+          safelist: {
+            standard: mergeStringArrays(themeSafelist.standard, userSafelist.standard),
+            deep: mergeStringArrays(themeSafelist.deep, userSafelist.deep),
+            greedy: mergeStringArrays(themeSafelist.greedy, userSafelist.greedy),
+          },
+        };
+      } else {
+        merged[pluginName] = { ...merged[pluginName], ...themeConfig };
+      }
+    }
+  }
+
+  return merged;
+}
+
+function buildFeatureAliases(discoveredFeatures) {
+  const featurePaths = getFeaturePathsForBuild(discoveredFeatures);
+  const aliases = {};
+  featurePaths.forEach((featurePath, featureName) => {
+    aliases[`/${featureName}.js`] = featurePath;
+  });
+  return aliases;
+}
+
+function buildResolveAliases({ themeRoot, projectRoot, resolvedOverridePaths, featureAliases }) {
+  return {
+    '@theme': themeRoot,
+    '/overrides/styles': path.resolve(projectRoot, resolvedOverridePaths.styles),
+    '/overrides/scripts': path.resolve(projectRoot, resolvedOverridePaths.scripts),
+    '/overrides/features': path.resolve(projectRoot, resolvedOverridePaths.features),
+    ...featureAliases,
+  };
+}
+
+function buildScssConfig({ projectRoot, stylesPath, themeRoot, themeName }) {
+  return {
+    api: 'modern-compiler',
+    includePaths: [
+      path.resolve(projectRoot, 'node_modules'),
+      path.resolve(projectRoot, stylesPath),
+      path.join(themeRoot, 'styles'),
+    ],
+    additionalData: `$theme-name: '${themeName}';\n`,
+  };
+}
+
+function buildOptimizationPlugin(mergedOptimizations, dirs) {
+  let resolvedViteConfig;
+  return {
+    name: 'eleventy-themes-optimization',
+    apply: 'build',
+    configResolved(config) {
+      resolvedViteConfig = config;
+    },
+    async closeBundle() {
+      try {
+        const finalDirs = { ...dirs, output: resolvedViteConfig.build.outDir };
+        await runOptimizations(mergedOptimizations, finalDirs);
+        logger.info('✅ Build optimization complete!\n');
+      } catch (error) {
+        logger.error('\n❌ Build optimization failed!');
+        logger.error(`   ${error.message}\n`);
+        throw error;
+      }
+    },
+  };
+}
+
+function buildPluginsArray({
+  projectRoot,
+  themeName,
+  themeMetadata,
+  codeHighlighting,
+  stylesEntry,
+  scriptsEntry,
+  resolvedOverridePaths,
+  discoveredFeatures,
+  userPlugins,
+  mergedOptimizations,
+  dirs,
+}) {
+  const themePlugins = [
+    themeAutoImportPlugin({
+      projectRoot,
+      themeName,
+      stylesEntry,
+      scriptsEntry,
+      resolvedOverridePaths,
+    }),
+    featureServePlugin({ discoveredFeatures }),
+    // Use the merged (theme.json + user theme.js) codeHighlighting so a user's
+    // prismTheme/diffHighlight override reaches the build; fall back to theme
+    // defaults when no merged config was provided.
+    prismThemePlugin(codeHighlighting ?? themeMetadata.config?.codeHighlighting),
+    ...userPlugins,
+  ];
+
+  if (mergedOptimizations && Object.keys(mergedOptimizations).length > 0) {
+    themePlugins.push(buildOptimizationPlugin(mergedOptimizations, dirs));
+  }
+
+  return themePlugins;
+}
+
+/**
+ * Create Vite configuration for any Eleventy theme.
+ *
+ * Wraps `@eleventy-plugin-themer/build-vite` with theme-specific features:
+ * - Auto-imports theme CSS and JS
+ * - `@theme` alias for imports
+ * - SCSS preprocessor configuration with theme paths
+ *
+ * @param {Object} themeMetadata - Theme metadata from `theme.json`.
+ * @param {Object} options
+ * @param {string} options.projectRoot - Project root path (required).
+ * @param {Object} [options.resolvedOverridePaths] - Resolved override paths.
+ * @param {Array}  [options.plugins] - Additional Vite plugins to append.
+ * @param {Object} [options.optimizations] - Optimization config (purgeCSS, etc.).
+ * @param {Object} [options.dirs] - Eleventy dirs config.
+ * @param {Map}    [options.discoveredFeatures] - Pre-discovered feature map.
+ * @param {...any} [options.viteOptions] - Additional Vite config to deep-merge.
+ * @returns {Object} Vite configuration object.
+ */
+export function createThemeViteConfig(themeMetadata, options = {}) {
+  const {
+    projectRoot,
+    mergedConfig,
+    resolvedOverridePaths = {},
+    plugins = [],
+    optimizations,
+    dirs,
+    discoveredFeatures,
+    ...viteOptions
+  } = options;
+
+  if (!projectRoot) {
+    throw new Error('createThemeViteConfig: projectRoot is required');
+  }
+  if (!themeMetadata || !themeMetadata.name) {
+    throw new Error('createThemeViteConfig: themeMetadata with name is required');
+  }
+
+  const themeName = themeMetadata.name;
+  const themeRoot = getThemeRoot(projectRoot, themeName);
+  const stylesEntry = themeMetadata.assets?.styles?.entry || DEFAULT_ASSET_ENTRIES.styles;
+  const scriptsEntry = themeMetadata.assets?.scripts?.entry || DEFAULT_ASSET_ENTRIES.scripts;
+
+  const featureAliases = buildFeatureAliases(discoveredFeatures);
+  const mergedOptimizations = mergeThemeBuildHints(optimizations, themeMetadata.build);
+
+  const themeConfig = {
+    resolve: {
+      alias: buildResolveAliases({
+        themeRoot,
+        projectRoot,
+        resolvedOverridePaths,
+        featureAliases,
+      }),
+    },
+    css: {
+      preprocessorOptions: {
+        scss: buildScssConfig({
+          projectRoot,
+          stylesPath: resolvedOverridePaths.styles,
+          themeRoot,
+          themeName,
+        }),
+      },
+    },
+    plugins: buildPluginsArray({
+      projectRoot,
+      themeName,
+      themeMetadata,
+      codeHighlighting: mergedConfig?.codeHighlighting,
+      stylesEntry,
+      scriptsEntry,
+      resolvedOverridePaths,
+      discoveredFeatures,
+      userPlugins: plugins,
+      mergedOptimizations,
+      dirs,
+    }),
+  };
+
+  return deepMergeViteConfig(themeConfig, viteOptions);
+}

package/utils/constants.mjs

@@ -0,0 +1,23 @@
+/**
+ * Shared constants for build plugins
+ *
+ * Centralizes glob patterns and asset paths used across multiple plugins.
+ */
+
+/**
+ * Glob pattern generators for build output files
+ */
+export const GLOB_PATTERNS = {
+  html: (outputDir) => `${outputDir}/**/*.html`,
+  css: (outputDir) => `${outputDir}/assets/css/*.css`,
+};
+
+/**
+ * Asset output paths used in rollup configuration and plugins
+ */
+export const ASSET_PATHS = {
+  scripts: 'assets/scripts',
+  css: 'assets/css',
+  fonts: 'assets/fonts',
+  images: 'assets/images',
+};

package/utils/features.mjs

@@ -0,0 +1,98 @@
+/**
+ * Utilities for resolving page-specific features for Vite builds
+ *
+ * Provides entry point discovery for features referenced in page front matter.
+ * Works with any theme that follows the @eleventy-plugin-themer conventions.
+ */
+
+import path from 'path';
+
+import { getAvailableFeatures, resolveResource } from '@eleventy-plugin-themer/core/internal/api';
+import { DEFAULT_ASSET_ENTRIES } from '@eleventy-plugin-themer/core/internal/defaults';
+import { logger } from '@eleventy-plugin-themer/core/logger';
+
+/**
+ * @internal Get feature paths for Vite aliases/serving.
+ *
+ * Used inside build-vite by `theme-config.mjs` and `feature-serve.mjs`. Exported
+ * for adapter authors building custom Vite integrations on top of build-vite,
+ * but not part of the documented public API surface — signature may change
+ * without a major version bump.
+ *
+ * The caller must have already discovered features via `getAvailableFeatures()`
+ * and pass the resulting Map — this avoids redundant filesystem scans during
+ * plugin init.
+ *
+ * @param {Map<string, {path: string}>} discoveredFeatures - Required. Output of `getAvailableFeatures()`.
+ * @returns {Map<string, string>} Map of feature name to absolute file path.
+ */
+export function getFeaturePathsForBuild(discoveredFeatures) {
+  if (!(discoveredFeatures instanceof Map)) {
+    throw new TypeError(
+      'getFeaturePathsForBuild: discoveredFeatures (Map) is required. ' +
+        'Call getAvailableFeatures() once during plugin init and pass the result.',
+    );
+  }
+  const featurePaths = new Map();
+  discoveredFeatures.forEach((info, name) => {
+    featurePaths.set(name, info.path);
+  });
+  return featurePaths;
+}
+
+/**
+ * Get Vite entry points for all features.
+ *
+ * Returns entry points for `main.js` plus all available features (theme + user,
+ * with user overrides taking precedence). Core handles cascade logic via
+ * `themeMetadata`.
+ *
+ * @param {string} projectRoot - Project root path.
+ * @param {Object} themeMetadata - Theme metadata object from `theme.json`.
+ * @param {Object} [opts]
+ * @param {Object} [opts.resolvedOverridePaths] - Pre-resolved override paths.
+ * @param {Map} [opts.discoveredFeatures] - Pre-discovered features. If omitted,
+ *   `getAvailableFeatures()` runs once internally.
+ * @returns {Object} Entry points object for Vite `build.rollupOptions.input`.
+ *
+ * @example
+ * import { getFeatureEntries } from '@eleventy-plugin-themer/build-vite';
+ * import { metadata } from '@eleventy-plugin-themer/theme-base';
+ *
+ * const input = getFeatureEntries(__dirname, metadata);
+ */
+export function getFeatureEntries(projectRoot, themeMetadata, opts = {}) {
+  const { resolvedOverridePaths, discoveredFeatures } = opts;
+  const mainScriptEntry = themeMetadata.assets?.scripts?.entry || DEFAULT_ASSET_ENTRIES.scripts;
+
+  const mainScript = resolveResource({
+    projectRoot,
+    themeName: themeMetadata.name,
+    resolvedOverridePaths,
+    resourceType: 'scripts',
+    filename: path.basename(mainScriptEntry),
+    throwOnMissing: true,
+  });
+
+  const entries = {
+    main: mainScript.path,
+  };
+
+  const features =
+    discoveredFeatures || getAvailableFeatures(projectRoot, themeMetadata, resolvedOverridePaths);
+
+  features.forEach((feature) => {
+    const entryKey = `/${feature.name}.js`;
+    entries[entryKey] = feature.path;
+  });
+
+  if (features.size > 0) {
+    const featureList = Array.from(features.entries())
+      .map(([name, info]) => `${name} (${info.source})`)
+      .join(', ');
+    logger.info(`✨ Discovered features: ${featureList}`);
+    logger.info(`✅ Added ${features.size} feature(s) as Vite entry points`);
+  }
+
+  return entries;
+}

package/utils/file-processor.mjs

@@ -0,0 +1,122 @@
+/**
+ * Generic file processor utility for build optimization plugins
+ *
+ * Provides consistent error handling, logging, and reporting across all plugins.
+ * Follows DRY principle by extracting common file processing patterns.
+ */
+
+import path from 'path';
+
+import { glob } from 'glob';
+import { logger } from '@eleventy-plugin-themer/core/logger';
+
+/**
+ * Process files with consistent error handling and logging
+ *
+ * @param {Object} options - Processing options
+ * @param {string|string[]} options.pattern - Glob pattern(s) for files to process
+ * @param {string} options.outputDir - Output directory (for relative path logging)
+ * @param {Function} options.processor - Async function to process each file
+ *   Signature: async (file) => { message?: string, stats?: object }
+ * @param {string} options.taskName - Name of the task (for logging)
+ * @param {Function} [options.calculateStats] - Optional function to calculate summary stats
+ *   Signature: (results) => { metricName: value, ... }
+ * @param {string} [options.errorTip] - Optional tip to show when errors occur
+ * @returns {Promise<{success: boolean, processed: number, errors: Array}>}
+ *
+ * @example
+ * await processFiles({
+ *   pattern: `./${outputDir}/assets/css/*.css`,
+ *   outputDir,
+ *   taskName: 'PurgeCSS',
+ *   processor: async (file) => {
+ *     // Process the file
+ *     return { message: ' (50% smaller)' };
+ *   },
+ *   calculateStats: (results) => ({
+ *     'total reduction': '45%'
+ *   }),
+ * });
+ */
+export async function processFiles({
+  pattern,
+  outputDir,
+  processor,
+  taskName = 'Processing',
+  calculateStats,
+  errorTip,
+}) {
+  logger.info(`\n📦 ${taskName}...\n`);
+
+  // Find files to process
+  const patterns = Array.isArray(pattern) ? pattern : [pattern];
+  let files = [];
+  for (const p of patterns) {
+    const matches = await glob(p);
+    files = files.concat(matches);
+  }
+
+  // Remove duplicates
+  files = [...new Set(files)];
+
+  if (files.length === 0) {
+    logger.info(`⚠️  ${taskName}: No files found to process`);
+    return { success: true, processed: 0, errors: [] };
+  }
+
+  const results = [];
+  const errors = [];
+
+  // Process each file
+  for (const file of files) {
+    try {
+      const result = await processor(file);
+      results.push({ file, ...(result || {}) });
+
+      const relativePath = path.relative(outputDir, file);
+      const message = result?.message || '';
+      logger.info(`✓ ${relativePath}${message}`);
+    } catch (error) {
+      const relativePath = path.relative(outputDir, file);
+      errors.push({
+        file: relativePath,
+        error: error.message,
+      });
+      logger.error(`✗ ${relativePath}: ${error.message}`);
+    }
+  }
+
+  // Calculate summary statistics
+  let statsStr = '';
+  if (calculateStats && results.length > 0) {
+    const stats = calculateStats(results);
+    if (stats && Object.keys(stats).length > 0) {
+      statsStr =
+        ', ' +
+        Object.entries(stats)
+          .map(([k, v]) => `${k}: ${v}`)
+          .join(', ');
+    }
+  }
+
+  // Log summary
+  logger.info(
+    `\n✓ ${taskName} completed: ${results.length}/${files.length} files${statsStr}${errors.length > 0 ? `, ${errors.length} failed` : ''}\n`,
+  );
+
+  // Report errors
+  if (errors.length > 0) {
+    logger.error(`\n❌ ${taskName} Errors:`);
+    errors.forEach(({ file, error }) => {
+      logger.error(`   ${file}: ${error}`);
+    });
+
+    if (errorTip) {
+      logger.error(`\n💡 Tip: ${errorTip}\n`);
+    }
+
+    throw new Error(`${taskName} failed for ${errors.length} file(s). See errors above.`);
+  }
+
+  return { success: true, processed: results.length, errors: [] };
+}

package/utils/integration-check.mjs

@@ -0,0 +1,146 @@
+/**
+ * Lightweight integration sanity check for build-vite consumers.
+ *
+ * Validates that node, vite, and @11ty/eleventy-plugin-vite are within the
+ * versions declared in build-vite's peerDependencies + engines. Emits a single
+ * banner on success and warnings on mismatch. **Never throws** — every failure
+ * mode (corrupt manifest, unreadable peer package.json) is swallowed to a
+ * single debug-style log so the check can never take down a consumer's build.
+ *
+ * Runs at most once per Node process. The dedupe is intentional: re-init
+ * within the same process (e.g. Eleventy `--serve` config reload) is silent
+ * because the underlying environment hasn't changed. Tests use
+ * `_resetIntegrationCheck()` to opt back in.
+ *
+ * Opt-out at runtime via `options.skipIntegrationCheck = true` (advanced
+ * consumers running a custom build flow).
+ */
+
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import path from 'path';
+import fs from 'fs';
+
+import { logger } from '@eleventy-plugin-themer/core/logger';
+
+const require = createRequire(import.meta.url);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const BUILD_VITE_MANIFEST_PATH = path.resolve(__dirname, '..', 'package.json');
+
+function readBuildViteManifest() {
+  return JSON.parse(fs.readFileSync(BUILD_VITE_MANIFEST_PATH, 'utf8'));
+}
+
+function readPeerVersion(pkgName) {
+  try {
+    return require(`${pkgName}/package.json`).version;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @internal Parse a leading major version from a semver-ish string.
+ * Accepts `7.3.3`, `v7.3.3`, `7.3.3-beta.1`. Returns null on failure.
+ * Anchored regex — no ReDoS.
+ */
+export function _parseMajor(version) {
+  if (typeof version !== 'string') return null;
+  const match = version.match(/^v?(\d+)\./);
+  return match ? Number(match[1]) : null;
+}
+
+/**
+ * @internal Extract major numbers from a peerDependencies range string.
+ * Handles `^M.x.x` and `^M.x.x || ^N.x.x` forms.
+ */
+export function _parseAllowedMajors(range) {
+  if (typeof range !== 'string') return [];
+  return [...range.matchAll(/\^(\d+)\./g)].map((m) => Number(m[1]));
+}
+
+/** @internal */
+export function _checkNode(manifest, nodeVersion = process.versions.node) {
+  const required = manifest.engines?.node;
+  const min = typeof required === 'string' ? Number(required.replace(/[^\d]/g, '')) : null;
+  const actual = _parseMajor(nodeVersion);
+  if (min === null || actual === null) return null;
+  if (actual < min) {
+    return `Node ${nodeVersion} is below the supported floor (>=${min}). Upgrade Node to avoid undefined behaviour.`;
+  }
+  return null;
+}
+
+/** @internal */
+export function _checkPeer(pkgName, manifest, peerLookup = readPeerVersion) {
+  const range = manifest.peerDependencies?.[pkgName];
+  if (!range) return null;
+  const installed = peerLookup(pkgName);
+  if (!installed) {
+    return `Peer dependency \`${pkgName}\` is not installed. Required: ${range}.`;
+  }
+  const allowed = _parseAllowedMajors(range);
+  const actual = _parseMajor(installed);
+  if (allowed.length === 0 || actual === null) return null;
+  if (!allowed.includes(actual)) {
+    return `\`${pkgName}\` ${installed} is outside the supported range (${range}). Behaviour may be unstable.`;
+  }
+  return null;
+}
+
+let alreadyRan = false;
+
+/**
+ * @internal Pure evaluator. Takes injected dependencies; returns
+ * `{ version, warnings }` or `null` if the manifest can't be read.
+ */
+export function _evaluate({
+  manifestReader = readBuildViteManifest,
+  peerLookup = readPeerVersion,
+  nodeVersion = process.versions.node,
+} = {}) {
+  let manifest;
+  try {
+    manifest = manifestReader();
+  } catch {
+    return null;
+  }
+  const warnings = [
+    _checkNode(manifest, nodeVersion),
+    _checkPeer('vite', manifest, peerLookup),
+    _checkPeer('@11ty/eleventy-plugin-vite', manifest, peerLookup),
+  ].filter(Boolean);
+  return { version: manifest.version, warnings };
+}
+
+export function runIntegrationCheck({ silent = false } = {}) {
+  if (alreadyRan) return;
+  try {
+    const result = _evaluate();
+    if (!result) {
+      // Manifest unreadable — dedupe so we don't spam, but don't claim OK.
+      alreadyRan = true;
+      return;
+    }
+    alreadyRan = true;
+    if (silent) return;
+
+    const { version, warnings } = result;
+    if (warnings.length === 0) {
+      logger.info(`[themer/build-vite ${version}] integration check: OK`);
+      return;
+    }
+    logger.warn(`[themer/build-vite ${version}] integration check: ${warnings.length} warning(s)`);
+    for (const w of warnings) logger.warn(`  • ${w}`);
+  } catch {
+    // Should be unreachable — _evaluate handles its own errors. Belt-and-braces
+    // so the docstring's "never throws" promise is genuinely guaranteed.
+    alreadyRan = true;
+  }
+}
+
+/** @internal Test-only: reset the once-per-process dedupe flag. */
+export function _resetIntegrationCheck() {
+  alreadyRan = false;
+}

package/utils/merge-arrays.mjs

@@ -0,0 +1,34 @@
+/**
+ * Tiny helper for merging string arrays from theme defaults and user values.
+ *
+ * Used by `mergeThemeBuildHints` to combine PurgeCSS safelist entries
+ * (`standard`, `deep`, `greedy`). Theme entries always come first so theme
+ * authors can rely on stable ordering for any greedy regex matchers; user
+ * entries are appended; duplicates are removed.
+ */
+
+/**
+ * Concatenate two arrays, theme entries first, deduped (preserves first-seen
+ * order). Tolerates `undefined`/non-array inputs by treating them as empty.
+ *
+ * @param {Array<string>|undefined} themeArr
+ * @param {Array<string>|undefined} userArr
+ * @returns {Array<string>}
+ */
+export function mergeStringArrays(themeArr, userArr) {
+  const theme = Array.isArray(themeArr) ? themeArr : [];
+  const user = Array.isArray(userArr) ? userArr : [];
+  const seen = new Set();
+  const result = [];
+  for (const item of theme) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    result.push(item);
+  }
+  for (const item of user) {
+    if (seen.has(item)) continue;
+    seen.add(item);
+    result.push(item);
+  }
+  return result;
+}