balm-core 5.2.0 → 6.0.0-alpha.1

package/src/balm.ts

@@ -0,0 +1,108 @@
+import { BalmConfig, BalmCustomConfig, BundlerType } from './types/index.js';
+import { resolveConfig } from './config/index.js';
+import { TaskDAG } from './runner/dag.js';
+import { BalmHooks } from './hooks/index.js';
+import { CleanTask } from './tasks/clean.js';
+import { StyleTask } from './tasks/style.js';
+import { ScriptTask } from './tasks/script.js';
+import { HtmlTask } from './tasks/html.js';
+import { CacheTask } from './tasks/cache.js';
+import { PwaTask } from './tasks/pwa.js';
+import { ServerTask } from './tasks/server.js';
+import { StaticTask } from './tasks/static.js';
+import { logger } from './utilities/logger.js';
+
+export class Balm {
+  private _config: BalmConfig;
+  private dag = new TaskDAG();
+  beforeTask?: () => Promise<void> | void;
+  afterTask?: () => Promise<void> | void;
+  readonly Bundler = BundlerType;
+
+  constructor() {
+    this._config = resolveConfig();
+  }
+
+  get config(): BalmConfig {
+    return this._config;
+  }
+  set config(customConfig: BalmCustomConfig) {
+    this._config = resolveConfig(customConfig);
+    if (this._config.logs?.level !== undefined) {
+      logger.level = this._config.logs.level;
+    }
+  }
+
+  async go(recipe?: (mix: BalmHooks) => void): Promise<void> {
+    const endTimer = logger.time('Build');
+    const taskSequence: string[] = [];
+
+    // Register built-in tasks
+    this.dag.registerTask(new CleanTask());
+    this.dag.registerTask(new StyleTask());
+    this.dag.registerTask(new ScriptTask());
+    this.dag.registerTask(new StaticTask());
+    this.dag.registerTask(new HtmlTask());
+    this.dag.registerTask(new CacheTask());
+    this.dag.registerTask(new PwaTask());
+    this.dag.registerTask(new ServerTask());
+
+    // Run recipe hooks
+    if (typeof recipe === 'function') {
+      const hooks = new BalmHooks(this.dag, this._config);
+      recipe(hooks);
+    }
+
+    try {
+      if (this.beforeTask) {
+        await this.beforeTask();
+      }
+
+      if (this._config.useDefaults) {
+        await this.dag.runSeries(
+          ['clean', 'style', 'script', 'static', 'html'],
+          this._config
+        );
+      }
+
+      // Execute recipe tasks
+      for (let i = 1; ; i++) {
+        const recipeName = `recipe:${i}`;
+        if (!this.dag.hasTask(recipeName)) break;
+        await this.dag.executeTask(recipeName, this._config);
+      }
+
+      // Post-recipe tasks: cache, pwa, serve
+      if (this._config.useDefaults) {
+        if (this._config.env.isProd) {
+          if (this._config.assets.cache) {
+            await this.dag.executeTask('cache', this._config);
+          }
+          if (this._config.pwa.enabled) {
+            await this.dag.executeTask('pwa', this._config);
+          }
+        } else {
+          await this.dag.executeTask('serve', this._config);
+        }
+      }
+
+      if (this.afterTask) {
+        await this.afterTask();
+      }
+
+      endTimer();
+    } catch (err: any) {
+      logger.error('build', `Build failed: ${err?.message || err}`);
+      throw err;
+    }
+  }
+
+  reset(): void {
+    this.dag.clear();
+    this.beforeTask = undefined;
+    this.afterTask = undefined;
+    this._config = resolveConfig();
+  }
+}
+
+export const balm = new Balm();

package/src/bundler/esbuild.ts

