@visulima/packem-rollup
API documentation for Packem Rollup plugins and transformers
@visulima/packem-rollup
Rollup plugins and transformer integrations for Packem.
Installation
npm install @visulima/packem-rollupTransformers
esbuild Transformer
import transformer from '@visulima/packem-rollup/transformer/esbuild'Fast JavaScript/TypeScript transformer using esbuild.
swc Transformer
import transformer from '@visulima/packem-rollup/transformer/swc'Rust-powered transformer using swc.
OXC Transformer
import transformer from '@visulima/packem-rollup/transformer/oxc'Next-generation JavaScript toolchain.
sucrase Transformer
import transformer from '@visulima/packem-rollup/transformer/sucrase'Lightweight JavaScript transformer.
TypeScript Transformer
import transformer from '@visulima/packem-rollup/transformer/typescript'Official TypeScript compiler transformer.
Plugins
nativeModulesPlugin
import { nativeModulesPlugin } from '@visulima/packem-rollup'Handles native Node.js addons (.node files) by copying them to the output directory and generating appropriate import statements.
Usage
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
export default defineConfig({
transformer,
rollup: {
nativeModules: {
nativesDirectory: 'natives'
}
}
})Options
interface NativeModulesOptions {
/**
* Custom subdirectory name for native modules within the output directory
* @default 'natives'
*/
nativesDirectory?: string
}See native-modules-plugin API docs for detailed documentation.
require-cjs-transformer
import { requireCJSTransformerPlugin } from '@visulima/packem-rollup'Transform ESM imports of CJS packages to require() calls for better performance.
Usage
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
import { requireCJSTransformerPlugin } from '@visulima/packem-rollup'
export default defineConfig({
transformer,
rollup: {
plugins: [
requireCJSTransformerPlugin({
builtinNodeModules: true
})
]
}
})Options
interface RequireCJSPluginOptions {
builtinNodeModules?: boolean
cwd?: string
additionalPackages?: string[]
exclude?: string[]
include?: string[]
excludePatterns?: string[]
}See require-cjs-transformer API docs for detailed documentation.
minify-html-literals
import { minifyHTMLLiteralsPlugin } from '@visulima/packem-rollup'Automatically minifies HTML and CSS content within template literals during the build process. This plugin identifies tagged template literals containing HTML/CSS and applies minification to reduce bundle size.
:::note
This plugin only runs when minification is enabled in Packem (minify: true in your configuration).
:::
Usage
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem/transformer/esbuild'
export default defineConfig({
transformer,
minify: true, // Required for the plugin to run
rollup: {
minifyHTMLLiterals: {
include: ['**/*.ts', '**/*.js'],
failOnError: false
}
}
})Options
interface MinifyHTMLLiteralsOptions {
/**
* Pattern or array of patterns of files not to minify.
*/
exclude?: FilterPattern;
/**
* If true, any errors while parsing or minifying will abort the bundle
* process. Defaults to false, which will only show a warning.
*/
failOnError?: boolean;
/**
* Pattern or array of patterns of files to minify.
*/
include?: string | string[];
/**
* Override minify-html-literals function.
*/
minifyHTMLLiterals?: typeof minifyHTMLLiterals;
/**
* Minify options, see
* https://www.npmjs.com/package/minify-html-literals#options.
*/
options?: Partial<MinifyHTMLLiteralsOptions>;
}Other Rollup Plugins
Packem includes several other Rollup plugins:
- CSS Processing: Sass, Less, Stylus, PostCSS support
- Asset Handling: Image and font processing
- TypeScript: Declaration file generation
- Optimization: Minification and tree shaking
Utilities
isPureCJS
import { isPureCJS } from '@visulima/packem-rollup'
const result = await isPureCJS('typescript', '/path/to/importer')
console.log(result) // trueDetects if a package is CommonJS-only.
Parameters
- id (
string): Package name or path - importer (
string): Importing file path - rollupResolve (
Function?): Custom resolver function
Returns
Promise<boolean> - True if the package is CJS-only.
Types
PackemRollupOptions
interface PackemRollupOptions {
css?: CssOptions
minifyHTMLLiterals?: MinifyHTMLLiteralsOptions | false
nativeModules?: NativeModulesOptions | false
requireCJS?: RequireCJSPluginOptions | false
plugins?: Plugin[]
// ... other Rollup options
}Configuration options for Rollup in Packem.
NativeModulesOptions
interface NativeModulesOptions {
/**
* Custom subdirectory name for native modules within the output directory
* @default 'natives'
*/
nativesDirectory?: string
}Configuration options for the native modules plugin.
RequireCJSPluginOptions
See require-cjs-transformer API docs.
Examples
Basic Transformer Usage
import { defineConfig } from '@visulima/packem/config'
import esbuildTransformer from '@visulima/packem-rollup/transformer/esbuild'
export default defineConfig({
transformer: esbuildTransformer,
rollup: {
requireCJS: {
builtinNodeModules: true
}
}
})Advanced Plugin Configuration
import { defineConfig } from '@visulima/packem/config'
import transformer from '@visulima/packem-rollup/transformer/swc'
import { requireCJSTransformerPlugin } from '@visulima/packem-rollup'
export default defineConfig({
transformer,
minify: true, // Required for minify-html-literals to run
rollup: {
minifyHTMLLiterals: {
include: ['src/**/*.ts'],
options: {
minifyOptions: {
collapseWhitespace: true,
removeComments: true
}
}
},
plugins: [
requireCJSTransformerPlugin({
builtinNodeModules: true,
additionalPackages: ['my-cjs-lib']
})
]
}
})