@hypernym/bundler

ESM & TS module bundler.

Repository ✦ Package ✦ Releases ✦ Discussions

pnpm add -D @hypernym/bundler

Features

Powered by Rolldown
Allows Advanced Customization
Provides a Powerful Hooking System
Exports Fully Optimized Code
Follows Modern Practice
Super Easy to Use
API-Friendly

Quick Start

Create a bundler.config.ts file at the root of your project:

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  // ...
})

Specify the bundle's entry points:

See all options.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  entries: [
    { input: './src/index.ts' },
    { dts: './src/types/index.ts' },
    {
      input: './src/utils/index.ts',
      output: './dist/utils/utils.min.js',
      minify: true,
    },
    // ...
  ],
})

Build via commands:

# pnpm
pnpm hyperbundler

# npm
npx hyperbundler

Config

Hyperbundler automatically detects custom configuration from the project root that can override or extend the build behavior.

Configuration file also accepts .js, .mjs, .ts, .mts formats.

// bundler.config.{js,mjs,ts,mts}

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  // ...
})

Custom path

Set a custom config path via the CLI command:

# 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, no additional configuration is required.

The default module environment for generated files is esm, which means output files will have a .js extension unless otherwise specified. For TypeScript declarations, the corresponding extension will be .d.ts.

Formats can also be explicitly specified for each entry, if needed.

Inputs

Default transformation behavior for all chunk entries:

./srcDir/file.js → ./outDir/file.js
./srcDir/file.mjs → ./outDir/file.js
./srcDir/file.cjs → ./outDir/file.cjs
./srcDir/file.ts → ./outDir/file.js
./srcDir/file.mts → ./outDir/file.js
./srcDir/file.cts → ./outDir/file.cjs

Declarations

Default transformation behavior for all dts entries:

./srcDir/file.ts → ./outDir/file.d.ts

Options

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

Type: EntryOptions[]

Specifies the bundle's entry points.

It allows you to manually set all build entries and adjust options for each one individually.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  entries: [
    { input: './src/index.ts' }, // outputs './dist/index.js'
    { dts: './src/types.ts' }, // outputs './dist/types.d.ts'
    // ...
  ],
})

Entry Chunk

Automatically transforms chunks for production.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  entries: [
    { input: './src/index.ts' }, // outputs './dist/index.js'
    {
      input: './src/index.ts',
      output: './out/index.js', // outputs './out/index.js'
    },
  ],
})

Entry Dts

Builds TypeScript declaration files (.d.ts) for production.

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  entries: [
    { dts: './src/types.ts' }, // outputs './dist/types.d.ts'
    {
      dts: './src/types.ts',
      output: './out/types.d.ts', // outputs './out/types.d.ts'
    },
  ],
})

Entry Copy

Copies either a single file or an entire directory structure from the source to the destination, including all subdirectories and files.

This is especially useful for transferring assets that don't require any transformation, just a straightforward copy-paste operation.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  entries: [
    {
      // 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

Specifies the content of the template file.

Provides the ability to dynamically inject template content during the build phase.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'
import { name, version } from './package.json'

export default defineConfig({
  entries: [
    {
      template: `// Package ${name} v${version} ...`,
      output: './dist/template.ts',
    },
  ],
})

outDir

Type: string | undefined
Default: dist

Specifies the output directory for production bundle.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  outDir: './output',
})

externals

Type: (string | RegExp)[] | undefined
Default: [/^node:/, /^@types/, /^@rollup/, /^@rolldown/, /^@hypernym/, /^rollup/, /^rolldown/, ...pkg.dependencies]

Specifies the module IDs or regular expressions that match module IDs to be treated as external and excluded from the bundle.

The IDs and regular expressions provided in this option are applied globally across all entries.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  externals: ['id-1', 'id-2', /regexp/],
})

Alternatively, externals can be defined individually for each entry using the entry.externals property.

export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      externals: ['id-1', 'id-2', /regexp/],
    },
  ],
})

minify

Type: boolean | 'dce-only' | MinifyOptions | undefined
Default: undefined

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.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  minify: true,
})

It can also be set per entry:

