melodist v0.11.1
š¦ melodist
An opinionated bundler for creating TypeScript libraries.
š Installation
With NPM:
npm install -D melodist
With Yarn:
yarn add -D melodist
š Documentation
Making sense of melodist
outputs
melodist
works in tandem with ESBuild and TypeScript to generate production-ready code bundles that are publishable to NPM, along with TypeScript definition files to support strongly-typed integrations by default.
A typical output looks like this:
your_project/
āāā .melodist/
ā
ā # CommonJS modules (with --format=cjs)
āāā cjs/
ā āāā index.js
ā āāā index.js.map
ā āāā [index.css]
ā āāā [index.css.map]
ā
ā # ES modules (with --format=esm)
āāā esm/
ā āāā index.js
ā āāā index.js.map
ā āāā index.mjs
ā āāā index.mjs.map
ā āāā [index.css]
ā āāā [index.css.map]
ā
ā # Immediately-invoked function expression (with --format=iife)
āāā iife/
ā āāā index.js
ā āāā index.js.map
ā āāā [index.css]
ā āāā [index.css.map]
ā
ā # React Native modules (with --format=rn)
āāā rn/
ā āāā index.js
ā āāā index.js.map
ā
ā # TypeScript definitions
āāā types/
āāā *.d.ts
melodist
generates multiple outputs in order to maximize backwards compatibility and interoperability across JS runtimes. These outputs can be associated with entrypoints configured in package.json
:
{
// CommonJS output
"main": "./.melodist/cjs/index.js",
// ES modules output (legacy)
"module": "./.melodist/esm/index.js",
// TypeScript definition
"types": "./.melodist/types/index.d.ts",
// React Native output
"react-native": "./.melodist/rn/index.js",
// CDN entrypoint
"jsdelivr": "./.melodist/iife/index.js",
// You should also define a standard NodeJS
// "exports" field, for maximum compatibility
"exports": {
// ES modules output (using `.mjs` extension)
"import": "./.melodist/esm/index.mjs",
// CommonJS output (for redundancy)
// (this should remain in-sync with package.json#main)
"require": "./.melodist/cjs/index.js"
}
}
Entrypoints
By default, [srcdir]/index.{ext}
is resolved as a starting point for bundling. Values for {ext}
can be one of:
- TypeScript:
ts
ortsx
- JavaScript:
js
orjsx
- CSS:
css
A JavaScript and/or TypeScript entry-point is required for each bundle. CSS is optional.
If [srcdir]
isn't found, or if an entry-point fails to resolve relative to [srcdir]
, then index.{ext}
will be resolved at the project root relative to your package.json
.
For greater flexibility, each delivery format (CommonJS modules, ES modules, IIFE modules, and React Native) can define its own entrypoint using a filename identifier.
- CommonJS:
index.cjs.{ext}
- ES:
index.esm.{ext}
- IIFE:
index.iife.{ext}
- React Native:
index.rn.{ext}
Defining external dependencies
By default, "dependencies"
and "peerDependencies"
listed in package.json
are marked "external" ā meaning those dependencies won't be included in the bundle, only referenced by the relevant module system (import
or require
). These defaults can be extended through the use of --external
flags.
For IIFE bundles, externals can be defined separately using --external:iife
flags, falling back to "dependencies"
, "peerDependencies"
and --external
where necessary.
Defining global Dependencies
Global dependencies can defined through the use of --global
flags. Dependencies marked as global are compiled to a variable reference on a global object. This is handy for situations where external dependencies may be included via <script>
tags in a browser.
For IIFE bundles, globals can be defined separately using --global:iife
flags, falling back to --global
where necessary.
Commands
melodist build
/ melodist dev
melodist build
creates an optimized, production-ready bundle.
melodist dev
serves a hot-reloading development server.
Both commands accept the same positional arguments and flags:
USAGE
$ melodist <build|dev> [options] [<srcdir>]
ARGUMENTS
srcdir Directory where input shall be consumed from. Default: "./src"
OPTIONS
--outdir, -o Directory where output shall be placed. Default: ".melodist"
--outdir:iife, Directory where output shall be placed if --format=iife is in
-o:iife use. Default: falls back to --outdir
--outdir:cjs, Directory where output shall be placed if --format=cjs is in use.
-o:cjs Default: falls back to --outdir
--outdir:esm, Directory where output shall be placed if --format=esm is in use.
-o:esm Default: falls back to --outdir
--outdir:rn, Directory where output shall be placed if --format=rn is in use.
-o:rn Default: falls back to --outdir
--outdir:types, Directory where generated type definitions shall be placed.
-o:types Default: falls back to --outdir
--format, -f A list of output formats that should be produced. Default:
["cjs", "esm"]
--es-target The EcmaScript syntax version to compile to. Default: "esnext"
--platform, -p Target platform (one of: browser, node, neutral). Default:
"neutral"
--external, -e Dependencies to be externalized. Default: inferred from
`dependencies` and `peerDependencies`
--external:iife, Dependencies to be externalized if --format=iife is in use.
-e:iife Default: falls back to --external
--global, -g Dependencies transpiled to global variables (i.e.: --global
react=React).
--global:iife, Dependencies transpiled to global variables if --format=iife is
-g:iife in use (i.e.: --global:iife react=React). Default: falls back to
--global
--name A global variable name to use if --format=iife is in use.
--(no-)sourcemap Generate sourcemaps. Default: true
--env ENV file from which to load environment data.
--tsconfig TSConfig file from which to load TypeScript configuration.
Default: "tsconfig.json"
--(no-)typecheck Whether to validate TypeScript typings at build time. Default:
true
--(no-)minify Whether to optimize bundles through code minification. Default:
true
--help, -h Show help text (you're lookin' at it).
--version, -v Show current version.
25 days ago
9 months ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
1 year ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago
2 years ago