@hypernym/bundler

Hyperbundler

ESM & TS module bundler.

Repository + Package + Releases + Discussions

pnpm add -D @hypernym/bundler

Hypernym Studio

Features

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

Quick Start

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

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

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

1. 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.mjs',
      minify: true,
    },
    // ...
  ],
})

1. Build via command:

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:

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.

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.

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

Inputs

Default transformation behaviour 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

Declarations

Default transformation behaviour for all dts entries:

• ./srcDir/file.ts resolves to ./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.

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' }, // => './dist/index.mjs'
    { dts: './src/types.ts' }, // => './dist/types.d.mts'
    // ...
  ],
})

Entry Chunk

• Types

Automatically transforms chunks for production.

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  entries: [
    { input: './src/index.ts' }, // => './dist/index.mjs'
  ],
})

Entry Declaration

• Types

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

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

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  entries: [
    { dts: './src/types.ts' }, // => './dist/types.d.mts'
  ],
})

Entry Copy

• Types

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.

// bundler.config.ts

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
      },
    },
  ],
})

Entry Template

• Types

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.

// 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
• 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: { find: string | RegExp; replacement: string; }[]
• Default: undefined

Specifies prefixes that will resolve imports with custom paths.

Enables these alias by default:

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

// bundler.config.ts

import { defineConfig } from '@hypernym/bundler'

export default defineConfig({
  alias: [{ find: /^#/, replacement: resolve('./src') }],
})

Now imports can be used like this:

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

minify

• Type: boolean
• Default: undefined

Specifies the minification for all chunk entries.

// 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>
• 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: (entry: BuildEntryOptions, stats: BuildEntryStats) => 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 } 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
        ]
      }
    },
  },
})

build:entry:end

• Type: (entry: BuildEntryOptions, stats: BuildEntryStats) => 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 (entry, 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) => {
      // ...
    },
  },
})

Utils

resolvePaths

• Type: (options: ResolvePathsOptions[]): (id: string) => string

Resolves external module IDs into custom paths.

import { defineConfig, resolvePaths } 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' },
      ]),
    },
  ],
})

Community

Feel free to ask questions or share new ideas.

Use the official discussions to get involved.

License

Developed in 🇭🇷 Croatia, © Hypernym Studio.

Released under the MIT license.