Registry / devops / rollup-plugin-app-utils

rollup-plugin-app-utils

JSON →
library1.0.6jsnpmunverified

The `rollup-plugin-app-utils` package provides a collection of common build utilities designed for Rollup-based projects. Currently stable at version 1.0.6, it does not specify a strict release cadence but appears to be a mature 1.x release. Its core functionalities include an i18n bundler capable of synchronizing translation keys across multiple locale files using a 'back-filling' mechanism, asset copying, dynamic directory preparation and cleanup, and HTML content injection. A key differentiator is its consolidation of these diverse utilities under a single plugin, with the i18n bundler offering intelligent key management. Developers should be aware that several of its file system operations, such as `copyAssets` and `emptyDirectories`, are synchronous, which can impact build performance on very large projects. The plugin is primarily consumed in `rollup.config.js` files, typically within an ESM context.

npm install rollup-plugin-app-utils
INSTALL
IMPORT
SIG · ROLLUP-PLUGIN-APP-
R
rollup-plugin-app-utils
devopsjavascriptv1.0.6
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Utils
import Utils from 'rollup-plugin-app-utils'
import { i18nBundler, copyAssets } from 'rollup-plugin-app-utils'
The plugin exports a default object named 'Utils' containing all utility functions. Individual functions are not named exports.
i18n.translations
import translations from 'i18n.translations'
import translations from './locales/output.json'
This is a virtual module generated by the i18nBundler plugin. It must be imported exactly as 'i18n.translations' in your application code.
Utils (CommonJS)
const Utils = require('rollup-plugin-app-utils')
For Rollup configuration files that use CommonJS or Node.js scripts outside the Rollup build process.

This quickstart demonstrates how to configure `rollup-plugin-app-utils` in a `rollup.config.js` to use `emptyDirectories` for cleanup and `i18nBundler` for processing and back-filling internationalization strings. It sets up mock locale files to showcase the automatic synchronization of translation keys across languages.

