mikel-cli 0.34.0 → 0.35.1

package/README.md

@@ -31,10 +31,10 @@ $ mikel <template> [options]
 
 | Option | Short | Description |
 |--------|-------|-------------|
-| `--config <file>` | `-c` | Path to configuration file |
 | `--help` | `-h` | Display help information |
-| `--data <file>` | `-D` | Path to JSON data file |
+| `--config <file>` | `-c` | Path to configuration file |
 | `--output <file>` | `-o` | Output file path |
+| `--data <file>` | `-D` | Path to JSON data file |
 | `--plugin <module>` | `-L` | Load a Mikel plugin from a JavaScript module (can be used multiple times) |
 | `--partial <file>` | `-P` | Register a partial template (supports glob patterns, can be used multiple times) |
 | `--helper <file>` | `-H` | Register helper functions from a JavaScript module (supports glob patterns, can be used multiple times) |
@@ -106,7 +106,7 @@ The `--partial`, `--helper`, and `--function` options support glob patterns for
 
 | Pattern | Description | Example |
 |---------|-------------|---------|
-| `*.ext` | All files with extension in current directory | `*.html`, `*.js` |
+| `*.ext` | All files with extension in current directory | `*.html` |
 | `dir/*.ext` | All files with extension in specific directory | `partials/*.html` |
 | `dir/**/*.ext` | All files with extension in directory and subdirectories | `components/**/*.html` |
 | `?` | Single character wildcard | `file?.html` |
