component-build-tools
Advanced tools
A set of build tools to simplify the creation of components
A set of build tools to help in the creation of components. These components can be web components or any other grouping of code to be used in the browser or in other environments like node.js.
Used with rollup, these tools will allow you to process locale file and template files into a set of .mjs files that are importable in your script files.
For those of you that have used gulp-component-assembler these tools allow similar functionality but by using ES6 imports instead of defining the component through an assembly.json file.
You need to install the component build tools in your project:
npm install --save-dev component-build-tools
You will also need to install the latest rollup in your project
npm install --save-dev rollup
For the component-build-tools to work with rollup you need to provide a config file named rollup.config.js in your project's root folder.
Here are two sample rollup.config.js files:
const rollup = require('component-build-tools').components.rollup;
const config = {
buildTypes: [ rollup.BUILD_TYPES.MJS ], // Set this to any build styles you want.
srcFolders: ['assets/wc-n1', 'assets/wc-p3'] // Set this to any folder you want to have rollup process
};
module.exports = rollup.init(config);
and
const {init, BUILD_TYPES} = require('component-build-tools').components.rollup;
const config = {
buildTypes: [ BUILD_TYPES.MJS, BUILD_TYPES.CJS, BUILD_TYPES.CJS5 ],
srcFolders: ['assets/*']
};
module.exports = init(config);
The first example will only build from the folders assets/wc-n1 and assets/wc-p3 and will generate two output module files in the dist/js folder.
The second example builds module files, common JS files and common JS files that have been transpiled into ES5. Its source is any and all folders inside the assets folder.
To run rollup:
./node_modules/.bin/rollup -c
There are 5 build styles:
| Build Style | Description |
|---|---|
| IIFE | IFFE styled output with no transpiling. |
| IIFE5 | IFFE output with ES5 transpile operation. For compatibility with older ES5 browsers. |
| CJS | Common JS output. Load by using require |
| CJS5 | Common JS output with ES5 transpile. Load by using require. For compatibility with older ES5 browsers. |
| MJS | ES6 Module output. Load by using import |
When you call init you pass in a set of options. Most are optional. The only one required is srcFolders.
| Option | Type | Default Value | Description |
|---|---|---|---|
| addEOLocale | bool | true | Add the EO (Esperanto) locale if it does not exist. |
| addKELocale | bool | false | Add the KE locale if it does not exist. This is a fake locale that returns the KEY as the string to help in debugging. |
| alwaysReturnFile | bool | false | The files _compiled/locales.msj and _compiled/templates.mjs will always be created if this value is true. Otherwise they will not be created. |
| buildTypes | array | [BUILD_TYPES.MJS,BUILD_TYPES.IIFE] | The list of build styles to create. See Build Styles above. |
| debug | bool | false | true to enable debug output. |
| defaultLocale | string | 'en' | The locale to use as the default locale when compiling locale files. |
| defaultLocaleVariable | string | 'document.documentElement.lang' | The variable to use as the default locale that is read at runtime that your app defines.document.documentElement.lang is the value stored in the lang attribute of the <html> tag. Changing that value will change what locale strings are used.<html lang='en'> will use the 'en' locale strings.<html lang="fr"> will use the 'fr' locale strings. |
| distPath | string/object | 'dist/js' | Path into which the distribution files will be placed. If distPath is an object then it must include one entry per output type defined in buildTypes.See distPath below. |
| includePath | bool | false | If this is set to false then the output files are placed directly into the distPath folder. If this is set to true then the output files are placed in a child folder named after the source folder inside the distPath folder. |
| localeFiles | array | ['locales/strings_*.json'] | An array of relative glob paths defining the locale files to load. |
| makeMinFiles | bool | false | If set to true then the output will include creating minimized files. |
| minTemplateWS | bool | true | Minimize the white space within the template files. |
| separateByLocale | bool | false | Currently not supported When true this will generate one output file per locale supported in the localesFile glob list. false will only produce one file with all locale data embedded. |
| sourcemap | bool | false | If true then sourcemap files are generated. If false then sourcemap files are not generated. |
| srcFileName | string | undefined | If undefined then we use the folder name to specify the source file name. Otherwise the srcFileName string is used.See srcFileName below. |
| srcFolders | string/array | [] | An array of glob folders in which to look into for source files. This is required. The user must supply this value. See srcFolders below. |
| tagMissingStrings | bool | true | When true Mark missing locale strings so they are easily seen. |
| templateFiles | array | ['*.html'] | A glob array of files to include as templates. |
| tempLocalesName | string | 'locales.mjs' | The filename used for the compiled locales file. |
| tempPath | string | './_compiled/' | The path into which all compiled files are place. |
| tempTemplateName | string | 'templates.mjs' | The filename used for the compiled templates file. |
| useStrict | bool | false | If true then add "use strict" at the top of the rolled up output files. |
If distPath is a string then the same distPath is used in the output for any build type.
You can also define distPath as an object to change the output path for each build type.
If you set buildType to [BUILD_TYPES.MJS, BUILD_TYPES.CJS] then your distPath object needs to include two properties, one per build type:
distPath: {
MJS: './path/for/mjs/built/files',
CJS: './cjs/file/path'
}
If you include extra properties they will be ignored. But you must include one property per build type. If you don't then an exception will be thrown and the build will fail.
If srcFileName is left as undefined then the name of the source files will be the same name as the folder with the extension of .mjs.
For example, the file structure below shows a folder named test1 and within it is a file named test1.mjs. The build process of the build tools will take test1.mjs as the root file to use in the rollup config file.
└─ components
└─ test1
├─ test1.msj
├─ style.html
└─ content.html
And the default output file will be placed in:
└─ dist
└─ js
└─ test1.mjs
The output file ./dist/js/test1/test1.mjs will combine the two template files style.html and content.html as well as the source file test1.js as one set of code.
If srcFileName were set to index.mjs then the build tools would use index.msj as the root file to use in the rollup config file.
└─ components
└─ test1
├─ index.msj
├─ style.html
└─ content.html
would still produce the same output structure of:
└─ dist
└─ js
└─ test1.mjs
If the value for includePath had been set to true then the output structure would be:
└─ dist
└─ js
└─ test1
└─ test1.mjs
srcFolders is the only option that must be supplied. This specifies the folder or folders that are to be processed by the build tools.
If you have all of your components stored in child folders of the folder ./comps then you would call init({srcFolders:['./comps/*']}).
Every folder directly under ./comps would get processed. Any subfolder that was found to match the requirements of a component will be handed off to rollup for further processing.
You can specify each folder independently within the array, and each entry in the array can either be a real path to a specific folder or a glob path to a set of folders.
init({srcFolders:['./comps/component1']})will only look at the path./comps/component1whileinit({srcFolders:['./comps/*']})will look at all direct child folders under./comps.
Locale files are JSON files that contain locale specific translations of strings you use in your application. By default the files are all placed in the locales folder and are named strings_??.json where the ?? is the 2 letter locale such as en, fr, or ja.
The file ./locales/strings_en.json will contain the English version of the strings. The file ./locales/strings_fr.json contains the French version of the strings. You can use things like en-US for US english and fr-CA for Canadian French. The two letter ISO 639-1 code and a subset of the BCP-47 codes are supported.
Currently we only support the 2 letter ISO 639-1 code and this ISO 639-1 code followed by a dash "-" and then the 2 letter ISO-3166 country code. Like en, fr, en-US, en-GB, fr-CA and fr-FR. Case is ignored.
These locale files are combined into the file ./_compiled/locales.mjs and you access them by importing that file and then calling the default function to get the set of locale strings for the specified locale.
import locales from "./_compiled/locales.mjs";
const lang = locales('en');
If no locale key is provided in the
locales()function then the default locale object is returned.
Template files tend to be HTML files but can be any kind of file. As a result of the compile process the contents of the template files are embedded into a template literal inside of the template.mjs file.
For example, if there is a template file called person.html:
<div class="person">
<div>Name: <span class="name">Frank N Stein</span></div>
</div>
Then the entry generated in the templates.mjs file would be:
case 'person':
return `<div class="person"> <div>Name: <span class="name">Frank N Stein</span></div> </div>`;
Since all templates become ES6 Template literals you can do some creative things in your template files. Let's say that you want to create a <table> with 5 rows. You could do it like this:
<table>
<tr class="row1">
<td>1</td>
<td class="name"></td>
<td class="age"></td>
</tr>
<tr class="row2">
<td>1</td>
<td class="name"></td>
<td class="age"></td>
</tr>
<tr class="row3">
<td>3</td>
<td class="name"></td>
<td class="age"></td>
</tr>
<tr class="row4">
<td>4</td>
<td class="name"></td>
<td class="age"></td>
</tr>
<tr class="row5">
<td>5</td>
<td class="name"></td>
<td class="age"></td>
</tr>
</table>
Or you can embed an second ES6 template literal within your template:
<table>
${[1,2,3,4,5].map( i => `<tr class="row${i}">
<td>${i}</td>
<td class="name"></td>
<td class="age"></td>
</tr>`).join('')}
</table>
When you get this string it will execute this template literal expression:
[1,2,3,4,5].map( i => `<tr class="row${i}">
<td>${i}</td>
<td class="name"></td>
<td class="age"></td>
</tr>`).join('')
This, in turn will return five copies of the internal HTML (The <tr> with its three <td> tags). THe join('') will convert them into a string and this will be inserted just inside the <table> tags.
The end result of the two example above are almost identical. Since we removed the duplication of code the second example is more flexible and less prone to errors.
If you need to add a back-tick ``` character into your template, outside of your template literals, then you must escape it like with the backslash, like this:
<p>This is the back-tick: \`</p>
This allows the back-tick to exist as a stand alone character and not as the ending of the generated template literal.
The compiled output would be this:
return `<p>This is the back-tick: \`</p>`;
If your component includes both templates and locale strings then the strings are made available to the template through the lang variable. The lang variable is auto-inserted into the templates.mjs file for all projects that have locale string files.
Locale file: ./locales/strings_en.json
{
"NAME": "Frank N Stein"
}
Template file: ./person.html
<div class="person">
<div>Name: <span class="name">${lang.NAME}</span></div>
</div>
Output in ./_compiled/templates.mjs:
import locales from './locales.mjs';
const lang = locales();
.
.
.
templates.str = function(key, data) {
switch(key) {
case 'person';
return `<div class="person"> <div>Name: <span class="name">${lang.NAME}</span></div> </div>`;
.
.
.
}
}
The signature of the functions templates.str and templates.dom is:
function(key, data) {}
So when your code calls either templates.str and templates.dom you can pass any object as the second parameter.
The first parameter is they key used to get the correct template.
If you wanted to create a table with a number of rows defined by a variable you would create your template like this:
Template file content.html:
<table>
${[...Array(data.size).keys()].map( i => `<tr class="row${i}">
<td>${i}</td>
<td class="name"></td>
<td class="age"></td>
</tr>`).join('')}
</table>
If you called templates.str('content', {size: 10}) then 10 rows would be created. If you called templates.str('content', {size: 87}) then 87 rows would be created.
You can pass in any data and use it any way your imagination can imagine. You just need to follow the rules for template literals.
import in a templateSometimes you need to be able to access external code within a template.
In this example we need an external function called name.
<div class="person">
<div>Name: <span class="name">${name("FRANK")}</span></div>
</div>
To do this we can add the import to the template file like this:
<%
import name from "../name.mjs";
%>
<div class="person">
<div>Name: <span class="name">${name("FRANK")}</span></div>
</div>
The import line of code will be inserted into the top of templates.mjs. You can add as many import lines as you need.
ONLY
importis valid within a template. No other code is permitted.
| Date | Version | Description |
|---|---|---|
| 07/24/2018 | 2.1.1 | ● Fixed tests to run on Windows as well as other OSs. ● Handle windows path.join() with inclusion of drive letter: C:\● Revert to simple minification if html-minify fails.● Updated version and docs |
| 06/18/2018 | 2.1.0 | ● Moved source files to lib folder.● Added index.js.● Added use of html-minify to improve minification of templates. ● Cleaned up documentation. ● Now using components.rollup as a sub-object for require. Getting ready for v3.0.0 and additional functionality. |
| 06/11/2018 | 2.0.1 | ● Bug fix to correctly set the name of an IIFE conversion. |
| 06/07/2018 | 2.0.0 | Breaking Changes!! ● Removed the escaping of the back-tick in templates. This was preventing sub-ES6 Template Literals in the templates. ● You now must list the source folders. In most cases you would change from srcPath: "modules/src" to srcPath: "modules/src/*"● Changed default build types from MJS and IIFE to MJS and CJS since these can both be loaded in a similar manner. ● addKELocale is now false by default● alwaysReturnFile is now false by default.● defaultLocaleVariable is now set to document.documentElement.lang which is the value set in the lang attribute of the <html> tag: <html lang="fr"> would use fr as the default value when getting the lang object.● includePath is now false by default.● New config options dstExtCJS, dstExtCJS5, dstExtIIFE, dstExtIIFE5 and dstExtMJS allow you to set the output extension for the various output file types.● Added ability for distPath to be an object and not just a string.● Added and cleaned up Docs ● Added more testing for the new code. |
| 05/29/2018 | 1.1.0 | ● Added code to allow template files to define imports they need. ● Improved Docs. Added Travis and Code Climate. |
| 05/10/2018 | 1.0.2 | ● Corrected REGEX to get correct file names for locale files. ● Improved error output to simplify debugging. |
| 04/03/2018 | 1.0.1 | ● Added pre-commit tests. |
| 03/29/2018 | 1.0.0 | ● Added options for addKELocale, defaultLocaleVariable and sourcemap.● Spelling Correction: Renamed option minTempalteWS to minTemplateWS.● If there are no compiled files to generate and alwaysReturnFile if set to false then no temporary folder is created. |
| 02/26/2018 | 0.0.0 | Initial Release. |
FAQs
A set of build tools to simplify the creation of components
We found that component-build-tools demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.