@@ -0,0 +1,47 @@
+import * as esbuild from 'esbuild';
+import path from 'node:path';
+import { BalmConfig } from '../types/index.js';
+import { logger } from '../utilities/logger.js';
+
+export async function runEsbuild(
+  config: BalmConfig,
+  customOptions: esbuild.BuildOptions = {}
+): Promise<esbuild.BuildResult> {
+  const isProd = config.env.isProd;
+
+  let entryPoints = customOptions.entryPoints || config.scripts.entry;
+  if (!entryPoints) {
+    entryPoints = [path.join(config.src.js, 'main.js')];
+  }
+
+  const defaultOptions: esbuild.BuildOptions = {
+    entryPoints: (Array.isArray(entryPoints)
+      ? entryPoints
+      : typeof entryPoints === 'string'
+        ? [entryPoints]
+        : entryPoints) as any,
+    absWorkingDir: config.workspace,
+    bundle: true,
+    outdir: config.dest.js,
+    alias: {
+      ...config.alias,
+      ...config.scripts.alias
+    },
+    minify: isProd || config.scripts.minify,
+    sourcemap: !isProd,
+    target:
+      config.scripts.target && config.scripts.target !== 'web'
+        ? (config.scripts.target as string)
+        : 'es2020',
+    format: 'esm',
+    ...config.scripts.esbuildOptions,
+    ...customOptions
+  };
+
+  try {
+    return await esbuild.build(defaultOptions);
+  } catch (err: any) {
+    logger.error('esbuild', err.message || err);
+    throw err;
+  }
+}

package/src/bundler/index.ts

@@ -0,0 +1,3 @@
+export * from './webpack.js';
+export * from './rollup.js';
+export * from './esbuild.js';

package/src/bundler/rollup.ts

@@ -0,0 +1,45 @@
+import { rollup, RollupOptions, OutputOptions } from 'rollup';
+import path from 'node:path';
+import { BalmConfig } from '../types/index.js';
+import { logger } from '../utilities/logger.js';
+
+export async function runRollup(
+  config: BalmConfig,
+  customInputOptions: RollupOptions = {},
+  customOutputOptions: OutputOptions = {}
+): Promise<void> {
+  const isProd = config.env.isProd;
+
+  let input = customInputOptions.input || config.scripts.entry;
+  if (!input) {
+    input = path.join(config.src.js, 'main.js');
+  }
+
+  const inputOptions: RollupOptions = {
+    ...config.scripts.rollupOptions,
+    ...customInputOptions,
+    input: (customInputOptions.input || input) as any
+  };
+
+  const outputOptions: OutputOptions = customOutputOptions.file
+    ? {
+        format: 'es',
+        sourcemap: !isProd,
+        ...customOutputOptions
+      }
+    : {
+        dir: config.dest.js,
+        format: 'es',
+        sourcemap: !isProd,
+        ...customOutputOptions
+      };
+
+  try {
+    const bundle = await rollup(inputOptions);
+    await bundle.write(outputOptions);
+    await bundle.close();
+  } catch (err: any) {
+    logger.error('rollup', err.message || err);
+    throw err;
+  }
+}

package/src/bundler/webpack.ts

