# UTAM Generator UTAM Generator is a tool that generates UTAM JSON files from HTML files. An input HTML file can be either a raw HTML downloaded from a browser or a Web Component source code in HTML format, such as a Lightning web component. Starting from version 2.1.0, the generator supports generation of a UTAM JSON page object from a JavaScript file with hardcoded HTML snippets. For more details, see [Generate from JavaScript](#generate-from-javascript). :::important Before you use the generator on a Salesforce page, use the [UTAM browser extension](https://utam.dev/tools/browser-extension) to identify existing page objects provided by Salesforce. You generally need to generate new page objects only for custom components or custom UI that you create. ::: Use the [generator playground](https://utam.dev/tools/generator-playground) to generate UTAM page objects from HTML or run the generator in your own repository. See the configuration steps in the next sections. - To run the generator in your own repository, see the configuration steps in the next section. ## Set up project dependencies The generator artifact is published in [npm](https://www.npmjs.com/package/@utam/generator). The `package.json` file configures the dependencies for a JavaScript project. Add a development dependency for the UTAM generator by running one of these commands: - `yarn add utam --dev` - `npm install utam --save-dev` These commands are equivalent and add `utam` to the `devDependencies` property in `package.json`, where `x.y.z` represents the installed version and is the latest version by default. ```json { "devDependencies": { "utam": "x.y.z" } } ``` ## Set up generate step in package.json The `package.json` file has a script that runs the `utam-generate` generation CLI command. `utam` is installed locally in your project because you added it to the `devDependencies` in `package.json`. ```json { "scripts": { "build": "yarn generate:utam", "generate:utam": "utam-generate -c utam-generator.config.json" }, "devDependencies": { "utam": "x.y.z" } } ``` ## Generator configuration file You can specify options in the generator configuration file. Use the `-c` flag of the `utam-generate` CLI to point at the configuration file. In this example, we use `utam-generator.config.json`. ```bash utam-generate -c utam-generator.config.json ``` Use the `-p` flag of the `utam-generate` CLI to point the generator at multiple configuration files. This approach is useful if you have a repo where you need different configuration options in different subprojects. In most scenarios, the `-c` flag suffices and you don't need to use the `-p` flag. ```bash utam-generate -p 'path/to/project1/utam.config.json' 'path/to/project2/utam.config.json' ``` :::note Pass a list of whitespace-separated utam compiler configuration file paths. ::: The generator configuration options are explained in the next section. ## Generation runner parameters You don't have to explicitly declare any options for the generator because all options have default values. If your project structure follows the default convention, the compiler works out of the box. In that case, set the generator configuration file to be an empty object, {}. This section lists all the options supported by the generator runner. For each option, we describe its JSON type, its default value, and what it does. There are other configuration parameters responsible for how the generator interprets HTML. Those parameters are explained in the [Generator rules guide](/tools/generator-guide). ```json { "inputRootDir": "./", // config file directory name "ignore": ["**/node_modules/**"], "inputFileMask": ["**/*.html"], "outputDir": "__utam__", "relativeOutputDir": false, "outputFileExtension": ".utam.json", "overrideExisting": true, "rulesFileMask": ["**/*.rules.json"] } ``` ### `inputRootDir` - Type: `string` - Default: `path.dirname(configFilePath)` The relative path from the configuration file's directory that represents the root directory path. The generator looks recursively in the root directory for HTML files. Defaults to the configuration file's directory if not specified. For instance, if your `utam-generator.config.json` configuration file is at the package root (the same level as the `package.json` file), the page object root directory defaults to the package root directory. ### `ignore` - Type: `string[]` - Default: `["**/node_modules/**"]` You can specify which folders and files should be ignored and not traversed by the generator. Defaults to ignore only `**/node_modules/**`. ### `inputFileMask` - Type: `string[]` - Default: `["**/*.html"]` The file mask pattern used by the generator to find HTML input files. It tells the generator where to start scanning for the source files relative to `inputRootDir`. Declare the file mask as a list of glob patterns. ### `relativeOutputDir` - Type: `boolean` - Default: `false` See `outputDir` for details. ### `outputDir` - Type: `string` - Default: `"__utam__"` The relative path from the `inputRootDir` directory to the target directory for generated UTAM JSON files. The generator writes the JSON page objects to this directory. If `relativeOutputDir` is set to `false`, a single folder is created under `inputRootDir`. ```txt ├── utam-generator.config.json ├── __utam__ ├── component1.utam.json ├── component2.utam.json ├── src/ └── modules/ ├── component1/... ├── component2/... ``` If `relativeOutputDir` is set to `true`, the output is generated under the same folder as the source file. The path is relative to the source folder. For example, if `outputDir` is set to `__utam__`, here's where the output is generated: ```txt ├── utam-generator.config.json ├── src/ └── modules/ ├── component1/ └── component1.html └── __utam__/ └── component1.utam.json ├── component2/ └── component2.html └── __utam__/ └── component2.utam.json ``` ### `outputFileExtension` - Type: `string` - Default: `".utam.json"` The generated output file has the same name as the source file with `.html` removed and with the `outputFileExtension` added as a suffix. For example, a `myComponent.html` source file generates `myComponent.utam.json`. ### `overrideExisting` - Type: `boolean` - Default: `true` If set to `true`, the generator overrides an existing file with the same name. By default if `myComponent.utam.json` already exists, it is overridden. ### `rulesFileMask` - Type: `string[]` - Default: `["**/*.rules.json"]` The file mask for component-based individual [generation rules](/docs/platform/utam/guide/generator-rules.md). ### `scriptHtmlWrapper` - Type: `string` - Default: undefined An HTML tag that will be used to wrap HTML snippets extracted from a JavaScript file. See [Generate from JavaScript](#generate-from-javascript). For example, if the value is `'html'`, the output will be `extracted HTML`. ## Generate from JavaScript You can generate a UTAM page object from a JavaScript file that contains HTML snippets. To enable the generator to find the HTML snippets in JavaScript files, add the mask for JavaScript files to the `inputFileMask` configuration parameter. ```json { "inputFileMask": ["**/*.html", "**/*.js"] } ``` The generator now looks into files with the `*.js` extension and extracts HTML code snippets. The generator uses [generator rules](/docs/platform/utam/guide/generator-rules.md) to generate UTAM page objects from the extracted snippets. For example, this JavaScript file contains an HTML snippet: ```js class Component { render() { return (
); } } ``` The UTAM generator recognizes code in the `div` tag as HTML and generates this JSON: ```json { "elements": [ { "public": true, "name": "button", "type": ["actionable", "clickable"], "selector": { "css": "button" } } ] } ``` If the `scriptHtmlWrapper` configuration parameter is set, the generated code will be wrapped into an HTML tag. For example, if the generator configuration is: ```json { "inputFileMask": ["**/*.html", "**/*.js"], "scriptHtmlWrapper": "html" } ``` The JSON is generated as if the HTML snippet in a JavaScript file was inside an `html` tag. ```json { "root": true, "selector": { "css": "html" }, "elements": [ ... ] } ```