@microsoft/fast-build 0.3.2 → 0.4.0

package/README.md

@@ -39,6 +39,8 @@ fast build [options]
 | `--state="<path>"` | `state.json` | JSON file containing the template state |
 | `--output="<path>"` | `output.html` | Where to write the rendered HTML |
 | `--templates="<glob>"` | _(none)_ | Glob pattern(s) for custom element template HTML files. Separate multiple patterns with commas. A warning is printed if not provided or if no files match a pattern. |
+| `--attribute-name-strategy="<strategy>"` | `none` | Strategy for mapping HTML attribute names to state property names on custom elements. `"none"` preserves dashes (e.g. `foo-bar` → `foo-bar`). `"camelCase"` converts dashes to camelCase (e.g. `foo-bar` → `fooBar`). See [Attribute name strategy](#attribute-name-strategy). |
+| `--config="<path>"` | `fast-build.config.json` | Path to a JSON configuration file. If omitted, `fast-build.config.json` in the current directory is used when present. CLI arguments take precedence over config values. See [Configuration file](#configuration-file). |
 
 ### Example
 
@@ -105,6 +107,54 @@ Template files must use the following format:
 
 If an `<f-template>` element has no `name` attribute, a warning is printed and it is ignored. Exact file paths (no wildcards) are also accepted as patterns, making it possible to register a single template file.
 
+### Attribute name strategy
+
+The `--attribute-name-strategy` option controls how HTML attribute names on custom elements are mapped to state property names in their shadow templates.
+
+| Strategy | Behaviour | Template binding |
+|---|---|---|
+| `none` (default) | Attribute names lowercased as-is, dashes preserved | `foo-bar` → `{{foo-bar}}` |
+| `camelCase` | Dashed attribute names converted to camelCase | `foo-bar` → `{{fooBar}}` |
+
+The `camelCase` strategy only affects "plain" custom element attributes. It does **not** change:
+- `data-*` attributes (always use `dataset.*` grouping)
+- `aria-*` attributes (always use ARIA reflection lookup)
+- HTML global attributes with known property names (e.g. `tabindex` → `tabIndex`)
+
+```shell
+fast build \
+  --templates="./components/**/*.html" \
+  --attribute-name-strategy=camelCase \
+  --entry=index.html \
+  --state=state.json \
+  --output=output.html
+```
+
+### Configuration file
+
+Instead of passing every option on the command line, you can place a `fast-build.config.json` file alongside your project files:
+
+```json
+{
+    "entry": "index.html",
+    "state": "state.json",
+    "output": "output.html",
+    "templates": "./components/**/*.html"
+}
+```
+
+The CLI automatically loads `fast-build.config.json` from the current directory when it exists. To use a different file, pass `--config`:
+
+```shell
+fast build --config=configs/my-build.json
+```
+
+**Precedence:** CLI arguments always override config file values. For example, `--output=other.html` will override the `output` value in the config file.
+
+**Path resolution:** File paths in the config file (`entry`, `state`, `output`, `templates`) are resolved relative to the config file's directory, not the current working directory. This ensures the config works correctly regardless of where the CLI is invoked.
+
+All keys are optional. Only the following keys are allowed: `entry`, `state`, `output`, `templates`, `attribute-name-strategy`. Unknown keys or non-string values produce an error.
+
 ## Template syntax
 
 Template syntax follows the FAST declarative HTML format. See the [`@microsoft/fast-html` README](../fast-html/README.md) for full documentation on bindings, conditionals, repeats, and directives.

package/bin/fast.js

@@ -6,6 +6,14 @@ const fs = require("fs");
 const path = require("path");
 
 const WASM_MODULE = path.join(__dirname, "../wasm/microsoft_fast_build.js");
+const DEFAULT_CONFIG_FILENAME = "fast-build.config.json";
+const ALLOWED_CONFIG_KEYS = new Set([
+    "entry",
+    "state",
+    "output",
+    "templates",
+    "attribute-name-strategy",
+]);
 
 /**
  * Parse CLI arguments of the form --key="value" or --key=value.
@@ -23,6 +31,106 @@ function parseArgs(argv) {
     return args;
 }
 
+/**
+ * Load and validate a fast-build config file.
+ *
+ * - If `configPath` is provided, the file must exist (error if missing).
+ * - If `configPath` is not provided, looks for `fast-build.config.json` in CWD.
+ *   Returns an empty object if the default file does not exist.
+ *
+ * File paths in the returned config are resolved relative to the config
+ * file's directory so that the caller can use them directly.
+ *
+ * @param {string | undefined} configPath - Explicit path from --config, if any.
+ * @returns {{ config: Record<string, string>, configDir: string | null }}
+ */
+function loadConfig(configPath) {
+    /** @type {string} */
+    let resolvedPath;
+    /** @type {boolean} */
+    let isExplicit;
+
+    if (configPath !== undefined) {
+        resolvedPath = path.resolve(configPath);
+        isExplicit = true;
+    } else {
+        resolvedPath = path.resolve(DEFAULT_CONFIG_FILENAME);
+        isExplicit = false;
+    }
+
+    if (!fs.existsSync(resolvedPath)) {
+        if (isExplicit) {
+            process.stderr.write(
+                `Error: Config file "${configPath}" not found.\n`
+            );
+            process.exit(1);
+        }
+        return { config: {}, configDir: null };
+    }
+
+    let raw;
+    try {
+        raw = JSON.parse(fs.readFileSync(resolvedPath, "utf8"));
+    } catch (e) {
+        process.stderr.write(
+            `Error: Failed to parse config file "${resolvedPath}": ${e.message}\n`
+        );
+        process.exit(1);
+    }
+
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        process.stderr.write(
+            `Error: Config file "${resolvedPath}" must contain a JSON object.\n`
+        );
+        process.exit(1);
+    }
+
+    for (const key of Object.keys(raw)) {
+        if (!ALLOWED_CONFIG_KEYS.has(key)) {
+            process.stderr.write(
+                `Error: Unknown key "${key}" in config file "${resolvedPath}". Allowed keys: ${[...ALLOWED_CONFIG_KEYS].join(", ")}.\n`
+            );
+            process.exit(1);
+        }
+        if (typeof raw[key] !== "string") {
+            process.stderr.write(
+                `Error: Value for "${key}" in config file "${resolvedPath}" must be a string.\n`
+            );
+            process.exit(1);
+        }
+    }
+
+    const configDir = path.dirname(resolvedPath);
+    return { config: raw, configDir };
+}
+
+/**
+ * Resolve a file path value, preferring the CLI arg over the config value.
+ * Config-derived paths are resolved relative to the config file's directory.
+ * CLI-derived paths are resolved relative to CWD (the default behaviour).
+ *
+ * @param {Record<string, string>} args - Parsed CLI arguments.
+ * @param {Record<string, string>} config - Parsed config file values.
+ * @param {string | null} configDir - Directory of the config file, or null.
+ * @param {string} key - The option key.
+ * @param {string} [defaultValue] - Fallback when neither source provides a value.
+ * @returns {string | undefined}
+ */
+function resolveOption(args, config, configDir, key, defaultValue) {
+    if (Object.prototype.hasOwnProperty.call(args, key)) {
+        return args[key];
+    }
+    if (Object.prototype.hasOwnProperty.call(config, key)) {
+        const value = config[key];
+        const isFilePath = key === "entry" || key === "state" || key === "output" || key === "templates";
+        if (isFilePath && configDir !== null) {
+            return path.resolve(configDir, value);
+        }
+        return value;
+    }
+    return defaultValue;
+}
+
 /**
  * Walk a directory recursively and collect all .html file paths.
  * @param {string} dir
@@ -163,10 +271,22 @@ function resolvePattern(pattern, wasm) {
 }
 
 async function runBuild(args) {
-    const templatesArg = args["templates"];
-    const output = args["output"] || "output.html";
-    const entry = args["entry"] || "index.html";
-    const stateFile = args["state"] || "state.json";
+    const { config, configDir } = loadConfig(
+        Object.prototype.hasOwnProperty.call(args, "config") ? args["config"] : undefined
+    );
+
+    const templatesArg = resolveOption(args, config, configDir, "templates");
+    const output = resolveOption(args, config, configDir, "output", "output.html");
+    const entry = resolveOption(args, config, configDir, "entry", "index.html");
+    const stateFile = resolveOption(args, config, configDir, "state", "state.json");
+    const attributeNameStrategy = resolveOption(args, config, configDir, "attribute-name-strategy");
+
+    if (attributeNameStrategy && attributeNameStrategy !== "none" && attributeNameStrategy !== "camelCase") {
+        process.stderr.write(
+            `Error: Invalid --attribute-name-strategy "${attributeNameStrategy}". Expected "none" or "camelCase".\n`
+        );
+        process.exit(1);
+    }
 
     // Load WASM module first — needed for both template parsing and rendering.
     const wasm = require(WASM_MODULE);
@@ -214,7 +334,9 @@ async function runBuild(args) {
     // Render
     let rendered;
     if (Object.keys(templatesMap).length > 0) {
-        rendered = wasm.render_entry_with_templates(entryContent, JSON.stringify(templatesMap), stateContent);
+        rendered = wasm.render_entry_with_templates(
+            entryContent, JSON.stringify(templatesMap), stateContent, attributeNameStrategy || "none"
+        );
     } else {
         rendered = wasm.render(entryContent, stateContent);
     }
@@ -234,7 +356,16 @@ async function main() {
             '                         Separate multiple patterns with commas.\n' +
             '  --output="output.html" Output file path (default: output.html)\n' +
             '  --entry="index.html"   Entry HTML template file (default: index.html)\n' +
-            '  --state="state.json"   State JSON file (default: state.json)\n'
+            '  --state="state.json"   State JSON file (default: state.json)\n' +
+            '  --attribute-name-strategy="none"\n' +
+            '                         Strategy for mapping attribute names to property names.\n' +
+            '                         "none" (default) or "camelCase".\n' +
+            '  --config="<path>"      Path to a fast-build config JSON file.\n' +
+            '                         Defaults to "fast-build.config.json" in the\n' +
+            '                         current directory if it exists. File paths in\n' +
+            '                         the config are resolved relative to the config\n' +
+            '                         file\'s directory. CLI arguments take precedence\n' +
+            '                         over config file values.\n'
         );
         return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@microsoft/fast-build",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "CLI and Node.js API for server-side rendering of FAST declarative HTML templates.",
   "author": {
     "name": "Microsoft",
@@ -28,7 +28,8 @@
     "wasm/microsoft_fast_build_bg.wasm.d.ts"
   ],
   "scripts": {
-    "build": "cargo build --manifest-path ../../crates/microsoft-fast-build/Cargo.toml && wasm-pack build --target nodejs ../../crates/microsoft-fast-build --out-dir ../../packages/fast-build/wasm"
+    "build": "cargo build --manifest-path ../../crates/microsoft-fast-build/Cargo.toml && wasm-pack build --target nodejs ../../crates/microsoft-fast-build --out-dir ../../packages/fast-build/wasm",
+    "test:node": "node --test test/config.test.js"
   },
   "engines": {
     "node": ">=22.18.0"

package/wasm/microsoft_fast_build.d.ts

@@ -23,14 +23,18 @@ export function render(entry: string, state: string): string;
  * output, while non-primitive values (`array`, `object`, `null`) are stripped.
  *
  * `templates_json` is a JSON object mapping element names to their HTML template strings.
+ * `attribute_name_strategy` controls attribute-to-property mapping: `"none"` (default)
+ * or `"camelCase"`. Pass an empty string for the default.
  * Returns the rendered HTML or throws a JavaScript error.
  */
-export function render_entry_with_templates(entry: string, templates_json: string, state: string): string;
+export function render_entry_with_templates(entry: string, templates_json: string, state: string, attribute_name_strategy: string): string;
 
 /**
  * Render a FAST HTML template with custom element templates and a JSON state string.
  * `templates_json` is a JSON object mapping element names to their HTML template strings,
  * e.g. `{"my-button": "<template>...</template>"}`.
+ * `attribute_name_strategy` controls attribute-to-property mapping: `"none"` (default)
+ * or `"camelCase"`. Pass an empty string for the default.
  * Returns the rendered HTML or throws a JavaScript error.
  */
-export function render_with_templates(entry: string, templates_json: string, state: string): string;
+export function render_with_templates(entry: string, templates_json: string, state: string, attribute_name_strategy: string): string;

package/wasm/microsoft_fast_build.js

@@ -63,15 +63,18 @@ exports.render = render;
  * output, while non-primitive values (`array`, `object`, `null`) are stripped.
  *
  * `templates_json` is a JSON object mapping element names to their HTML template strings.
+ * `attribute_name_strategy` controls attribute-to-property mapping: `"none"` (default)
+ * or `"camelCase"`. Pass an empty string for the default.
  * Returns the rendered HTML or throws a JavaScript error.
  * @param {string} entry
  * @param {string} templates_json
  * @param {string} state
+ * @param {string} attribute_name_strategy
  * @returns {string}
  */
-function render_entry_with_templates(entry, templates_json, state) {
-    let deferred5_0;
-    let deferred5_1;
+function render_entry_with_templates(entry, templates_json, state, attribute_name_strategy) {
+    let deferred6_0;
+    let deferred6_1;
     try {
         const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
@@ -79,18 +82,20 @@ function render_entry_with_templates(entry, templates_json, state) {
         const len1 = WASM_VECTOR_LEN;
         const ptr2 = passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len2 = WASM_VECTOR_LEN;
-        const ret = wasm.render_entry_with_templates(ptr0, len0, ptr1, len1, ptr2, len2);
-        var ptr4 = ret[0];
-        var len4 = ret[1];
+        const ptr3 = passStringToWasm0(attribute_name_strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len3 = WASM_VECTOR_LEN;
+        const ret = wasm.render_entry_with_templates(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
+        var ptr5 = ret[0];
+        var len5 = ret[1];
         if (ret[3]) {
-            ptr4 = 0; len4 = 0;
+            ptr5 = 0; len5 = 0;
             throw takeFromExternrefTable0(ret[2]);
         }
-        deferred5_0 = ptr4;
-        deferred5_1 = len4;
-        return getStringFromWasm0(ptr4, len4);
+        deferred6_0 = ptr5;
+        deferred6_1 = len5;
+        return getStringFromWasm0(ptr5, len5);
     } finally {
-        wasm.__wbindgen_free(deferred5_0, deferred5_1, 1);
+        wasm.__wbindgen_free(deferred6_0, deferred6_1, 1);
     }
 }
 exports.render_entry_with_templates = render_entry_with_templates;
@@ -99,15 +104,18 @@ exports.render_entry_with_templates = render_entry_with_templates;
  * Render a FAST HTML template with custom element templates and a JSON state string.
  * `templates_json` is a JSON object mapping element names to their HTML template strings,
  * e.g. `{"my-button": "<template>...</template>"}`.
+ * `attribute_name_strategy` controls attribute-to-property mapping: `"none"` (default)
+ * or `"camelCase"`. Pass an empty string for the default.
  * Returns the rendered HTML or throws a JavaScript error.
  * @param {string} entry
  * @param {string} templates_json
  * @param {string} state
+ * @param {string} attribute_name_strategy
  * @returns {string}
  */
-function render_with_templates(entry, templates_json, state) {
-    let deferred5_0;
-    let deferred5_1;
+function render_with_templates(entry, templates_json, state, attribute_name_strategy) {
+    let deferred6_0;
+    let deferred6_1;
     try {
         const ptr0 = passStringToWasm0(entry, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len0 = WASM_VECTOR_LEN;
@@ -115,18 +123,20 @@ function render_with_templates(entry, templates_json, state) {
         const len1 = WASM_VECTOR_LEN;
         const ptr2 = passStringToWasm0(state, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
         const len2 = WASM_VECTOR_LEN;
-        const ret = wasm.render_with_templates(ptr0, len0, ptr1, len1, ptr2, len2);
-        var ptr4 = ret[0];
-        var len4 = ret[1];
+        const ptr3 = passStringToWasm0(attribute_name_strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len3 = WASM_VECTOR_LEN;
+        const ret = wasm.render_with_templates(ptr0, len0, ptr1, len1, ptr2, len2, ptr3, len3);
+        var ptr5 = ret[0];
+        var len5 = ret[1];
         if (ret[3]) {
-            ptr4 = 0; len4 = 0;
+            ptr5 = 0; len5 = 0;
             throw takeFromExternrefTable0(ret[2]);
         }
-        deferred5_0 = ptr4;
-        deferred5_1 = len4;
-        return getStringFromWasm0(ptr4, len4);
+        deferred6_0 = ptr5;
+        deferred6_1 = len5;
+        return getStringFromWasm0(ptr5, len5);
     } finally {
-        wasm.__wbindgen_free(deferred5_0, deferred5_1, 1);
+        wasm.__wbindgen_free(deferred6_0, deferred6_1, 1);
     }
 }
 exports.render_with_templates = render_with_templates;

package/wasm/microsoft_fast_build_bg.wasm.d.ts

@@ -3,8 +3,8 @@
 export const memory: WebAssembly.Memory;
 export const parse_f_templates: (a: number, b: number) => [number, number];
 export const render: (a: number, b: number, c: number, d: number) => [number, number, number, number];
-export const render_entry_with_templates: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
-export const render_with_templates: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+export const render_entry_with_templates: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
+export const render_with_templates: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => [number, number, number, number];
 export const __wbindgen_externrefs: WebAssembly.Table;
 export const __wbindgen_malloc: (a: number, b: number) => number;
 export const __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;