A fast and modern bundler for Node.js and TypeScript.
Supports multiple runtimes, shared modules, server components, dynamic import, wasm, css, and more.
Built on top of Rollup, combined with your preferred transformer like esbuild, swc, or sucrase.
Daniel Bannert's open source work is supported by the community on GitHub Sponsors
Visulima Packem
is built on top of Rollup, combined with your preferred transformer like esbuild
, swc
, or sucrase
.
It enables you to generate multiple bundles (CommonJS or ESModule) simultaneously while adhering to Node.js’ native file type support.
It uses the exports
configuration in package.json
and recognizes entry file conventions to match your exports and build them into bundles.
- ✅ package.json#exports, package.json#main, package.json#module to define entry-points
- ✅ package.json#bin to define executables
- ✅ package.json#types to define types
- ✅ Generates package.json#typeVersions to support node 10
- ✅ Dependency externalization
- ✅ Minification
- ✅ TypeScript support + .d.ts bundling
- ✅ Watch mode
- ✅ CLI outputs (auto hashbang insertion)
- ✅ Validates package.json and checks if all fields that are needed to publish your package are configured correctly
- ✅ Supports multiple runtimes (default, react-server, edge-light)
- ✅ Supports react server and client components
- ✅ Supports shared modules
- ✅ Supports dynamic import
- ✅ Supports
tsconfig.json
paths andpackage.json
imports resolution - ✅ ESM ⇄ CJS interoperability
- ✅ Supports isolated declaration types (experimental)
- ✅ Supports wasm WebAssembly modules
- ✅ Supports css, sass, less, stylus and Up-to-date CSS Modules (experimental)
- ✅ TypeDoc documentation generation
And more...
npm install --save-dev @visulima/packem
yarn add -D @visulima/packem
pnpm add -D @visulima/packem
You need to prepare your project to be able to bundle it with packem
.
You can check out the following cases to configure your package.json.
JavaScript
Then use the exports field in package.json to configure different conditions and leverage the same functionality as other bundlers, such as webpack. The exports field allows you to define multiple conditions.
{
"files": ["dist"],
"exports": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs"
},
"scripts": {
"build": "packem build"
}
}
TypeScript
When building a TypeScript library, separate the types from the main entry file by specifying the types
path in package.json
.
When you're using .mjs
or .cjs
extensions with TypeScript and modern module resolution (above node16), TypeScript will require specific type declaration files like .d.mts
or .d.cts
to match the extension. packem
can automatically generate them to match the types to match the condition and extensions.
One example is to configure your exports like this in package.json:
{
"files": ["dist"],
"exports": {
"import": {
"types": "./dist/index.d.mts",
"default": "./dist/index.mjs"
},
"require": {
"types": "./dist/index.d.cts",
"default": "./dist/index.cjs"
}
},
"scripts": {
"build": "packem build"
}
}
Hybrid (CJS & ESM) Module Resolution with TypeScript
If you're using TypeScript with Node 10
and Node 16
module resolution, you can use the types
field in package.json to specify the types path.
Then packem
will generate the types file with the same extension as the main entry file.
{
"files": ["dist"],
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
"import": {
"types": "./dist/index.d.mts",
"default": "./dist/index.mjs"
},
"require": {
"types": "./dist/index.d.cts",
"default": "./dist/index.cjs"
}
},
"scripts": {
"build": "packem build"
}
}
Enable the automatic node 10
typesVersions generation in packem.config.js:
export default defineConfig({
// ...
rollup: {
// ...
node10Compatibility: {
typeScriptVersion: ">=5.0", // Chose the version of TypeScript you want to support
writeToPackageJson: true,
},
// ...
},
transformer,
});
You can validate your package.json exports configuration with are the types wrong cli tool.
Links:
Initialize packem in your project, this will create a packem.config.ts
or packem.config.js
file in the root of your project.
packem init [options]
This command will ask you some questions about your project and create the configuration file.
Run the following command to bundle your files:
packem build [options]
Then files in src
folders will be treated as entry files and match the export names in package.json.
[!NOTE] The
src
folder can be configured in the packem configuration file.
For example: src/index.ts
will match the exports name "."
or the only main export.
Now just run npm run build
or pnpm build
/ yarn build
if you're using these package managers, packem
will find the entry files and build them.
The output format will be based on the exports condition and also the file extension. Given an example:
- It's CommonJS for
require
and ESM forimport
based on the exports condition. - It's CommonJS for
.cjs
and ESM for.mjs
based on the extension regardless the exports condition. Then for export condition like "node" you could choose the format with your extension.
[!NOTE] All the
dependencies
andpeerDependencies
will be marked as external automatically and not included in the bundle. If you want to include them in the bundle, you can use the--no-external
option.
This will write the files into the ./dist
folder.
[!NOTE] The
dist
folder can be configured in the packem configuration file.
For exports condition like react-native
, react-server
and edge-light
as they're special platforms, they could have different exports or different code conditions.
In this case packem
provides an override input source file convention if you want to build them as different code bundle.
For instance:
{
"exports": {
"react-server": "./dist/react-server.mjs",
"edge-light": "./dist/edge-light.mjs",
"import": "./dist/index.mjs"
}
}
[!NOTE] The edge-light export contains a
process.env.EdgeRuntime
variable true, for all other runtimes false is returned.
If you need to separate the production
and development
exports condition, packem
provides process.env.NODE_ENV
injected by default if present that you don't need to manually inject yourself.
- When the
production
exports condition is defined and the file ends with*.production.*
in the package.json, the bundle will be minified. - When the
development
exports condition is defined and the file ends with*.development.*
in the package.json, the bundle will not be minified.
{
"exports": {
"development": "./dist/index.development.mjs",
"production": "./dist/index.production.mjs"
}
}
To build executable files with the bin
field in package.json. The source file matching will be same as the entry files convention.
[!NOTE] >
packem
automatically preserves and prepends the shebang to the executable file, and fix correct permissions for the executable file.
For example:
|- src/
|- bin/
|- index.ts
This will match the bin
field in package.json as:
{
"bin": "./dist/bin/index.cjs"
}
or .mjs
if the type
field is module
in package.json.
{
"type": "module",
"bin": "./dist/bin/index.mjs"
}
For multiple executable files, you can create multiple files.
|- src/
|- bin/
|- foo.ts
|- bar.ts
This will match the bin
field in package.json as:
{
"bin": {
"foo": "./dist/bin/foo.cjs",
"bar": "./dist/bin/bar.cjs"
}
}
packem
supports to build server components and server actions with library directives like "use client"
or "use server"
. It will generate the corresponding chunks for client and server that scope the client and server boundaries properly.
Then when the library is integrated to an app such as Next.js
, app bundler can transform the client components and server actions correctly and maximum the benefits.
If you're using "use client"
or "use server"
in entry file, then it will be preserved on top and the dist file of that entry will become a client component.
If you're using "use client"
or "use server"
in a file that used as a dependency for an entry, then that file containing directives be split into a separate chunk and hoist the directives to the top of the chunk.
There are always cases that you need to share code among bundles, but they don't have to be a separate entry or exports. You want to have them bundled into a shared chunk and then use them in different bundles. You can use shared module convention [name].[layer]-runtime.[ext]
to create shared modules bundles.
Shared Utils Example
// src/util.shared-runtime.js
export function sharedUtil() {
/* ... */
}
Then you can use them in different entry files:
// src/index.js
import { sharedUtil } from "./util.shared-runtime";
// src/lite.js
import { sharedUtil } from "./util.shared-runtime";
packem
will bundle the shared module into a separate layer which matches the file name convention, in the above case it's "shared", and that bundle will be referenced by the different entry bundles.
With multiple runtime bundles, such as having default
and react-server
together. They could have the modules that need to be shared and kept as only one instance among different runtime bundles. You can use the shared module convention to create shared modules bundles for different runtime bundles.
Shared Runtime Module Example
"use client";
// src/app-context.shared-runtime.js
export const AppContext = React.createContext(null);
Then you can use them in different entry files:
// src/index.js
import { AppContext } from "./app-context.shared-runtime";
// src/index.react-server.js
import { AppContext } from "./app-context.shared-runtime";
app-context.shared-runtime
will be bundled into a separate chunk that only has one instance and be shared among different runtime bundles.
packem
supports importing of file as string content, you can name the extension as .txt or .data, and it will be bundled as string content.
// src/index.js
import { text } from "./text.txt";
console.log(text); // "Hello World"
Use the --visualize
flag to generate a packem-bundle-analyze.html
file at build time, showing the makeup of your bundle.
packem
supports building module workers with the --workers
flag, which are a special type of bundle that can be used to run code in a web worker.
worker = new Worker(new URL("./worker.js", import.meta.url), { type: "module" });
// or simply:
worker = new Worker("./worker.js", { type: "module" });
A plugin can additionally specify an enforce property (similar to webpack loaders) to adjust its application order.
The value of enforce
can be either "pre"
or "post"
.
The value of type
can be either "build"
or "dts"
, where "build"
is the default value.
If
dts
is specified, the plugin will only run when declaration files are generated.
The resolved plugins will be in the following order:
- Alias
- User plugins with enforce: 'pre'
- Rollup core plugins
- User plugins without enforce value
- Rollup build plugins
- User plugins with enforce: 'post'
- Rollup post build plugins (minify, manifest, copy, reporting)
import { defineConfig } from "@visulima/packem/config";
import { optimizeLodashImports } from "@optimize-lodash/rollup-plugin";
export default defineConfig({
// ...
plugins: [
{
enforce: "pre",
plugin: optimizeLodashImports(),
// type: "build" -> default value
},
],
// ...
});
Aliases can be configured in the import map, defined in package.json#imports
.
For native Node.js import mapping, all entries must be prefixed with #
to indicate an internal subpath import. Packem
takes advantage of this behavior to define entries that are not prefixed with #
as an alias.
Native Node.js import mapping supports conditional imports (eg. resolving different paths for Node.js and browser), but packem
does not.
⚠️ Aliases are not supported in type declaration generation. If you need type support, do not use aliases.
{
// ...
imports: {
// Mapping '~utils' to './src/utils.js'
"~utils": "./src/utils.js",
// Native Node.js import mapping (can't reference ./src)
"#internal-package": "./vendors/package/index.js",
},
}
Node.js ESM offers interoperability with CommonJS via static analysis. However, not all bundlers compile ESM to CJS syntax in a way that is statically analyzable.
Because packem
uses Rollup, it's able to produce CJS modules that are minimal and interoperable with Node.js ESM.
This means you can technically output in CommonJS to get ESM and CommonJS support.
Sometimes it's useful to use require()
or require.resolve()
in ESM. ESM code that uses require()
can be seamlessly compiled to CommonJS, but when compiling to ESM, Node.js will error because require
doesn't exist in the module scope.
When compiling to ESM, packem
detects require()
usages and shims it with createRequire(import.meta.url)
.
Not only does packem
shim ESM ⇄ CJS
, but fixes the export
and export types
for default
exports in your commonjs files.
To enable both features you need to add cjsInterop: true
to your packem
config.
export default defineConfig({
cjsInterop: true,
// ...
});
Pass in compile-time environment variables with the --env
flag.
This will replace all instances of process.env.NODE_ENV
with 'production'
and remove unused code:
packem build --env.NODE_ENV=production
Packem
validates your package.json
file and checks if all fields are configured correctly, that are needed to publish your package.
[!NOTE] To have a full validation checkup, visit publint and are the types wrong.
To generate api documentation for your project, you need to install typedoc
to your project.
npm exec packem add typedoc
yarn exec packem add typedoc
pnpm exec packem add typedoc
To generate documentation for your project, you can use the --typedoc
flag.
packem build --typedoc
This will generate a api-docs
folder in the root of your project.
You can specify the output format inside the packem.config.js
file.
export default defineConfig({
// ...
typedoc: {
format: "inline",
readmePath: "./README.md",
},
// ...
});
packem
supports:
- PostCSS
- Sass
- Less
- Stylus
- Up-to-date CSS Modules implementation
- URL resolving/rewriting with asset handling
- Ability to use
@import
statements inside regular CSS - Built-in assets handler
- Ability to emit pure CSS for other plugins
- Complete code splitting support, with respect for multiple entries,
preserveModules
andmanualChunks
- Multiple instances support, with check for already processed files
- Proper sourcemaps, with included sources content by default
- Respects
assetFileNames
for CSS file names - Respects sourcemaps from loaded files
- Support for implementation forcing for Sass
- Support for partials and
~
in Less import statements
PostCSS is a tool for transforming styles with JS plugins. These plugins can lint your CSS, add support for variables and mixins, transpile future CSS syntax, inline images, and more.
Install all the necessary dependencies:
npm install --save-dev postcss postcss-load-config postcss-modules postcss-modules-extract-imports postcss-modules-local-by-default postcss-modules-scope postcss-modules-values postcss-value-parser icss-utils
yarn add -D postcss postcss-load-config postcss-modules postcss-modules-extract-imports postcss-modules-local-by-default postcss-modules-scope postcss-modules-values postcss-value-parser icss-utils
pnpm add -D postcss postcss-load-config postcss-modules postcss-modules-extract-imports postcss-modules-local-by-default postcss-modules-scope postcss-modules-values postcss-value-parser icss-utils
Add the loader to your packem.config.ts
:
import { defineConfig } from "@visulima/packem/config";
import transformer from "@visulima/packem/transformer/esbuild";
import postcssLoader from "@visulima/packem/css/loader/postcss";
import sourceMapLoader from "@visulima/packem/css/loader/sourcemap";
export default defineConfig({
transformer,
rollup: {
css: {
loaders: [postcssLoader, sourceMapLoader],
},
},
});
To use Sass, you need to install the sass
package:
npm install --save-dev sass-embedded // recommended
// or
npm install --save-dev sass
// or
npm install --save-dev node-sass
yarn add -D sass-embedded // recommended
// or
yarn add -D sass
// or
yarn add -D node-sass
pnpm add -D sass-embedded // recommended
// or
pnpm add -D sass
// or
pnpm add -D node-sass
Add the loader to your packem.config.ts
:
import { defineConfig } from "@visulima/packem/config";
import transformer from "@visulima/packem/transformer/esbuild";
import postcssLoader from "@visulima/packem/css/loader/postcss";
import sassLoader from "@visulima/packem/css/loader/sass";
import sourceMapLoader from "@visulima/packem/css/loader/sourcemap";
export default defineConfig({
transformer,
rollup: {
css: {
loaders: [postcssLoader, sassLoader, sourceMapLoader],
},
},
});
To use Less, you need to install the less
package:
npm install --save-dev less
yarn add -D less
pnpm add -D less
Add the loader to your packem.config.ts
:
import { defineConfig } from "@visulima/packem/config";
import transformer from "@visulima/packem/transformer/esbuild";
import postcssLoader from "@visulima/packem/css/loader/postcss";
import lessLoader from "@visulima/packem/css/loader/less";
import sourceMapLoader from "@visulima/packem/css/loader/sourcemap";
export default defineConfig({
transformer,
rollup: {
css: {
loaders: [postcssLoader, lessLoader, sourceMapLoader],
},
},
});
To use Stylus, you need to install the stylus
package:
npm install --save-dev stylus
yarn add -D stylus
pnpm add -D stylus
Add the loader to your packem.config.ts
:
import { defineConfig } from "@visulima/packem/config";
import transformer from "@visulima/packem/transformer/esbuild";
import postcssLoader from "@visulima/packem/css/loader/postcss";
import stylusLoader from "@visulima/packem/css/loader/stylus";
import sourceMapLoader from "@visulima/packem/css/loader/sourcemap";
export default defineConfig({
transformer,
rollup: {
css: {
loaders: [postcssLoader, stylusLoader, sourceMapLoader],
},
},
});
After that you can import CSS/Sass/Less/Stylus files in your code:
import "./styles.css";
Default mode is inject
, which means CSS is embedded inside JS and injected into <head>
at runtime, with ability to pass options to CSS injector or even pass your own injector.
CSS is available as default export in inject
and extract
modes, but if CSS Modules are enabled you need to use named css
export.
// Injects CSS, also available as `style` in this example
import style from "./style.css";
// Using named export of CSS string
import { css } from "./style.css";
In emit
mode none of the exports are available as CSS is purely processed and passed along the build pipeline, which is useful if you want to preprocess CSS before using it with CSS consuming plugins, e.g. rollup-plugin-lit-css.
PostCSS configuration files will be found and loaded automatically, but this behavior is configurable using config
option.
/* Import from `node_modules` */
@import "bulma/css/bulma";
/* Local import */
@import "./custom";
/* ...or (if no package named `custom` in `node_modules`) */
@import "custom";
You can prepend the path with ~
to resolve in node_modules
:
// Import from `node_modules`
@import "~bulma/css/bulma";
// Local import
@import "./custom";
// ...or
@import "custom";
Also note that partials are considered first, e.g.
@import "custom";
Will look for _custom
first (with the appropriate extension(s)), and then for custom
if _custom
doesn't exist.
styles({
mode: "inject", // Unnecessary, set by default
// ...or with custom options for injector
mode: ["inject", { container: "body", singleTag: true, prepend: true, attributes: { id: "global" } }],
// ...or with custom injector
mode: ["inject", (varname, id) => `console.log(${varname},${JSON.stringify(id)})`],
});
styles({
mode: "extract",
// ... or with relative to output dir/output file's basedir (but not outside of it)
mode: ["extract", "awesome-bundle.css"],
});
The packem configuration file is a JavaScript file that exports an object with the following properties:
You choose which one of the three supported transformer to use.
You can specify command to be executed after a successful build, specially useful for Watch mode
packem build --watch --onSuccess "node dist/index.js"
onSuccess
can also be a function
that returns Promise
. For this to work, you need to use packem.config.ts
instead of the cli flag:
import { defineConfig } from "@visulima/packem/config";
export default defineConfig({
// ...
async onSuccess() {
// Start some long running task
// Like a server
},
});
You can return a cleanup function in onSuccess
:
import { defineConfig } from "@visulima/packem/config";
export default defineConfig({
// ...
onSuccess() {
const server = http.createServer((req, res) => {
res.end("Hello World!");
});
server.listen(3000);
return () => {
server.close();
};
},
});
- bunchee - Zero config bundler for ECMAScript and TypeScript packages
- unbuild - 📦 An unified javascript build system
- pkgroll - 📦 Zero-config package bundler for Node.js + TypeScript
- siroc - Zero-config build tooling for Node
- tsup - The simplest and fastest way to bundle your TypeScript libraries
- microbundle - Zero-configuration bundler for tiny JS libs, powered by Rollup.
Libraries in this ecosystem make the best effort to track Node.js’ release schedule. Here’s a post on why we think this is important.
If you would like to help take a look at the list of issues and check our Contributing guild.
Note: please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.
The visulima pack is open-sourced software licensed under the MIT