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; for example, a Lightning web component.
Any logic or page content that isn't stored inside static HTML files, for example JavaScript, isn't processed.
Setup
The generator artifact is published in npm.
To use the generator, you have two options.
-
To use the generator as a utility, clone the
utam-js-recipes
repository and follow the instructions. -
To run the generator in your own repository, see the configuration steps in the next section.
Set up project dependencies
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.
{
"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
.
{
"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
.
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.
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.
{
"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
.
<inputRootDir>
├── 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:
<inputRootDir>
├── 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.