Melodist

0.11.1 verified Sat Apr 25 auth: no javascript

Melodist is an opinionated bundler for creating TypeScript libraries, version 0.11.1. It uses ESBuild and TypeScript to generate multiple output formats (CJS, ESM, IIFE, React Native) for maximum compatibility. It works in tandem with ESBuild and TypeScript, offering automatic externalization of dependencies, global variable definitions for browser usage, and support for CSS entry points. Release cadence is stable but not documented as frequent.

Common errors

error Error: Cannot find module 'melodist' ↓

cause Melodist not installed or not in PATH.

fix

Install as devDependency: npm install -D melodist, then use npx melodist or npm scripts.

error Error: No entry point found. Expected src/index.ts or index.ts. ↓

cause Default entry point not found.

fix

Ensure src/index.ts exists or specify entry with --entry flag or meld.config.js.

error Module not found: Error: Can't resolve 'lodash' ↓

cause Dependency not externalized correctly.

fix

Add --external lodash or ensure lodash is in dependencies in package.json.

error Cannot use import statement outside a module ↓

cause Output file uses ESM imports but runtime expects CommonJS.

fix

Check package.json main vs module fields; use .mjs for ESM exports or set type: module.

Warnings

gotcha Melodist outputs to .melodist/ directory by default; ensure .gitignore includes this. ↓

fix Add .melodist/ to .gitignore

gotcha External dependencies: Only dependencies and peerDependencies are external by default; devDependencies are bundled unless explicitly externalized. ↓

fix Use --external flags for any devDependencies you want to exclude.

deprecated The --cjs, --esm, --iife, --rn flags are deprecated in favor of --format. ↓

fix Use --format=cjs,esm,iife,rn instead.

gotcha If using .mjs output for ESM, ensure your package.json exports field uses .mjs extension. ↓

fix Set "exports": { "import": "./.melodist/esm/index.mjs" }

breaking Melodist v0.10.0 changed default srcdir from lib/ to src/. ↓

fix Either move files to src/ or use --srcdir lib/ flag.

gotcha CSS support is experimental; CSS output may not be minified or optimized. ↓

fix Use a separate CSS build tool if needed.

Install

npm install melodist

yarn add melodist

pnpm add melodist

Imports

melodist
wrong
```
import melodist from 'melodist'
```
correct
```
npx melodist [options]
```
Melodist is a CLI tool, not a library. Use npx or npm scripts to run it.
default (CLI)
wrong
```
npx melodist --format esm --minify
```
correct
```
npx melodist --help
```
Common mistake: not distinguishing between flag style. Use --format not --format=esm? Actually --format=esm is correct. More common mistake: forgetting --external flags.
config file
wrong
```
melodist.config.js
```
correct
```
melodist.config.ts
```
If using TypeScript, the config file should be .ts. Melodist reads melodist.config.ts or melodist.config.js.

Quickstart

Installation, package.json configuration, and basic build command for a TypeScript library.

// First install melodist
// npm install -D melodist

// In package.json, add scripts:
{
  "scripts": {
    "build": "melodist --format esm,cjs",
    "prepublishOnly": "melodist"
  },
  "main": "./.melodist/cjs/index.js",
  "module": "./.melodist/esm/index.js",
  "types": "./.melodist/types/index.d.ts",
  "exports": {
    "import": "./.melodist/esm/index.mjs",
    "require": "./.melodist/cjs/index.js"
  }
}

// Create src/index.ts with your library code
// Run npm run build to generate bundles in .melodist/