Security News
Python Overtakes JavaScript as Top Programming Language on GitHub
Python becomes GitHub's top language in 2024, driven by AI and data science projects, while AI-powered security tools are gaining adoption.
@visulima/packem
Advanced tools
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.
tsconfig.json
paths and package.json
imports resolutionAnd 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.
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"
}
}
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"
}
}
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:
require
and ESM for import
based on the exports condition..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.
production
and development
exports conditionIf 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.
production
exports condition is defined and the file ends with *.production.*
in the package.json, the bundle will be minified.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.
// 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.
"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" });
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.
require()
in ESMSometimes 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",
},
// ...
});
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.
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
FAQs
A fast and modern bundler for Node.js and TypeScript.
The npm package @visulima/packem receives a total of 675 weekly downloads. As such, @visulima/packem popularity was classified as not popular.
We found that @visulima/packem demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Python becomes GitHub's top language in 2024, driven by AI and data science projects, while AI-powered security tools are gaining adoption.
Security News
Dutch National Police and FBI dismantle Redline and Meta infostealer malware-as-a-service operations in Operation Magnus, seizing servers and source code.
Research
Security News
Socket is tracking a new trend where malicious actors are now exploiting the popularity of LLM research to spread malware through seemingly useful open source packages.