Narcissistic Preening Monarch

    @catalyst-elements/dev-utils
    TypeScript icon, indicating that this package has built-in type declarations

    0.0.2 • Public • Published

    This is a work in progress that is not ready to be used yet

    Catalyst Elements' Development Utilities

    Travis David David npm (scoped)

    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.

    Keywords

    none

    Install

    npm i @catalyst-elements/dev-utils

    DownloadsWeekly Downloads

    1

    Version

    0.0.2

    License

    BSD-3-Clause

    Unpacked Size

    188 kB

    Total Files

    103

    Last publish

    Collaborators

    • catalyst-elements