@hypernym/bundler 0.14.4 → 0.21.0

package/LICENSE.txt

@@ -1,6 +1,7 @@
 MIT License
 
-Copyright (c) 2025 Ivo Dolenc, Hypernym Studio
+Copyright (c) 2025, Ivo Dolenc <https://github.com/ivodolenc>
+Copyright (c) 2025, Hypernym Studio <https://github.com/hypernym-studio>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -20,11 +20,9 @@
 
 ## Features
 
-- Powered by Rollup
-- Written in TypeScript
+- Powered by Rolldown
 - Allows Advanced Customization
 - Provides a Powerful Hooking System
-- Supports All TS Module Resolutions
 - Exports Fully Optimized Code
 - Follows Modern Practice
 - Super Easy to Use
@@ -67,9 +65,13 @@ export default defineConfig({
 })
 ```
 
-3. Build via command:
+3. Build via commands:
 
 ```sh
+# pnpm
+pnpm hyperbundler
+
+# npm
 npx hyperbundler
 ```
 
@@ -94,37 +96,41 @@ export default defineConfig({
 Set a custom config path via the CLI command:
 
 ```sh
+# pnpm
+pnpm hyperbundler --config hyper.config.ts
+
+# npm
 npx hyperbundler --config hyper.config.ts
 ```
 
 ## Formats
 
-During transformation, file formats are automatically resolved and in most cases there is no need for additional configuration.
+During transformation, file formats are automatically resolved, and in most cases, no additional configuration is required.
 
-`Hyperbundler` module environment for generated files defaults to `esm`, which means the outputs will have a `.mjs` extension unless otherwise specified. For TypeScript declarations, the appropriate extension will be `.d.mts`.
+The default module environment for generated files is `esm`, which means output files will have a `.mjs` extension unless otherwise specified. For TypeScript declarations, the corresponding extension will be `.d.mts`.
 
-Formats can also be explicitly specified for each entry, if necessary.
+Formats can also be explicitly specified for each entry, if needed.
 
 ### Inputs
 
-Default transformation behaviour for all `chunk` entries:
+Default transformation behavior for all `chunk` entries:
 
-- `./srcDir/file.js` resolves to `./outDir/file.mjs`
-- `./srcDir/file.mjs` resolves to `./outDir/file.mjs`
-- `./srcDir/file.cjs` resolves to `./outDir/file.cjs`
-- `./srcDir/file.ts` resolves to `./outDir/file.mjs`
-- `./srcDir/file.mts` resolves to `./outDir/file.mjs`
-- `./srcDir/file.cts` resolves to `./outDir/file.cjs`
+- `./srcDir/file.js` → `./outDir/file.mjs`
+- `./srcDir/file.mjs` → `./outDir/file.mjs`
+- `./srcDir/file.cjs` → `./outDir/file.cjs`
+- `./srcDir/file.ts` → `./outDir/file.mjs`
+- `./srcDir/file.mts` → `./outDir/file.mjs`
+- `./srcDir/file.cts` → `./outDir/file.cjs`
 
 ### Declarations
 
-Default transformation behaviour for all `dts` entries:
+Default transformation behavior for all `dts` entries:
 
-- `./srcDir/file.ts` resolves to `./outDir/file.d.mts`
+- `./srcDir/file.ts` → `./outDir/file.d.mts`
 
 ## Options
 
-All options are documented with descriptions and examples so auto-completion will be offered as you type. Simply hover over the property and see what it does in the `quickinfo`.
+All options come with descriptions and examples. As you type, you’ll get suggestions and can see quick info by hovering over any property.
 
 ### entries
 
@@ -141,16 +147,14 @@ import { defineConfig } from '@hypernym/bundler'
 
 export default defineConfig({
   entries: [
-    { input: './src/index.ts' }, // => './dist/index.mjs'
-    { dts: './src/types.ts' }, // => './dist/types.d.mts'
+    { input: './src/index.ts' }, // outputs './dist/index.mjs'
+    { dts: './src/types.ts' }, // outputs './dist/types.d.mts'
     // ...
   ],
 })
 ```
 
