@hypernym/bundler 0.2.0 → 0.3.1

package/dist/bin/index.mjs

@@ -25,7 +25,7 @@ const externals = [
 ];
 
 const name = "bundler";
-const version = `0.2.0`;
+const version = `0.3.1`;
 
 const cl = console.log;
 const logger = {
@@ -212,13 +212,13 @@ async function build(cwd, options) {
           _format = "cjs";
         const output = entry.output || _output;
         const format = entry.format || _format;
-        const defaultPlugins = [esbuild(plugins?.esbuild)];
+        const _plugins = [esbuild(plugins?.esbuild)];
         if (plugins?.json) {
           const jsonOptions = isObject(plugins.json) ? plugins.json : void 0;
-          defaultPlugins.push(jsonPlugin(jsonOptions));
+          _plugins.push(jsonPlugin(jsonOptions));
         }
         if (plugins?.replace) {
-          defaultPlugins.unshift(
+          _plugins.unshift(
             replacePlugin({
               true: true,
               ...plugins.replace
@@ -227,12 +227,20 @@ async function build(cwd, options) {
         }
         if (plugins?.resolve) {
           const resolveOptions = isObject(plugins.resolve) ? plugins.resolve : void 0;
-          defaultPlugins.unshift(resolvePlugin(resolveOptions));
+          _plugins.unshift(resolvePlugin(resolveOptions));
+        }
+        if (hooks?.["rollup:plugins"]) {
+          hooks["rollup:plugins"](_plugins, {
+            ...entry,
+            input,
+            output,
+            format
+          });
         }
         const builder = await rollup({
           input: resolve(cwd, input),
           external: externals || options.externals,
-          plugins: defaultPlugins,
+          plugins: _plugins,
           onLog: (level, log) => {
             if (logFilter(log))
               buildLogs.push({ level, log });
@@ -263,10 +271,19 @@ async function build(cwd, options) {
           _format = "cjs";
         const output = entry.output || _output;
         const format = entry.format || _format;
+        const _plugins = [dts(plugins?.dts)];
+        if (hooks?.["rollup:plugins"]) {
+          hooks["rollup:plugins"](_plugins, {
+            ...entry,
+            types,
+            output,
+            format
+          });
+        }
         const builder = await rollup({
           input: resolve(cwd, types),
           external: externals || options.externals,
-          plugins: [dts(plugins?.dts)],
+          plugins: _plugins,
           onLog: (level, log) => {
             if (logFilter(log))
               buildLogs.push({ level, log });

package/dist/types/index.d.ts

@@ -1,11 +1,11 @@
-import { OutputOptions, LogLevel, RollupLog } from 'rollup';
+import { OutputOptions, LogLevel, RollupLog, Plugin } from 'rollup';
 import { RollupReplaceOptions } from '@rollup/plugin-replace';
 import { RollupJsonOptions } from '@rollup/plugin-json';
 import { RollupNodeResolveOptions } from '@rollup/plugin-node-resolve';
 import { TransformOptions } from 'esbuild';
 import { Options as Options$1 } from 'rollup-plugin-dts';
 
-interface BuildPlugins {
+interface PluginsOptions {
     esbuild?: TransformOptions;
     dts?: Options$1;
     resolve?: RollupNodeResolveOptions | true;
@@ -13,7 +13,7 @@ interface BuildPlugins {
     replace?: RollupReplaceOptions;
 }
 
-interface Entry {
+interface EntryBase {
     /**
      * Specifies the path of the transformed module.
      *
@@ -56,7 +56,7 @@ interface Entry {
      */
     logFilter?: string[];
 }
-interface EntryInput extends Entry {
+interface EntryInput extends EntryBase {
     /**
      * Specifies the path of the module's build source.
      */
@@ -66,9 +66,9 @@ interface EntryInput extends Entry {
      *
      * @default undefined
      */
-    plugins?: BuildPlugins;
+    plugins?: PluginsOptions;
 }
-interface EntryTypes extends Entry {
+interface EntryTypes extends EntryBase {
     /**
      * Specifies the path of the module's build source that contains only TS definitions.
      */
@@ -78,23 +78,106 @@ interface EntryTypes extends Entry {
      *
      * @default undefined
      */
-    plugins?: Pick<BuildPlugins, 'dts'>;
+    plugins?: Pick<PluginsOptions, 'dts'>;
+}
+type EntryOptions = EntryInput | EntryTypes;
+
+interface Options {
+    /**
+     * Specifies the bundle's entry points.
+     *
+     * It allows you to manually set all build entries and adjust options for each one individually.
+     *
+     * @example
+     *
+     * ```ts
+     * export default defineConfig({
+     *   entries: [
+     *     { input: './src/index.ts' }, // => './dist/index.mjs'
+     *     { types: './src/types.ts' }, // => './dist/types.d.ts'
+     *     // ...
+     *   ]
+     * })
+     * ```
+     */
+    entries: EntryOptions[];
+    /**
+     * Specifies the output directory for production bundle.
+     *
+     * @default 'dist'
+     */
+    outDir?: string;
+    /**
+     * Specifies the module IDs, or regular expressions to match module IDs,
+     * that should remain external to the bundle.
+     *
+     * IDs and regexps from this option are applied globally to all entries.
+     *
+     * Also, it is possible to define externals individually per entry (`entry.externals`).
+     *
+     * @default [/^node:/, /^@types/, /^@rollup/, /^@hypernym/, /^rollup/, ...pkg.dependencies]
+     */
+    externals?: (string | RegExp)[];
+    /**
+     * Provides a powerful hooking system to further expand bundling mode.
+     *
+     * @example
+     *
+     * ```ts
+     * export default defineConfig({
+     *   hooks: {
+     *     'build:end': async (options, buildStats) => {
+     *       // ...
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * @default undefined
+     */
+    hooks?: HooksOptions;
 }
-type EntriesOptions = EntryInput | EntryTypes;
 
 interface BuildLogs {
     level: LogLevel;
     log: RollupLog;
 }
 interface BuildStats {
+    /**
+     * The root path of the project.
+     */
     cwd: string;
+    /**
+     * Final bundle size.
+     */
     size: number;
+    /**
+     * Total bundle build time.
+     */
     buildTime: number;
+    /**
+     * List of generated bundle modules.
+     */
     files: {
+        /**
+         * Module output path.
+         */
         path: string;
+        /**
+         * Module size.
+         */
         size: number;
+        /**
+         * Build time of individual module.
+         */
         buildTime: number;
+        /**
+         * Module format.
+         */
         format: string;
+        /**
+         * List of warnings from build plugins.
+         */
         logs: BuildLogs[];
     }[];
 }
@@ -102,55 +185,128 @@ interface BuildStats {
 interface HooksOptions {
     /**
      * Called just before bundling started.
+     *
+     * @example
+     *
+     * ```ts
+     * export default defineConfig({
+     *   hooks: {
+     *     'bundle:start': async (options) => {
+     *       // ...
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * @default undefined
      */
     'bundle:start'?: (options?: Options) => void | Promise<void>;
     /**
      * Called just before building started.
+     *
+     * @example
+     *
+     * ```ts
+     * export default defineConfig({
+     *   hooks: {
+     *     'build:start': async (options, buildStats) => {
+     *       // ...
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * @default undefined
      */
     'build:start'?: (options?: Options, buildStats?: BuildStats) => void | Promise<void>;
     /**
-     * Called right after building is complete.
-     */
-    'build:end'?: (options?: Options, buildStats?: BuildStats) => void | Promise<void>;
-    /**
-     * Called right after bundling is complete.
-     */
-    'bundle:end'?: (options?: Options) => void | Promise<void>;
-}
-
-interface Options {
-    /**
-     * Specifies the bundle's entry points.
+     * Called just before the initialization of the Rollup plugin.
      *
-     * It allows you to manually set all build entries and adjust options for each one individually.
-     */
-    entries: EntriesOptions[];
-    /**
-     * Specifies the output directory for production bundle.
+     * Provides the ability to add and manipulate custom plugins.
      *
-     * @default 'dist'
+     * @example
+     *
+     * ```ts
+     * import { plugin1, plugin2, plugin3 } from './plugins'
+     *
+     * export default defineConfig({
+     *   hooks: {
+     *     'rollup:plugins': (plugins, entry) => {
+     *       // adds a custom plugin before the default bundler plugins
+     *       plugins.unshift(plugin1())
+     *       // adds a custom plugin after the default bundler plugins
+     *       plugins.push(plugin2())
+     *       // adds a custom plugin for a specific entry only
+     *       if (entry?.input?.includes('./src/index.ts')) {
+     *         plugins.push(plugin3())
+     *       }
+     *       // returns the final list of plugins
+     *       return plugins
+     *     }
+     *   }
+     * })
+     * ```
+     *
+     * @default undefined
      */
-    outDir?: string;
+    'rollup:plugins'?: (plugins: Plugin[], entry?: Partial<EntryInput> & Partial<Omit<EntryTypes, 'plugins'>>) => Plugin[];
     /**
-     * Specifies the module IDs, or regular expressions to match module IDs,
-     * that should remain external to the bundle.
+     * Called right after building is complete.
      *
-     * IDs and regexps from this option are applied globally to all entries.
+     * @example
      *
-     * Also, it is possible to define externals individually per entry (`entry.externals`).
+     * ```ts
+     * export default defineConfig({
+     *   hooks: {
+     *     'build:end': async (options, buildStats) => {
+     *       // ...
+     *     }
+     *   }
+     * })
+     * ```
      *
-     * @default [/^node:/, /^@types/, /^@rollup/, /^@hypernym/, /^rollup/, ...pkg.dependencies]
+     * @default undefined
      */
-    externals?: (string | RegExp)[];
+    'build:end'?: (options?: Options, buildStats?: BuildStats) => void | Promise<void>;
     /**
-     * Provides a powerful hooking system to further expand bundling mode.
+     * Called right after bundling is complete.
+     *
+     * @example
+     *
+     * ```ts
+     * export default defineConfig({
+     *   hooks: {
+     *     'bundle:end': async (options) => {
+     *       // ...
+     *     }
+     *   }
+     * })
+     * ```
      *
      * @default undefined
      */
-    hooks?: HooksOptions;
+    'bundle:end'?: (options?: Options) => void | Promise<void>;
 }
 
+/**
+ * List of global defaults for externals.
+ *
+ * @example
+ *
+ * ```ts
+ * import { externals } from '@hypernym/bundler'
+ *
+ * export default defineConfig({
+ *   entries: [
+ *     {
+ *       input: './src/index.ts',
+ *       externals: [...externals, 'id', /regexp/]
+ *     },
+ *   ]
+ * })
+ * ```
+ */
 declare const externals: RegExp[];
 declare function defineConfig(options: Options): Options;
 
-export { defineConfig, externals };
+export { type BuildLogs, type BuildStats, type EntryBase, type EntryInput, type EntryOptions, type EntryTypes, type HooksOptions, type Options, type PluginsOptions, defineConfig, externals };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypernym/bundler",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "author": "Hypernym Studio",
   "description": "ESM & TS module bundler.",
   "license": "MIT",
@@ -62,9 +62,9 @@
     "@hypernym/utils": "^2.1.0",
     "@rollup/plugin-json": "^6.0.1",
     "@rollup/plugin-node-resolve": "^15.2.3",
-    "@rollup/plugin-replace": "^5.0.3",
-    "esbuild": "^0.19.4",
-    "rollup": "^4.1.1",
+    "@rollup/plugin-replace": "^5.0.4",
+    "esbuild": "^0.19.5",
+    "rollup": "^4.1.4",
     "rollup-plugin-dts": "^6.1.0"
   },
   "devDependencies": {