Using with Rollup
Updated on August 22, 2024
Baleada Source Transform's Rollup plugin can be imported from @baleada/rollup-plugin-source-transform.
// rollup.config.js
const sourceTransform = require('@baleada/rollup-plugin-source-transform'),
myTransformFunction = require('path/to/myTransformFunction')
export default {
// ...other options, like input and output
plugins: [
sourceTransform({
transform: myTransformFunction
})
]
}
The sourceTransform plugin's only parameter is an options object. Here's a full breakdown of that object:
transform({ source }) => sourcetransform function can be asynchronous—the plugin will await its results. Read the rest of this article for additional Rollup-specific guidance.testincludeA Picomatch pattern (String) or array of Picomatch patterns that match the files you want to transform.
If include is omitted or of zero length, files will be included by default; otherwise, they will only be included if the ID matches one of the patterns.
excludeA Picomatch pattern (String) or array of Picomatch patterns that match the files you do not want to transform.
context and utils in the transform function's first argument
As mentioned in the Baleada Source Transform overview, your transform function's only parameter is an object that includes various properties. Two of these properties—context and utils—have specific values when used with Rollup.
When using Baleada Source Transform with Rollup, context is the plugin context. utils contains all of the functions from the @rollup/pluginutils package.
transform function return value
In most cases, you'll probably return a String from your transform function, but to learn more about what else you can return (including custom ASTs and sourcemaps), visit the Rollup docs.
Specifying which files get transformed
If you don't pass a test function or any Picomatch patterns to include or exclude, Baleada Source Transform will apply your transform to every file.
This is almost definitely not your desired behavior. Instead, you'll likely want to tell Source Transform to only transform certain files.
In most cases, you can pass a Picomatch pattern (String) or array of Picomatch patterns to include or exclude to specify which files get transformed.
If you need more flexibility than Picomatch patterns offer, you can pass a test function instead of using include and exclude.
The test function receives one argument: an object whose properties and values are outlined below.
| Property | Type | Description | | --- | --- | --- | --- | --- | | source | String | The contents of the file being processed | | id | String | The absolute file path to the file (i.e. starting from the system root, not the root of your project) |
test should return true if the file should be transformed, and false if it shouldn't.