@@ -0,0 +1,124 @@
+import webpack, { Configuration } from 'webpack';
+import path from 'node:path';
+import { BalmConfig } from '../types/index.js';
+import { logger } from '../utilities/logger.js';
+
+export async function runWebpack(
+  config: BalmConfig,
+  customOptions: Configuration = {}
+): Promise<webpack.Stats | undefined> {
+  const isProd = config.env.isProd;
+
+  let entry = customOptions.entry || config.scripts.entry;
+  if (!entry) {
+    entry = path.join(config.src.js, 'main.js');
+  }
+
+  const rawOutputPath = customOptions.output?.path;
+  const isCustomOutput = Boolean(rawOutputPath);
+  const outputPath = isCustomOutput
+    ? path.isAbsolute(rawOutputPath as string)
+      ? (rawOutputPath as string)
+      : path.resolve(config.workspace, rawOutputPath as string)
+    : config.dest.base;
+
+  const jsDir = isCustomOutput ? '' : isProd ? config.paths.target.js : config.paths.tmp.js;
+  const imgDir = isProd ? config.paths.target.img : config.paths.tmp.img;
+  const fontDir = isProd ? config.paths.target.font : config.paths.tmp.font;
+
+  const defaultWebpackConfig: Configuration = {
+    mode: isProd ? 'production' : 'development',
+    context: config.workspace,
+    entry,
+    output: {
+      path: outputPath,
+      filename: isCustomOutput
+        ? '[name].js'
+        : isProd && config.assets.cache
+          ? `${jsDir}/[name].[contenthash:8].js`
+          : `${jsDir}/[name].js`,
+      chunkFilename: isCustomOutput
+        ? 'chunk/[name].js'
+        : isProd && config.assets.cache
+          ? `${jsDir}/chunk/[name].[chunkhash:8].js`
+          : `${jsDir}/chunk/[name].js`,
+      publicPath: config.assets.virtualDir ? `/${config.assets.virtualDir}/` : '/',
+      ...(config.scripts.library ? { library: config.scripts.library as any } : {})
+    },
+    target: config.scripts.target || 'web',
+    externals: config.scripts.externals as any,
+    plugins: [
+      ...(config.scripts.plugins || [])
+    ],
+    resolve: {
+      extensions: [
+        '.wasm',
+        '.mjs',
+        '.js',
+        '.jsx',
+        '.ts',
+        '.tsx',
+        '.vue',
+        '.json',
+        ...(config.scripts.extensions || [])
+      ],
+      alias: {
+        ...config.alias,
+        ...config.scripts.alias
+      }
+    },
+    module: {
+      rules: [
+        ...(config.scripts.loaders || []),
+        {
+          test: /\.(png|jpe?g|gif|svg|webp)$/i,
+          type: 'asset/resource',
+          generator: {
+            filename: `${imgDir}/[name].[hash:8][ext]`
+          }
+        },
+        {
+          test: /\.(woff2?|eot|ttf|otf)$/i,
+          type: 'asset/resource',
+          generator: {
+            filename: `${fontDir}/[name].[hash:8][ext]`
+          }
+        }
+      ]
+    },
+    optimization: {
+      minimize: isProd || config.scripts.minify
+    },
+    devtool: isProd ? false : 'eval-cheap-module-source-map'
+  };
+
+  const webpackConfig: Configuration = {
+    ...defaultWebpackConfig,
+    ...config.scripts.webpackOptions,
+    ...customOptions,
+    output: {
+      ...defaultWebpackConfig.output,
+      ...config.scripts.webpackOptions?.output,
+      ...customOptions?.output,
+      path: outputPath
+    }
+  };
+
+  return new Promise((resolve, reject) => {
+    const compiler = webpack(webpackConfig);
+    compiler.run((err, stats) => {
+      if (err) {
+        logger.error('webpack', err.stack || err);
+        return reject(err);
+      }
+
+      if (stats?.hasErrors()) {
+        const info = stats.toJson();
+        logger.error('webpack', info.errors?.map((e) => e.message).join('\n'));
+        return reject(new Error('Webpack compilation errors'));
+      }
+
+      resolve(stats);
+    });
+  });
+}

package/src/config/constants.ts

@@ -0,0 +1,12 @@
+export const ASSETS_TYPES = ['css', 'js', 'img', 'font', 'media'];
+export const PUBLIC_URL = '%PUBLIC_URL%';
+export const CHUNK = { dir: 'chunk' };
+export const ASSET = { dir: 'asset' };
+
+export const ASSET_EXT = {
+  styles: ['css', 'scss', 'sass', 'less'],
+  scripts: ['js', 'mjs', 'cjs', 'ts', 'mts', 'cts', 'jsx', 'tsx'],
+  images: ['png', 'jpg', 'jpeg', 'gif', 'svg', 'webp', 'ico'],
+  fonts: ['woff', 'woff2', 'ttf', 'eot', 'otf'],
+  media: ['mp4', 'webm', 'ogg', 'mp3', 'wav', 'flac', 'aac']
+};

package/src/config/defaults.ts