export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      minify: true,
    },
  ],
})

Hooks

List of lifecycle hooks that are called at various phases:

Name	Description
`bundle:start`	Called at the beginning of bundling.
`build:start`	Called at the beginning of building.
`build:entry:start`	Called on each entry just before the build process.
`build:entry:end`	Called on each entry right after the build process is completed.
`build:end`	Called right after building is complete.
`bundle:end`	Called right after bundling is complete.

bundle:start

Type: (options: Options) => void | Promise<void> | undefined
Default: undefined

Called at the beginning of bundling.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  hooks: {
    'bundle:start': async (options) => {
      // ...
    },
  },
})

build:start

Type: (options: Options, stats: BuildStats) => void | Promise<void> | undefined
Default: undefined

Called at the beginning of building.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  hooks: {
    'build:start': async (options, stats) => {
      // ...
    },
  },
})

build:entry:start

Type: (entry: BuildEntryOptions, stats: BuildEntryStats) => void | Promise<void> | undefined
Default: undefined

Called on each entry just before the build process.

Provides the ability to customize entry options before they are passed to the next phase.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'
import { plugin1, plugin2 } from './src/utils/plugins.js'

export default defineConfig({
  hooks: {
    'build:entry:start': async (entry, stats) => {
      // ...
    },
  },
})

build:entry:end

Type: (entry: BuildEntryOptions, stats: BuildEntryStats) => void | Promise<void> | undefined
Default: undefined

Called on each entry right after the build process is completed.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  hooks: {
    'build:entry:end': async (entry, stats) => {
      // ...
    },
  },
})

build:end

Type: (options: Options, stats: BuildStats) => void | Promise<void> | undefined
Default: undefined

Called right after building is complete.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  hooks: {
    'build:end': async (options, stats) => {
      // ...
    },
  },
})

bundle:end

Type: (options: Options) => void | Promise<void> | undefined
Default: undefined

Called right after bundling is complete.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  hooks: {
    'bundle:end': async (options) => {
      // ...
    },
  },
})

Utils

externals

List of global default patterns for external module identifiers.

import { externals } from '@hypernym/bundler'

export default defineConfig({
  entries: [
    {
      input: './src/index.ts',
      externals: [...externals, 'id', /regexp/],
    },
  ],
})

Plugins

Provides built-in plugins that can be used out of the box and additionally customized as needed.

import {
  aliasPlugin,
  jsonPlugin,
  replacePlugin,
  dts,
  outputPaths,
  //...
} from '@hypernym/bundler/plugins'

Programmatic

build

Type: function build(options: Options): Promise<BuildStats>

import { build } from '@hypernym/bundler'

await build({
  entries: [{ input: './src/index.ts' }],
  // ...
})

CLI

config

Specifies the path to the bundler custom config file.

# pnpm
pnpm hyperbundler --config hyper.config.js

# npm
npx hyperbundler --config hyper.config.js

cwd

Specifies the path to the project root (current working directory).

# 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.

# pnpm
pnpm hyperbundler --tsconfig tsconfig.json

# npm
npx hyperbundler --tsconfig tsconfig.json

License

Released under the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 154 Commits
.github		.github
.vscode		.vscode
src		src
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
LICENSE.txt		LICENSE.txt
README.md		README.md
bundler.config.ts		bundler.config.ts
eslint.config.js		eslint.config.js
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
prettier.config.js		prettier.config.js
tsconfig.json		tsconfig.json

Uh oh!

License

hypernym-studio/bundler

Folders and files

Latest commit

History

Repository files navigation

@hypernym/bundler

Features

Quick Start

Config

Custom path

Formats

Inputs

Declarations

Options

entries

Entry Chunk

Entry Dts

Entry Copy

Entry Template

outDir

externals

minify

Hooks

bundle:start

build:start

build:entry:start

build:entry:end

build:end

bundle:end

Utils

externals

Plugins

Programmatic

build

CLI

config

cwd

tsconfig

License

About

Topics

Resources

License

Code of conduct

Uh oh!

Stars

Watchers

Forks

Releases 31

Sponsor this project

Uh oh!

Packages 0

Languages

Packages