README
This is a work in progress that is not ready to be used yet
Catalyst Elements' Development Utilities
This package contains opinionated utilities that are helpful for developing custom web components.
Many of the utilities this package contains make assumptions about the structure of the repository they are working on as well as the technologies used. Use the same technologies and follow the same repository structure that the Catalyst Elements use for best results.
Please note this package is only intended to be uses as dev dependency.
Installation
# Install with npm:
npm install --save-dev @catalyst-elements/dev-utils
# Install with yarn:
yarn add -D @catalyst-elements/dev-utils
Usage
Cli
This package contains an executable script called catalyst-elements
which can
preform various tasks.
Example of using catalyst-elements
in package.json
's scripts
:
{
"name": "my-element",
"scripts": {
"build": "catalyst-elements build",
"build-docs": "catalyst-elements build-docs",
"generate-auto-analysis": "catalyst-elements generate-auto-analysis",
"lint": "catalyst-elements lint",
"test": "catalyst-elements test"
},
"devDependencies": {
"@catalyst-elements/dev-utils": "*"
}
}
JS API
This package can be used in JavaScript to preform various tasks.
Example of using catalyst-elements
to build a component:
import * as catalystElements from '@catalyst-elements/dev-utils';
async function run() {
const options = catalystElements.loadOptions();
const config = await catalystElements.loadConfig(options);
await catalystElements.build(options, config);
}
run()
.then(() => {
console.log('The build has finished.');
})
.catch(() => {
console.log('Something when wrong.');
});
Tasks
Build
Build the component from the source files.
cli task name: build
js api function: build
Build Docs
Build the documentation for the component.
Documentation should be contained in the file analysis.json
which should be
located at the root of the repository of the component being build.
See Automatic Analysis Generation for details
on creating the analysis.json
file.
cli task name: build-docs
js api function: buildDocs
Lint
Run linting on the source code.
TypeScript files (*.ts
) are linted with
TSLint.
Sass files (*.scss
) are linted with stylelint.
cli task name: lint
js api function: lint
Test
Run the tests for the component.
Tests are run using web component tester.
cli task name: test
js api function: test
Automatic Analysis Generation
Generates an analysis of the component (auto-analysis.json
) from its
distribution code. An analysis is needed for the component's documentation.
Note: The analysis created by this task is often not fully complete by it acts as a good starting point. Manual editing of the automatically generated analysis is recommended.
cli task name: generate-auto-analysis
js api function: analyze
Configuration
The cli, a config file can be specified with the --config
flag. With the JS
api, pass an object into the function loadOptions()
with the key configFile
and value of the path to the config file.
The config file should be a JavaScript file that has a default export of type
UserConfig
; see the type definition for
details.
Note: A TypeScript file can be given instead if the script is run through ts-node instead of node.
Utility Functions
Function | Description |
---|---|
glob(pattern, options) |
Uses node-glob to do glob matching but with a promise-based interface and support for multiple patterns. |
Contributions
Contributions are most welcome.
Please read our contribution guidelines.