@@ -0,0 +1,209 @@
+import path from 'node:path';
+import { BalmConfig, BundlerType } from '../types/index.js';
+
+export function createDefaultConfig(workspace = process.cwd()): BalmConfig {
+  const isProd = process.env.NODE_ENV === 'production';
+  const isDev = !isProd;
+  const isTest = process.env.NODE_ENV === 'test';
+
+  const roots = {
+    source: 'src',
+    tmp: '.tmp',
+    target: 'dist'
+  };
+
+  const paths = {
+    source: {
+      base: '',
+      html: '',
+      css: 'styles',
+      js: 'scripts',
+      img: 'images',
+      font: 'fonts',
+      media: 'media'
+    },
+    tmp: {
+      base: '',
+      css: 'css',
+      js: 'js',
+      img: 'img',
+      font: 'fonts',
+      media: 'media'
+    },
+    target: {
+      base: '',
+      css: 'css',
+      js: 'js',
+      img: 'img',
+      font: 'font',
+      media: 'media'
+    }
+  };
+
+  const alias: Record<string, string> = {
+    '@': path.join(workspace, roots.source)
+  };
+
+  const styles = {
+    extname: 'scss',
+    minify: false,
+    atImportPaths: [],
+    alias: {},
+    options: {},
+    sassOptions: {},
+    lessOptions: {},
+    postcssLoaderOptions: {},
+    postcssPlugins: [],
+    sprites: [],
+    spriteOptions: {}
+  };
+
+  const scripts = {
+    bundler: BundlerType.webpack,
+    minify: false,
+    minifyOptions: {},
+    entry: '',
+    target: 'web',
+    library: '',
+    libraryTarget: 'var',
+    externals: {},
+    injectHtml: false,
+    htmlName: 'index.html',
+    alias: {},
+    plugins: [],
+    loaders: [],
+    defaultLoaders: {
+      html: true,
+      css: true,
+      js: true,
+      url: true
+    },
+    options: {},
+    esbuildOptions: {},
+    rollupOptions: {},
+    webpackOptions: {},
+    useCache: false
+  };
+
+  const html = {
+    options: {
+      collapseWhitespace: true,
+      minifyCSS: true,
+      minifyJS: {
+        compress: {
+          drop_console: true
+        }
+      },
+      processConditionalComments: true,
+      removeComments: true,
+      removeEmptyAttributes: true,
+      removeScriptTypeAttributes: true,
+      removeStyleLinkTypeAttributes: true
+    }
+  };
+
+  const assets = {
+    root: 'assets',
+    mainDir: 'public',
+    subDir: '',
+    buildDir: 'build',
+    virtualDir: '',
+    cache: false,
+    options: {
+      fileNameManifest: 'rev-manifest.json',
+      dontRenameFile: ['.html'],
+      dontUpdateReference: []
+    },
+    includes: [],
+    excludes: []
+  };
+
+  const server = {
+    host: null,
+    port: 3000,
+    open: true,
+    proxy: false,
+    proxyOptions: false,
+    historyOptions: false,
+    useHMR: false,
+    options: {}
+  };
+
+  const pwa = {
+    enabled: false,
+    mode: 'generateSW' as const,
+    version: '',
+    manifest: 'manifest.json',
+    swSrcFilename: 'service-worker.js',
+    swDestFilename: 'service-worker.js',
+    options: {}
+  };
+
+  const ftp = {
+    options: {},
+    watchFiles: []
+  };
+
+  const images = {
+    plugins: []
+  };
+
+  const env = {
+    isProd,
+    isDev,
+    isTest,
+    inFrontend: true,
+    inSSR: false,
+    inDesktopApp: false,
+    isMP: false
+  };
+
+  const src = {
+    base: path.join(workspace, roots.source),
+    html: path.join(workspace, roots.source, paths.source.html),
+    css: path.join(workspace, roots.source, paths.source.css),
+    js: path.join(workspace, roots.source, paths.source.js),
+    img: path.join(workspace, roots.source, paths.source.img),
+    font: path.join(workspace, roots.source, paths.source.font),
+    media: path.join(workspace, roots.source, paths.source.media)
+  };
+
+  const targetBase = path.join(workspace, isProd ? roots.target : roots.tmp);
+  const dest = {
+    base: targetBase,
+    html: targetBase,
+    css: path.join(targetBase, isProd ? paths.target.css : paths.tmp.css),
+    js: path.join(targetBase, isProd ? paths.target.js : paths.tmp.js),
+    img: path.join(targetBase, isProd ? paths.target.img : paths.tmp.img),
+    font: path.join(targetBase, isProd ? paths.target.font : paths.tmp.font),
+    media: path.join(targetBase, isProd ? paths.target.media : paths.tmp.media),
+    static: path.join(targetBase, assets.virtualDir, assets.subDir)
+  };
+
+  return {
+    workspace,
+    workspaces: {
+      local: workspace,
+      global: path.resolve(workspace, '..')
+    },
+    alias,
+    env,
+    inFrontend: true,
+    useDefaults: true,
+    roots,
+    paths,
+    styles,
+    scripts,
+    html,
+    assets,
+    server,
+    pwa,
+    ftp,
+    images,
+    logs: {
+      level: 1
+    },
+    src,
+    dest
+  };
+}