import Utils from 'rollup-plugin-app-utils'; import path from 'path'; import fs from 'fs'; // --- Setup: Create a temporary project structure for the demo --- const projectRoot = path.resolve(__dirname, 'temp-rollup-project'); const localesDir = path.join(projectRoot, 'locales'); const outputDir = path.join(projectRoot, 'dist'); const srcDir = path.join(projectRoot, 'src'); // Ensure a clean slate and create necessary directories Utils.emptyDirectories([projectRoot]); // Clean up previous runs fs.mkdirSync(path.join(localesDir, 'en'), { recursive: true }); fs.mkdirSync(path.join(localesDir, 'es'), { recursive: true }); fs.mkdirSync(srcDir, { recursive: true }); // Create mock locale files fs.writeFileSync(path.join(localesDir, 'en', 'common.json'), JSON.stringify({ "hello": "Hello", "goodbye": "Goodbye from EN", "greeting": "Welcome" }, null, 2)); fs.writeFileSync(path.join(localesDir, 'es', 'common.json'), JSON.stringify({ "hello": "Hola", "spanish_only": "Solo español" }, null, 2)); // 'goodbye' and 'greeting' are missing here, will be back-filled // Create a mock source file that imports translations fs.writeFileSync(path.join(srcDir, 'main.js'), ` import translations from 'i18n.translations'; // Resolved by the plugin console.log('EN Hello:', translations.en.common.hello); console.log('ES Hello:', translations.es.common.hello); console.log('ES Goodbye (should be backfilled from EN):', translations.es.common.goodbye); console.log('ES Greeting (should be backfilled from EN):', translations.es.common.greeting); console.log('ES Spanish Only (should be removed by backfilling):', translations.es.common.spanish_only); // This key should be removed from ES as it's not in EN `); // --- Rollup Configuration --- export default { input: path.join(srcDir, 'main.js'), output: { dir: outputDir, format: 'es', entryFileNames: 'bundle.js', }, plugins: [ // Clean the output directory before starting the build Utils.emptyDirectories([outputDir]), // Process and bundle i18n strings, performing back-filling Utils.i18nBundler({ target: localesDir, baseLanguage: 'en', skipBackFilling: false, // Ensure back-filling happens (add missing, remove orphaned keys) transformer: (lang, data) => data, // Simple passthrough transformer }) ] }; // To run this example: // 1. Save the above code as 'rollup.config.js' in an empty directory. // 2. Run 'npm install --save-dev rollup rollup-plugin-app-utils'. // 3. Execute 'npx rollup -c'. // 4. Inspect the 'temp-rollup-project/dist/bundle.js' and 'temp-rollup-project/locales' for processed output.
Debug
Known issues
gotchaSeveral key utilities like `copyAssets`, `prepareDirectories`, `emptyDirectories`, and `htmlInjector` perform file system operations synchronously. This can block the Node.js event loop during the build process, potentially leading to performance bottlenecks, especially with very large file sets or complex directory structures.
fix
For larger projects, monitor build times and consider the potential performance impact. If synchronous blocking becomes an issue, explore alternative build steps or custom plugins that utilize asynchronous file operations for performance-critical tasks, or consider running these steps in a separate, non-blocking process if feasible.
affects: >=1.0.0
gotchaSetting the `skipBackFilling` option to `true` within the `i18nBundler` configuration will prevent the plugin from automatically synchronizing missing keys and files across your locale folders based on the base language. This can lead to incomplete translations or unexpected behavior if translation files are not meticulously kept in sync manually.
fix
Ensure you understand the implications of `skipBackFilling`. If you need automatic key and file synchronization (adding missing keys/files, removing orphaned keys/files), leave this option as `false` (its default behavior). If you manage translations manually and explicitly want to disable this feature, set it to `true` and implement your own external synchronization strategy.
affects: >=1.0.0
gotchaThe `i18nBundler` expects translation imports in your application code to use the specific virtual module path `'i18n.translations'`. Attempting to import translations via standard relative or absolute file paths (e.g., `import translations from './locales/en/common.json'`) will not work, as the plugin dynamically generates and intercepts this virtual module.
fix
Always use `import translations from 'i18n.translations'` in your application code to access the bundled translations. Ensure the `i18nBundler` plugin is correctly configured and active within your Rollup setup's `plugins` array to handle this virtual module resolution.
affects: >=1.0.0
Errors
Common errors & fixes
[!] Error: Could not resolve 'i18n.translations' from src/main.js (or similar module not found error)
The `i18nBundler` plugin was either not configured correctly in `rollup.config.js`, or it was not placed early enough in the `plugins` array for Rollup to resolve its virtual module before other resolvers ran.
fix
Ensure `Utils.i18nBundler({...})` is correctly included in your `rollup.config.js` `plugins` array. It is often beneficial to place the `i18nBundler` near the beginning of the `plugins` list to ensure its virtual module is resolved before other resolution plugins interfere.
[!] (fs-extra) EACCES: permission denied, copyFile 'source_path' -> 'target_path' (or similar 'EACCES', 'ENOENT' errors during file operations)
The Rollup process (or the user running it) lacks the necessary read/write permissions for the specified source or target directories/files used by `copyAssets`, `emptyDirectories`, or `prepareDirectories` functions.
fix
Verify that the user account running the Rollup build has appropriate read and write permissions for all directories and files involved in the copy, empty, and prepare operations. On Linux/macOS, check file system permissions using `ls -l` and adjust with `chmod` if needed. On Windows, verify folder security settings.
Upgrade
Version history
1.0.6latest on npm
Audit
Dependencies
fs-extrarequiredUsed internally by file system operations like copyAssets, prepareDirectories, and emptyDirectories.
Agent activity
26 hits · last 30 days
node
22
OpenAI (training)
1
Resources
rollup-plugin-app-utils — npm install rollup-plugin-app-utils · libregistry