-#### Entry Chunk
-
-- [Types](./src/types/entries.ts)
+### Entry Chunk
 
 Automatically transforms `chunks` for production.
 
@@ -161,48 +165,38 @@ import { defineConfig } from '@hypernym/bundler'
 
 export default defineConfig({
   entries: [
-    { input: './src/index.ts' }, // => './dist/index.mjs'
+    { input: './src/index.ts' }, // outputs './dist/index.mjs'
+    {
+      input: './src/index.ts',
+      output: './out/index.js', // outputs './out/index.js'
+    },
   ],
 })
 ```
 
-#### Entry Declaration
+### Entry Dts
 
-- [Types](./src/types/entries.ts)
-
-Builds TypeScript `declaration` files (.d.ts) for production.
+Builds TypeScript `declaration` files (`.d.mts`) for production.
 
 ```ts
-// bundler.config.ts
-
 import { defineConfig } from '@hypernym/bundler'
 
 export default defineConfig({
   entries: [
-    { declaration: './src/types.ts' }, // => './dist/types.d.mts'
-  ],
-})
-```
-
-Also, it is possible to use `dts` alias.
-
-```ts
-import { defineConfig } from '@hypernym/bundler'
-
-export default defineConfig({
-  entries: [
-    { dts: './src/types.ts' }, // => './dist/types.d.mts'
+    { dts: './src/types.ts' }, // outputs './dist/types.d.mts'
+    {
+      dts: './src/types.ts',
+      output: './out/types.d.ts', // outputs './out/types.d.ts'
+    },
   ],
 })
 ```
 
-#### Entry Copy
+### Entry Copy
 
-- [Types](./src/types/entries.ts)
+Copies either a single `file` or an entire `directory` structure from the source to the destination, including all subdirectories and files.
 
-Copies the single `file` or entire `directory` structure from source to destination, including subdirectories and files.
-
-This can be very useful for copying some assets that don't need a transformation process, but a simple copy paste feature.
+This is especially useful for transferring assets that don't require any transformation, just a straightforward copy-paste operation.
 
 ```ts
 // bundler.config.ts
@@ -212,20 +206,28 @@ import { defineConfig } from '@hypernym/bundler'
 export default defineConfig({
   entries: [
     {
-      copy: {
-        input: './src/path/file.ts', // or ['path-dir', 'path-file.ts', ...]
-        output: './dist/out', // path to output dir
-      },
+      // copies a single file
+      copy: './src/path/file.ts', // outputs './dist/path/file.ts'
+    },
+    {
+      // copies a single file
+      copy: './src/path/file.ts',
+      output: './dist/subdir/custom-file-name.ts',
+    },
+    {
+      // copies the entire directory
+      input: './src/path/srcdir',
+      output: './dist/outdir',
     },
   ],
 })
 ```
 
-#### Entry Template
+### Entry Template
 
-- [Types](./src/types/entries.ts)
+Specifies the content of the `template` file.
 
-Provides the ability to dynamically inject `template` content during the build phase and writes the file to the destination path defined in the output property.
+Provides the ability to dynamically inject template content during the build phase.
 
 ```ts
 // bundler.config.ts
