@legumeinfo/web-components

This repository contains a Web Component library developed for the Legume Information System and other AgBio databases. The Web Components are built using Lit and the UIkit CSS framework. UIkit, however, is only listed as a development dependency and must be installed independently when using this library.

This readme is intended for developers. For user documentation, see the NPM readme and our documentation site.

Setup

Install dependencies:

npm i

Build

This project uses the TypeScript compiler to produce JavaScript that runs in modern browsers.

To build the JavaScript version of the library:

npm run build

To watch files and rebuild when the files are modified, run the following command in a separate shell:

npm run build:watch

All built files will be placed in the lib/ directory.

Testing

This project uses modern-web.dev's @web/test-runner for testing. See the modern-web.dev testing documentation for more information.

Tests can be run with the test script, which will run tests against Lit's development mode (with more verbose errors) as well as against Lit's production mode:

npm test

For local testing during development, the test:dev:watch command will run tests in Lit's development mode (with verbose errors) on every change to the source files:

npm test:watch

Alternatively the test:prod and test:prod:watch commands will run tests in Lit's production mode.

Dev Server

This project uses modern-web.dev's @web/dev-server for previewing the project without additional build steps. Web Dev Server handles resolving Node-style "bare" import specifiers, which aren't supported in browsers. It also automatically transpiles JavaScript and adds polyfills to support older browsers. See modern-web.dev's Web Dev Server documentation for more information.

To run the dev server and open the project in a new browser tab:

npm run serve

There is a development HTML file located at /dev/index.html that can be viewed at http://localhost:8000/dev/index.html. Note that this command will serve the code using Lit's development mode (with more verbose errors). To serve the code against Lit's production mode, use npm run serve:prod.

Editing

If you use VS Code, we highly recommend the lit-plugin extension, which enables some extremely useful features for lit-html templates:

• Syntax highlighting
• Type-checking
• Code completion
• Hover-over docs
• Jump to definition
• Linting
• Quick Fixes

The project is setup to recommend lit-plugin to VS Code users if they don't already have it installed.

Linting

Linting of TypeScript files is provided by ESLint and TypeScript ESLint. In addition, lit-analyzer is used to type-check and lint lit-html templates with the same engine and rules as lit-plugin.

The rules are mostly the recommended rules from each project, but some have been turned off to make LitElement usage easier.

To lint the project run:

npm run lint

Formatting

Prettier is used for code formatting. It has been pre-configured according to the Lit's style.

Prettier has not been configured to run when committing files so be sure to run it before pushing any changes.

Static Site

This project includes a website generated with the TypeDoc documentation generator. The site is generated to the /docs directory and intended to be checked in so that GitHub pages can serve the site from /docs on the main branch.

To enable the site, go to the GitHub settings and change the GitHub Pages "Source" setting to "main branch /docs folder".

To build the site, run:

npm run docs

To serve the site locally, run:

npm run docs:serve

The site will usually be served at http://localhost:8000.

Bundling and minification

Bundling and minification is performed in a single step using Rollup. The follow commands will bundle and minify whatever code is already in the lib/ directory and place the bundled code in the file dist/web-components.min.js.

To bundle and minify the code, run:

npm run bundle

To automatically re-bundle when the code in the lib/ directory changes, run:

npm run bundle:watch