@hypernym/bundler

ESM & TS module bundler.

_{Repository | Package | Releases | Discussions}

npm i -D @hypernym/bundler

Features

• Powered by Rollup
• Allows advanced customization
• Provides a powerful hooking system
• Supports all TS module resolutions
• Exports fully optimized code
• Follows modern practice
• Super easy to use

Quick Start

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

[!NOTE]

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

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

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

2. Specify the bundle's entry points:

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

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

3. Build via command:

npx hyperbundler

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>
• 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>
• 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: (options: BuildEntryOptions, stats: BuildStats) => void | Promise<void>
• 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, plugin3 } from './src/utils/plugins.js'

export default defineConfig({
  hooks: {
    'build:entry:start': async (options, stats) => {
      // adds custom plugins for a specific entry only
      if (options.input?.includes('./src/index.ts')) {
        options.plugins = [
          plugin1(), // adds a custom plugin before the default bundler plugins
          ...options.plugins, // list of default bundler plugins
          plugin2(), // adds a custom plugin after the default bundler plugins
        ]
      }
      // adds custom plugins for a specific types only
      if (options.types?.includes('./src/types.ts')) {
        options.plugins = [
          ...options.plugins, // list of default bundler plugins
          plugin3(), // adds a custom plugin designed to work only with TS declarations
        ]
      }
    },
  },
})

build:entry:end

• Type: (options: BuildEntryOptions, stats: BuildStats) => void | Promise<void>
• 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 (options, stats) => {
      // ...
    },
  },
})

build:end

• Type: (options: Options, stats: BuildStats) => void | Promise<void>
• 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>
• Default: undefined

Called right after bundling is complete.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

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

Options

outDir

• Type: string
• 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)[]
• 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.

IDs and regexps from this option are applied globally to all entries.

Also, it is possible to define externals individually per entry (entry.externals).

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

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

alias

• Type: true
• Default: undefined

Specifies global path alias support.

If true, it enables import prefixes:

• @/*
• ~/*

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  alias: true,
})

After that it can be imported as:

// Imports module from './src/utils/index.js'
import { module } from '@/utils'

// or

// Imports module from './src/utils/index.js'
import { module } from '~/utils'

CLI

Custom Config

Set a custom config path via the CLI command:

npx hyperbundler --config my.config.js

Community

Feel free to ask questions or share new ideas.

Use the official discussions to get involved.

License

Developed in 🇭🇷 Croatia.

Released under the MIT license.

© Hypernym Studio