@@ -245,7 +247,7 @@ export default defineConfig({
 
 ### outDir
 
-- Type: `string`
+- Type: `string | undefined`
 - Default: `dist`
 
 Specifies the output directory for production bundle.
@@ -256,20 +258,18 @@ Specifies the output directory for production bundle.
 import { defineConfig } from '@hypernym/bundler'
 
 export default defineConfig({
-  outDir: 'output',
+  outDir: './output',
 })
 ```
 
 ### externals
 
-- Type: `(string | RegExp)[]`
-- Default: `[/^node:/, /^@types/, /^@rollup/, /^@hypernym/, /^rollup/, ...pkg.dependencies]`
-
-Specifies the module IDs, or regular expressions to match module IDs, that should remain external to the bundle.
+- Type: `(string | RegExp)[] | undefined`
+- Default: `[/^node:/, /^@types/, /^@rollup/, /^@rolldown/, /^@hypernym/, /^rollup/, /^rolldown/, ...pkg.dependencies]`
 
-IDs and regexps from this option are applied globally to all entries.
+Specifies the module IDs or regular expressions that match module IDs to be treated as external and excluded from the bundle.
 
-Also, it is possible to define externals individually per entry (`entry.externals`).
+The IDs and regular expressions provided in this option are applied globally across all entries.
 
 ```ts
 // bundler.config.ts
@@ -281,46 +281,30 @@ export default defineConfig({
 })
 ```
 
-### alias
-
-- Type: `{ find: string | RegExp; replacement: string; }[]`
-- Default: `undefined`
-
-Specifies prefixes that will resolve imports with custom paths.
-
-Enables these `alias` by default:
+Alternatively, externals can be defined individually for each entry using the `entry.externals` property.
 
 ```ts
-// Imports module from './src/utils/index.js'
-import { module } from '@/utils' // @
-import { module } from '~/utils' // ~
-```
-
-Also, it is possible to completely override the default aliases by setting custom ones.
-
-```ts
-// bundler.config.ts
-
-import { defineConfig } from '@hypernym/bundler'
-
 export default defineConfig({
-  alias: [{ find: /^#/, replacement: resolve('./src') }],
+  entries: [
+    {
+      input: './src/index.ts',
+      externals: ['id-1', 'id-2', /regexp/],
+    },
+  ],
 })
 ```
 
-Now imports can be used like this:
-
-```ts
-// Imports module from './src/utils/index.js'
-import { module } from '#/utils' // #
-```
-
 ### minify
 
-- Type: `boolean`
+- Type: `boolean | 'dce-only' | MinifyOptions | undefined`
 - Default: `undefined`
 
-Specifies the minification for all `chunk` entries.
+Controls code minification for all `chunk` entries.
+
+- `true`: Enable full minification including code compression and dead code elimination.
+- `false`: Disable minification (default).
+- `'dce-only'`: Only perform dead code elimination without code compression.
+- `MinifyOptions`: Fine-grained control over minification settings.
 
 ```ts
 // bundler.config.ts
@@ -332,7 +316,7 @@ export default defineConfig({
 })
 ```
 
-It can also be set per entry.
+It can also be set per entry:
 
 ```ts
 export default defineConfig({
@@ -360,7 +344,7 @@ List of lifecycle hooks that are called at various phases:
 
 ### bundle:start
 
-- Type: `(options: Options) => void | Promise<void>`
+- Type: `(options: Options) => void | Promise<void> | undefined`
 - Default: `undefined`
 
 Called at the beginning of bundling.
@@ -381,7 +365,7 @@ export default defineConfig({
 
 ### build:start
 
-- Type: `(options: Options, stats: BuildStats) => void | Promise<void>`
+- Type: `(options: Options, stats: BuildStats) => void | Promise<void> | undefined`
 - Default: `undefined`
 
 Called at the beginning of building.
@@ -402,7 +386,7 @@ export default defineConfig({
 
 ### build:entry:start
 
-- Type: `(entry: BuildEntryOptions, stats: BuildEntryStats) => void | Promise<void>`
+- Type: `(entry: BuildEntryOptions, stats: BuildEntryStats) => void | Promise<void> | undefined`
 - Default: `undefined`
 
 Called on each entry just before the build process.
@@ -418,14 +402,7 @@ import { plugin1, plugin2 } from './src/utils/plugins.js'
 export default defineConfig({
   hooks: {
     'build:entry:start': async (entry, stats) => {
-      // adds custom plugins for a specific entry only
-      if (entry.input?.includes('./src/index.ts')) {
-        entry.defaultPlugins = [
-          plugin1(), // adds a custom plugin before the default bundler plugins
-          ...entry.defaultPlugins, // list of default bundler plugins
-          plugin2(), // adds a custom plugin after the default bundler plugins
-        ]
-      }
+      // ...
     },
   },
 })
@@ -433,7 +410,7 @@ export default defineConfig({
 
 ### build:entry:end
 
-- Type: `(entry: BuildEntryOptions, stats: BuildEntryStats) => void | Promise<void>`
+- Type: `(entry: BuildEntryOptions, stats: BuildEntryStats) => void | Promise<void> | undefined`
 - Default: `undefined`
 
 Called on each entry right after the build process is completed.
@@ -454,7 +431,7 @@ export default defineConfig({
 
 ### build:end
 
-- Type: `(options: Options, stats: BuildStats) => void | Promise<void>`
+- Type: `(options: Options, stats: BuildStats) => void | Promise<void> | undefined`
 - Default: `undefined`
 
 Called right after building is complete.
@@ -475,7 +452,7 @@ export default defineConfig({
 
 ### bundle:end
 
-- Type: `(options: Options) => void | Promise<void>`
+- Type: `(options: Options) => void | Promise<void> | undefined`
 - Default: `undefined`
 
 Called right after bundling is complete.
@@ -496,34 +473,92 @@ export default defineConfig({
 
 ## Utils
 
-### resolvePaths
-
-- Type: `(options: ResolvePathsOptions[]): (id: string) => string`
+### externals
 
-Resolves external module IDs into custom paths.
+List of global default patterns for external module identifiers.
 
 ```ts
-import { defineConfig, resolvePaths } from '@hypernym/bundler'
+import { externals } from '@hypernym/bundler'
 
 export default defineConfig({
   entries: [
     {
       input: './src/index.ts',
-      externals: [/^@\/path/],
-      paths: resolvePaths([
-        // replaces `@/path` with `./path/index.mjs`
-        { find: /^@\/path/, replacement: './path/index.mjs' },
-      ]),
+      externals: [...externals, 'id', /regexp/],
     },
   ],
 })
 ```
 
-## Community
+## Plugins
 
-Feel free to ask questions or share new ideas.
+Provides built-in plugins that can be used out of the box and additionally customized as needed.
 
-Use the official [discussions](https://github.com/hypernym-studio/bundler/discussions) to get involved.
+```ts
+import {
+  aliasPlugin,
+  jsonPlugin,
+  replacePlugin,
+  dts,
+  outputPaths,
+  //...
+} from '@hypernym/bundler/plugins'
+```
+
+## Programmatic
+
+### build
+
+- Type: `function build(options: Options): Promise<BuildStats>`
+
+```ts
+import { build } from '@hypernym/bundler'
+
+await build({
+  entries: [{ input: './src/index.ts' }],
+  // ...
+})
+```
+
+## CLI
+
+### config
+
+Specifies the path to the `bundler` custom config file.
+
+```sh
+# pnpm
+pnpm hyperbundler --config hyper.config.mjs
+
+# npm
+npx hyperbundler --config hyper.config.mjs
+```
+
+### cwd
+
+Specifies the path to the project root (current working directory).
+
+```sh
+# pnpm
+pnpm hyperbundler --cwd ./custom-dir
+
+# npm
+npx hyperbundler --cwd ./custom-dir
+```
+
+### tsconfig
+
+Specifies the path to the `tsconfig` file.
+
+By default, if the file `tsconfig.json` exists in the project root, it will be used as the default config file.
+
+```sh
+# pnpm
+pnpm hyperbundler --tsconfig tsconfig.json
+
+# npm
+npx hyperbundler --tsconfig tsconfig.json
+```
 
 ## License