package/src/config/index.ts

@@ -0,0 +1,112 @@
+import path from 'node:path';
+import { BalmConfig, BalmCustomConfig } from '../types/index.js';
+import { createDefaultConfig } from './defaults.js';
+import { deepMerge } from '../utilities/utils.js';
+import { ASSETS_TYPES } from './constants.js';
+import { setWorkspaces } from '../utilities/workspace.js';
+
+export function resolveConfig(
+  customConfig: BalmCustomConfig = {},
+  defaultWorkspace = process.cwd()
+): BalmConfig {
+  let localWorkspace = defaultWorkspace;
+  let globalWorkspace = path.resolve(defaultWorkspace, '..');
+
+  if (customConfig.workspace) {
+    if (typeof customConfig.workspace === 'string') {
+      localWorkspace = path.resolve(customConfig.workspace);
+      globalWorkspace = path.resolve(localWorkspace, '..');
+    } else if (typeof customConfig.workspace === 'object') {
+      localWorkspace = path.resolve(customConfig.workspace.local || defaultWorkspace);
+      globalWorkspace = path.resolve(
+        customConfig.workspace.global || path.resolve(localWorkspace, '..')
+      );
+    }
+  }
+
+  setWorkspaces(localWorkspace, globalWorkspace);
+
+  const defaultConfig = createDefaultConfig(localWorkspace);
+  const config = deepMerge(defaultConfig, customConfig) as BalmConfig;
+
+  // Set normalized workspace path
+  config.workspace = localWorkspace;
+  config.workspaces = {
+    local: localWorkspace,
+    global: globalWorkspace
+  };
+
+  // Update src quick directories
+  config.src = {
+    base: path.join(config.workspace, config.roots.source),
+    html: path.join(config.workspace, config.roots.source, config.paths.source.html),
+    css: path.join(config.workspace, config.roots.source, config.paths.source.css),
+    js: path.join(config.workspace, config.roots.source, config.paths.source.js),
+    img: path.join(config.workspace, config.roots.source, config.paths.source.img),
+    font: path.join(config.workspace, config.roots.source, config.paths.source.font),
+    media: path.join(config.workspace, config.roots.source, config.paths.source.media)
+  };
+
+  // Update dest quick directories
+  const targetBase = path.join(
+    config.workspace,
+    config.env.isProd || !config.inFrontend ? config.roots.target : config.roots.tmp
+  );
+
+  const isProd = config.env.isProd || !config.inFrontend;
+  const pathMap = isProd ? config.paths.target : config.paths.tmp;
+
+  const destStatic = path.join(
+    targetBase,
+    config.assets.virtualDir,
+    config.assets.subDir
+  );
+
+  config.dest = {
+    base: targetBase,
+    html: targetBase,
+    css: path.join(targetBase, pathMap.css),
+    js: path.join(targetBase, pathMap.js),
+    img: path.join(targetBase, pathMap.img),
+    font: path.join(targetBase, pathMap.font),
+    media: path.join(targetBase, pathMap.media),
+    static: destStatic
+  };
+
+  // Set assets.static
+  config.assets.static = path.join(
+    config.assets.root,
+    config.assets.mainDir,
+    config.assets.subDir
+  );
+
+  for (const assetType of ASSETS_TYPES) {
+    (config.assets as any)[assetType] = path.join(
+      config.assets.static,
+      (config.paths.target as any)[assetType]
+    );
+  }
+
+  // Set HMR flag
+  const hmrEnv =
+    config.useDefaults &&
+    config.env.isDev &&
+    !config.env.inSSR &&
+    !config.env.isMP;
+  const hmrEnabling = config.scripts.bundler === 'webpack';
+  config.server.useHMR = hmrEnv && hmrEnabling;
+
+  // Set desktop app
+  if (/^electron-.*/.test(config.scripts.target as string)) {
+    config.env.inDesktopApp = true;
+  }
+
+  // Set use cache for webpack
+  config.scripts.useCache =
+    config.env.isProd && config.assets.cache && config.scripts.injectHtml;
+
+  return config;
+}
+
+export * from './constants.js';
+export * from './defaults.js';