@@ -122,7 +122,7 @@ export default {
     input: "src/**/*.mustache",
     output: {
         dir: "dist/",
-        rename: {
+        nameMapper: {
             "^src/(.+)\\.mustache$": "$1.html",
         },
     },
@@ -155,44 +155,97 @@ input: ["src/index.mustache", "src/pages/**/*.mustache"]
 
 #### `output`
 
-Where to write the rendered files. Accepts a string (directory path) or an object:
+An object containing the options to instruct mikel where and how to save rendered templates.
+
+##### `output.dir`
+
+Output directory to save the rendered templates. If not provided, rendered templates will be saved in the current working directory.
 
 ```js
-// simple directory
-output: "dist/"
-
-// with rename rules
-output: {
-    dir: "dist/",
-    rename: {
-        "^src/(.+)\\.mustache$": "$1.html",
+export default {
+    output: {
+        dir: "dist/",
     },
-}
+    // ...
+};
 ```
 
-The `rename` field works like Jest's `moduleNameMapper` — keys are regular expressions and values are replacement strings. The first matching pattern wins. If no pattern matches, the basename of the input file is used as the output filename.
+##### `output.nameMapper`
+
+An object to map the input file names to the output file names. It works like Jest's `moduleNameMapper` — keys are regular expressions and values are replacement strings. The first matching pattern wins. If no pattern matches, the basename of the input file is used as the output filename.
 
 ```js
-// src/docs/guide/index.mustache → dist/docs/guide/index.html
-rename: {
-    "^src/(.+)\\.mustache$": "$1.html",
-}
+// src/docs/guide/index.mustache -> dist/docs/guide/index.html
+export default {
+    output: {
+        nameMapper: {
+            "^src/(.+)\\.mustache$": "$1.html",
+        },
+    },
+    // ...
+};
 ```
 
 #### `data`
 
-Data to pass to the templates. Accepts a path to a JSON file or a plain object:
+Data to pass to the templates. Accepts a path to a JSON file:
 
 ```js
-// path to JSON file
-data: "./data/site.json"
+export default {
+    data: "./data/site.json",
+    // ...
+};
+```
+
+Or a plain object:
 
-// inline object
-data: {
-    site: {
-        title: "My Site",
+```js
+export default {
+    data: {
+        site: {
+            title: "My Site",
+        },
     },
-}
+    // ...
+};
+```
+
+#### `helpers`
+
+An object containing helpers that will be registered in the mikel engine:
+
+```js
+export default {
+    helpers: {
+        uppercase: ({ fn, data }) => {
+            return fn(data).toUpperCase();
+        },
+    },
+};
+```
+
+#### `functions`
+
+An object containing functions that will be registered in the mikel engine:
+
+```js
+export default {
+    functions: {
+        sayHello: () => "Hello!",
+    },
+};
+```
+
+#### `partials`
+
+An object containing partials that will be registered in the mikel engine:
+
+```js
+export default {
+    partials: {
+        "foo": "Hello {{this.bar}}",
+    },
+};
 ```
 
 #### `plugins`

package/cli.js

@@ -1,306 +1,95 @@
 #!/usr/bin/env node
 
-import fs from "node:fs/promises";
-import { existsSync } from "node:fs";
-import path from "node:path";
 import { parseArgs } from "node:util";
-import mikel from "mikel";
-import { expandGlobPatterns, applyRename } from "./index.js";
-
-// load configuration file
-const loadConfiguration = async (configurationFile) => {
-    if (!configurationFile) {
-        return {};
-    }
-    const configurationPath = path.resolve(process.cwd(), configurationFile);
-    if (!existsSync(configurationPath)) {
-        throw new Error(`Configuration file '${configurationPath}' was not found.`);
-    }
-    // check the extension of the file
-    const configurationExtension = path.extname(configurationFile);
-    if (configurationExtension === ".js") {
-        return await import(configurationPath);
-    }
-    else if (configurationExtension === ".json") {
-        const content = await fs.readFile(configurationPath, "utf8");
-        return JSON.parse(content);
-    }
-    else {
-        throw new Error(`Unknown extension for configuration file '${configurationFile}'`);
-    }
-};
-
-// @description loading input files
-const loadInput = async (inputFiles) => {
-    if (!inputFiles || inputFiles?.length === 0) {
-        throw new Error(`No input templates provided.`);
-    }
-    // expand glob patterns
-    return expandGlobPatterns([inputFiles].flat());
-};
-
-// @description resolve output
-const resolveOutput = (inputFile, outputFile, outputConfig) => {
-    // 1. output file is provided via cli arguments
-    if (outputFile) {
-        return path.resolve(process.cwd(), outputFile);
-    }
-    // 2. output configuration is provided and it is a string
-    else if (outputConfig && typeof outputConfig === "string") {
-        return path.resolve(process.cwd(), path.join(outputConfig, inputFile));
-    }
-    // 3. output configuration is provided and it is an object
-    else if (outputConfig && typeof outputConfig === "object") {
-        const renamedOutputFile = applyRename(inputFile, outputConfig?.rename || {});
-        return path.resolve(process.cwd(), path.join(outputConfig?.dir || ".", renamedOutputFile));
-    }
-    // 4. other case???
-    throw new Error(`Unknown error resolving output for template '${inputFile}'`);
-};
-
-// @description load JSON data from the provided path
-const loadData = async (fileOrObject = null) => {
-    if (!fileOrObject) {
-        return {};
-    }
-    // 1. check for object containing data (from config.data)
-    if (typeof fileOrObject === "object") {
-        return fileOrObject;
-    }
-    // 2. build the full data file path and check if exists
-    const dataPath = path.resolve(process.cwd(), fileOrObject);
-    if (!existsSync(dataPath)) {
-        throw new Error(`Data file '${dataPath}' was not found.`);
-    }
-    // 3. read the file and parse it as JSON
-    try {
-        const content = await fs.readFile(dataPath, "utf8");
-        return JSON.parse(content);
-    } catch (error) {
-        if (error instanceof SyntaxError) {
-            throw new Error(`Invalid JSON in data file '${dataPath}': ${error.message}`);
-        }
-        throw new Error(`Failed to read data file '${dataPath}': ${error.message}`);
-    }
-};
-
-// @description load javascript modules
-const loadModules = async (patterns = [], callback) => {
-    const files = await expandGlobPatterns(patterns);
-    
-    for (let i = 0; i < files.length; i++) {
-        const file = files[i]; // path.resolve(process.cwd(), uniqueFiles[i]);
-        if (!existsSync(file)) {
-            throw new Error(`File '${file}' was not found.`);
-        }
-        
-        // Check if it's a file (not a directory)
-        const stats = await fs.stat(file);
-        if (!stats.isFile()) {
-            continue; // Skip directories
-        }
-        
-        // import the module
-        try {
-            await callback(file);
-        } catch (error) {
-            throw new Error(`Failed to load '${file}': ${error.message}`);
-        }
-    }
-};
+import { build, resolveConfigurationFromArgs } from "./index.js";
 
 // print the help of the tool
 const printHelp = () => {
     console.log("Usage: ");
     console.log("  mikel --help");
     console.log("  mikel <template> [...options]");
+    console.log("  mikel --config <configurationFile> [...options]");
     console.log("");
     console.log("Options:");
     console.log("  -h, --help              Prints the usage information");
+    console.log("  -c, --config <file>     Configuration file to use");
+    console.log("  -o, --output <path>     Output file or directory to save compiled templates");
     console.log("  -P, --partial <file>    Register a partial (supports glob patterns, can be used multiple times)");
     console.log("  -H, --helper <file>     Register a helper (supports glob patterns, can be used multiple times)");
     console.log("  -F, --function <file>   Register a function (supports glob patterns, can be used multiple times)");
     console.log("  -L, --plugin <file>     Load a plugin from node_modules (can be used multiple times)");
     console.log("  -D, --data <file>       Path to the data file to use (JSON)");
-    console.log("  -o, --output <file>     Output file");
     console.log("");
     console.log("Examples:");
     console.log("  mikel template.html --data data.json --output www/index.html");
     console.log("  mikel template.html --data data.json --partial header.html --partial footer.html --output www/index.html");
-    console.log("  mikel template.html --helper helpers.js --function utils.js --output dist/index.html");
-    console.log("  mikel template.html --partial 'partials/*.html' --helper 'helpers/*.js' --output dist/index.html");
     console.log("  mikel template.html --partial 'components/**/*.html' --output dist/index.html");
+    console.log("  mikel template.html --helper helpers.js --function utils.js --output dist/index.html");
+    console.log("  mikel template.html --plugin mikel-markdown --output dist/index.html");
     console.log("");
     process.exit(0);
 };
 
 // @description main function
-const main = async (inputOption = "", options = {}) => {
+const main = async () => {
+    // process arguments
+    const { positionals, values } = parseArgs({
+        options: {
+            config: {
+                type: "string",
+                short: "c",
+            },
+            data: {
+                type: "string",
+                short: "D",
+            },
+            output: {
+                type: "string",
+                short: "o",
+            },
+            partial: {
+                type: "string",
+                short: "P",
+                multiple: true,
+            },
+            plugin: {
+                type: "string",
+                short: "L",
+                multiple: true,
+            },
+            helper: {
+                type: "string",
+                short: "H",
+                multiple: true,
+            },
+            function: {
+                type: "string",
+                short: "F",
+                multiple: true,
+            },
+            help: {
+                type: "boolean",
+                short: "h",
+            },
+        },
+        allowPositionals: true,
+    });
+
     // check to print help
-    if (options.help) {
+    if (values.help) {
         return printHelp();
     }
 
-    // load configuration file and inputs
-    const config = await loadConfiguration(options.config);
-    const inputs = await loadInput(inputOption || config.input || null);
-    const data = await loadData(options.data || config.data || null);
-    const mikelInstance = mikel.create({});
-
-    // if no input files were provided, throw an error and stop processing
-    if (!inputs || inputs?.length === 0) {
-        throw new Error(`No input templates found`);
+    // build with the provided configuration
+    try {
+        const config = await resolveConfigurationFromArgs(process.cwd(), { positionals, values });
+        await build(config);
     }
-    // load plugins
-    const plugins = options.plugin || config.plugins || [];
-    for (let i = 0; i < plugins.length; i++) {
-        const pluginName = Array.isArray(plugins[i]) ? plugins[i][0] : plugins[i];
-        const pluginOptions = Array.isArray(plugins[i]) && plugins[i].length === 2 ? plugins[i][1] : null;
-        let pluginModule;
-        try {
-            // try to import the plugin from node_modules
-            pluginModule = (await import(pluginName))?.default;
-            if (typeof pluginModule !== "function") {
-                throw new Error(`Plugin '${pluginName}' does not export a valid plugin function.`);
-            }
-            mikelInstance.use(pluginModule(pluginOptions));
-        } catch (error) {
-            throw new Error(`Failed to load plugin '${pluginName}': ${error.message}`);
-        }
+    catch (error) {
+        console.error(`\n❌ ${error.message}\n`);
+        process.exit(1);
     }
-
-    // load additional partials, helpers, and functions
-    await loadModules(options.partial, async (file) => {
-        try {
-            mikelInstance.addPartial(path.basename(file), await fs.readFile(file, "utf8"));
-        } catch (error) {
-            throw new Error(`Failed to read partial file '${file}': ${error.message}`);
-        }
-    });
-    await loadModules(options.helper, async (file) => {
-        const extension = path.extname(file);
-        if (extension !== ".js" && extension !== ".mjs") {
-            throw new Error(`Module '${file}' is not supported. Only ESM JavaScript (.js or .mjs) files are supported.`);
-        }
-        // import the module
-        const content = (await import(file)) || {};
-        if (typeof content === "object" && !!content) {
-            Object.keys(content).forEach(helperName => {
-                mikelInstance.addHelper(helperName, content[helperName]);
-            });
-        }
-    });
-    await loadModules(options.function, async (file) => {
-        const extension = path.extname(file);
-        if (extension !== ".js" && extension !== ".mjs") {
-            throw new Error(`Module '${file}' is not supported. Only ESM JavaScript (.js or .mjs) files are supported.`);
-        }
-        // import the module
-        const content = (await import(file)) || {};
-        if (typeof content === "object" && !!content) {
-            Object.keys(content).forEach(functionName => {
-                mikelInstance.addFunction(functionName, content[functionName]);
-            });
-        }
-    });
-    // process input files
-    for (let i = 0; i < inputs.length; i++) {
-        // const inputPath = path.resolve(process.cwd(), inputs[i]);
-        const inputPath = inputs[i]; // inputs contains absolute paths already
-        const relativeInputPath = path.relative(process.cwd(), inputPath);
-        if (!existsSync(inputPath)) {
-            throw new Error(`Template file '${inputPath}' was not found.`);
-        }
-        let template;
-        try {
-            template = await fs.readFile(inputPath, "utf8");
-        } catch (error) {
-            throw new Error(`Failed to read template file '${inputPath}': ${error.message}`);
-        }
-        // compile the template
-        let result;
-        try {
-            result = mikelInstance(template, data);
-        } catch (error) {
-            throw new Error(`Template compilation failed: ${error.message}`);
-        }
-        // check if output argument has been provided to write the result to a file
-        // this will also create any intermediary directory that does not exist
-        if (options.output || config.output) {
-            const outputPath = resolveOutput(relativeInputPath, options.output, config.output);
-            const outputDirectory = path.dirname(outputPath);
-            // make sure that any directory containing the output file exists
-            if (!existsSync(outputDirectory)) {
-                try {
-                    await fs.mkdir(outputDirectory, { recursive: true });
-                } catch (error) {
-                    throw new Error(`Failed to create output directory '${outputDirectory}': ${error.message}`);
-                }
-            }
-            try {
-                await fs.writeFile(outputPath, result, "utf8");
-                console.error(`✓ Saving '${inputPath}' -> '${outputPath}'`);
-            } catch (error) {
-                throw new Error(`Failed to write output file '${outputPath}': ${error.message}`);
-            }
-        }
-        // if no output file has been provided, print the result to console
-        else if (inputs.length === 1) {
-            process.stdout.write(result);
-        }
-        else {
-            throw new Error(`Unconsistent usage of input and output arguments.`);
-        }
-    }
-    // exit
     process.exit(0);
 };
 
-// process arguments
-const { positionals, values } = parseArgs({
-    options: {
-        config: {
-            type: "string",
-            short: "c",
-        },
-        data: {
-            type: "string",
-            short: "D",
-        },
-        output: {
-            type: "string",
-            short: "o",
-        },
-        helper: {
-            type: "string",
-            short: "H",
-            multiple: true,
-        },
-        function: {
-            type: "string",
-            short: "F",
-            multiple: true,
-        },
-        partial: {
-            type: "string",
-            short: "P",
-            multiple: true,
-        },
-        plugin: {
-            type: "string",
-            short: "L",
-            multiple: true,
-        },
-        help: {
-            type: "boolean",
-            short: "h",
-        },
-    },
-    allowPositionals: true,
-});
-
-// run main script
-main(positionals[0], values).catch(error => {
-    console.error(`\n❌ Error: ${error.message}\n`);
-    process.exit(1);
-});
+main()

package/index.d.ts

@@ -0,0 +1,19 @@
+import type { MikelHelper, MikelFunction, MikelPartial, MikelPlugin } from "mikel";
+
+export type MikelCliPlugin = string | [string, ...any] | MikelPlugin;
+
+export type MikelCliConfig = {
+    context?: string;
+    input?: string | string[];
+    output?: string | {
+        dir?: string;
+        nameMapper?: Record<string, string>;
+    };
+    partials?: Record<string, string | MikelPartial>;
+    helpers?: Record<string, MikelHelper>;
+    functions?: Record<string, MikelFunction>;
+    plugins?: MikelCliPlugin[];
+};
+
+export declare const defineConfig: (config: MikelCliConfig) => MikelCliConfig;
+export declare const build: (config: MikelCliConfig) => Promise<void>;

package/index.js

@@ -1,43 +1,249 @@
 import fs from "node:fs/promises";
+import { existsSync } from "node:fs";
 import path from "node:path";
+import mikel from "mikel";
 
 // @description get the files that matches the provided patterns
 // this is a utility function to expand glob patterns to actual file paths.
 // it uses Node.js 24+ built-in fs.glob to handle glob patterns.
-export const expandGlobPatterns = async (patterns = []) => {
+export const expandGlobPatterns = async (root, patterns = []) => {
     const files = [];
-    for (let i = 0; i < patterns.length; i++) {
-        const pattern = patterns[i];
+    for (const pattern of patterns) {
         if (pattern.includes("*") || pattern.includes("?") || pattern.includes("[")) {
-            try {
-                // use Node.js 24+ built-in fs.glob
-                // https://nodejs.org/api/fs.html#fspromisesglobpattern-options
-                for await (const file of fs.glob(pattern, { cwd: process.cwd() })) {
-                    files.push(file);
-                }
-            } catch (error) {
-                files.push(pattern);
+            // use Node.js 24+ built-in fs.glob
+            // https://nodejs.org/api/fs.html#fspromisesglobpattern-options
+            for await (const file of fs.glob(pattern, { cwd: root })) {
+                files.push(file);
             }
         } else {
             files.push(pattern);
         }
     }
-    // remove duplicates and resolve to absolute paths
-    return Array.from(new Set(files)).map(file => {
-        return path.resolve(process.cwd(), file);
-    });
+    // remove duplicates
+    return Array.from(new Set(files));
 };
 
 // @description apply a rename to the provided file path based on a rename configuration
 // object
-export const applyRename = (filePath, rename = {}) => {
-    const patterns = Object.keys(rename);
-    for (let i = 0; i < patterns.length; i++) {
-        const regex = new RegExp(patterns[i]);
-        if (regex.test(filePath)) {
-            return filePath.replace(regex, rename[patterns[i]]);
+export const applyNameMapping = (file, mapping = {}) => {
+    for (const pattern of Object.keys(mapping)) {
+        const regex = new RegExp(pattern);
+        if (regex.test(file)) {
+            return file.replace(regex, mapping[pattern]);
         }
     }
     // fallback: only returns the basename of the file
-    return path.basename(filePath);
+    return path.basename(file);
+};
+
+// @description load configuration file from the provided path
+export const loadConfiguration = async (configurationFile) => {
+    if (!configurationFile) {
+        return {};
+    }
+    const configurationPath = path.resolve(process.cwd(), configurationFile);
+    if (!existsSync(configurationPath)) {
+        throw new Error(`Configuration file '${configurationPath}' was not found.`);
+    }
+    // check the extension of the file
+    const configurationExtension = path.extname(configurationFile);
+    if (configurationExtension === ".js" || configurationExtension === ".mjs") {
+        return (await import(configurationPath)).default;
+    }
+    else if (configurationExtension === ".json") {
+        return JSON.parse(await fs.readFile(configurationPath, "utf8"));
+    }
+    // invalid configuration extension
+    throw new Error(`Unknown extension for configuration file '${configurationFile}'`);
+};
+
+// @description get the files that matches the provided input files patterns
+export const loadInputFiles = async (root, inputFiles) => {
+    if (!inputFiles || inputFiles?.length === 0) {
+        throw new Error(`No input templates provided.`);
+    }
+    return expandGlobPatterns(root, Array.isArray(inputFiles) ? inputFiles : [inputFiles]);
+};
+
+// @description resolve output
+export const resolveOutput = (root, file, output) => {
+    // 1. the provided output is an string
+    if (!!output && typeof output === "string") {
+        // directory if ends with /, otherwise treat as output file
+        return path.resolve(root, output.endsWith("/") ? path.join(output, file) : output);
+    }
+    // 2. output configuration is provided as an object
+    else if (!!output && typeof output === "object") {
+        const renamedOutputFile = applyNameMapping(file, output?.nameMapping || {});
+        return path.resolve(root, path.join(output?.dir || ".", renamedOutputFile));
+    }
+    // 3. other case???
+    throw new Error(`Unknown error resolving output for template '${file}'`);
+};
+
+// @description load JSON data from the provided path
+export const loadData = async (root, fileOrObject = null) => {
+    if (!fileOrObject) {
+        return {};
+    }
+    // 1. check for object containing data (from config.data)
+    if (typeof fileOrObject === "object") {
+        return fileOrObject;
+    }
+    // 2. build the full data file path and check if exists
+    const dataPath = path.resolve(root, fileOrObject);
+    if (!existsSync(dataPath)) {
+        throw new Error(`Data file '${dataPath}' was not found.`);
+    }
+    // 3. read the file and parse it as JSON
+    try {
+        return JSON.parse(await fs.readFile(dataPath, "utf8"));
+    } catch (error) {
+        if (error instanceof SyntaxError) {
+            throw new Error(`Invalid JSON in data file '${dataPath}': ${error.message}`);
+        }
+        throw new Error(`Failed to read data file '${dataPath}': ${error.message}`);
+    }
 };
+
+// @description load partials
+const loadPartials = async (root, patterns = []) => {
+    const files = await expandGlobPatterns(root, [patterns].flat());
+    const partials = {};
+    for (const file of files) {
+        try {
+            partials[path.basename(file)] = await fs.readFile(path.resolve(root, file), "utf8");
+        } catch (error) {
+            throw new Error(`Failed to read partial file '${file}': ${error.message}`);
+        }
+    }
+    return partials;
+};
+
+// @description load javascript modules from the specified patterns
+const loadModules = async (root, patterns = []) => {
+    const files = await expandGlobPatterns(root, [patterns].flat());
+    const loadedModules = {};
+    for (const file of files) {
+        const filePath = path.resolve(root, file);
+        //only javascript modules are supported, so we have to check the extension of the file
+        const extension = path.extname(filePath);
+        if (extension !== ".js" && extension !== ".mjs") {
+            throw new Error(`Module '${filePath}' is not supported. Only ESM JavaScript (.js or .mjs) files are supported.`);
+        }
+        // import the module and call the register method
+        const module = await import(filePath);
+        for (const [name, fn] of Object.entries(module)) {
+            if (typeof fn === "function") {
+                loadedModules[name] = fn;
+            }
+        }
+    }
+    return loadedModules;
+};
+
+// @description build a configuration object from CLI arguments
+export const resolveConfigurationFromArgs = async (root = process.cwd(), args = {}) => {
+    const config = await loadConfiguration(args?.values?.config);
+
+    // resolve partials, helpers and functions from cli arguments
+    const partials = await loadPartials(root, args?.values?.partial || []);
+    const helpers = await loadModules(root, args?.values?.helper || []);
+    const functions = await loadModules(root, args?.values?.function || []);
+
+    // return parsed configuration object
+    return {
+        context: config.context || root,
+        input: (!!args?.positionals && Array.isArray(args?.positionals) && args.positionals.length > 0) ? args.positionals : config.input,
+        output: args?.values?.output || config.output,
+        data: args?.values?.data || config.data,
+        partials: Object.assign(config.partials || {}, partials),
+        helpers: Object.assign(config.helpers || {}, helpers),
+        functions: Object.assign(config.functions || {}, functions),
+        plugins: args?.values?.plugin || config.plugins || [],
+    };
+};
+
+// @description main build script
+export const build = async (config = {}) => {
+    const inputFiles = await loadInputFiles(config.context, config.input);
+    const data = await loadData(config.context, config.data);
+    const mikelInstance = mikel.create({
+        helpers: config.helpers,
+        functions: config.functions,
+        partials: config.partials,
+    });
+
+    // load plugins
+    for (const plugin of config.plugins) {
+        // check if the provided plugin is a function or an object
+        if (typeof plugin === "function" || (typeof plugin === "object" && !Array.isArray(plugin) && !!plugin)) {
+            mikelInstance.use(plugin);
+        }
+        else {
+            const pluginName = Array.isArray(plugin) ? plugin[0] : plugin;
+            const pluginOptions = Array.isArray(plugin) && plugin.length > 1 ? plugin.slice(1) : [];
+            try {
+                // try to import the plugin from node_modules
+                const pluginModule = (await import(pluginName))?.default;
+                if (typeof pluginModule !== "function") {
+                    throw new Error(`Plugin '${pluginName}' does not export a valid plugin function.`);
+                }
+                mikelInstance.use(pluginModule(...pluginOptions));
+            } catch (error) {
+                throw new Error(`Failed to load plugin '${pluginName}': ${error.message}`);
+            }
+        }
+    }
+
+    // process input files
+    for (const inputFile of inputFiles) {
+        const inputPath = path.resolve(config.context, inputFile);
+        if (!existsSync(inputPath)) {
+            throw new Error(`Template file '${inputPath}' was not found.`);
+        }
+        let template;
+        try {
+            template = await fs.readFile(inputPath, "utf8");
+        } catch (error) {
+            throw new Error(`Failed to read template file '${inputPath}': ${error.message}`);
+        }
+        // compile the template
+        let result;
+        try {
+            result = mikelInstance(template, data);
+        } catch (error) {
+            throw new Error(`Template compilation error: ${error.message}`);
+        }
+        // check if output argument has been provided to write the result to a file
+        // this will also create any intermediary directory that does not exist
+        if (config.output) {
+            const outputPath = resolveOutput(config.context, inputFile, config.output);
+            const outputDirectory = path.dirname(outputPath);
+            // make sure that any directory containing the output file exists
+            if (!existsSync(outputDirectory)) {
+                try {
+                    await fs.mkdir(outputDirectory, { recursive: true });
+                } catch (error) {
+                    throw new Error(`Failed to create output directory '${outputDirectory}': ${error.message}`);
+                }
+            }
+            try {
+                await fs.writeFile(outputPath, result, "utf8");
+                console.error(`✓ Saving '${inputPath}' -> '${outputPath}'`);
+            } catch (error) {
+                throw new Error(`Failed to write output file '${outputPath}': ${error.message}`);
+            }
+        }
+        // if no output file has been provided, print the result to console
+        else if (inputFiles.length === 1) {
+            process.stdout.write(result);
+        }
+        else {
+            throw new Error(`Unconsistent usage of input and output arguments.`);
+        }
+    }
+};
+
+// @description utility method to provide a typed configuration
+export const defineConfig = (config = {}) => config;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "mikel-cli",
     "description": "The cli tool for mikel templating.",
-    "version": "0.34.0",
+    "version": "0.35.1",
     "type": "module",
     "license": "MIT",
     "author": {
@@ -16,25 +16,32 @@
     "engines": {
         "node": ">=24.0.0"
     },
+    "types": "index.d.ts",
     "scripts": {
-        "test": "node test.js"
+        "test": "node --import=./loader.js test.js"
     },
     "exports": {
-        ".": "./index.js",
-        "./index.js": "./index.js",
-        "./cli.js": "./cli.js",
+        ".": {
+            "import": "./index.js",
+            "types": "./index.d.ts"
+        },
+        "./index.js": {
+            "import": "./index.js",
+            "types": "./index.d.ts"
+        },
         "./package.json": "./package.json"
     },
     "bin": {
         "mikel": "cli.js"
     },
     "peerDependencies": {
-        "mikel": "^0.34.0"
+        "mikel": "^0.35.1"
     },
     "files": [
         "README.md",
         "cli.js",
-        "index.js"
+        "index.js",
+        "index.d.ts"
     ],
     "keywords": [
         "mikel",