webcomponents

Monorepo of all web components built as part of the HAX ecosystem, many working stand-alone.

HAX

The authoring experience of HAX and the ability to make fast, static file backed websites rapidly. Get all the details you want on HAX docs! HAX seeks to be the smallest possible back-end CMS to make HAX work and be able to build websites with it. Leveraging JSON Outline Schema, HAX is able to author multiple pages, which it then writes onto the file system. This way a slim server layer is just for basic authentication, knowing how to save files, and placing them in version control.

Watch and Learn more about HAX here:

• Try Hax: https://hax.cloud
• HAXCellence https://haxtheweb.org/what-is-hax
• Youtube channel - https://www.youtube.com/@haxtheweb

Issues / Support / Community

• Discord Channel - https://bit.ly/hax-discord
• Unified issue queue - https://github.com/haxtheweb/issues/issues
• Using Merlin directly in any HAX spaces and type "Issue" to jump start a report!

Related links and tech

• HAXcms (NodeJS)
• HAXcms (PHP)
• Storybook docs
• HAX [dot] PSU
• HAX doc site
• HAX + 11ty

Welcome to the haxtheweb project!

Web components that can work in just about anything, are very small (Vanila or Lit based) and have full on authoring solutions if you dig deeper; Enjoy!

Quick start

Notice: You will need to use Node version 6.0 or higher. Verify that you have yarn enabled — if not install yarn globally. These web components are written in ES6 and build routines compile to es5 to encompass legacy browsers.

Quick Install

curl -fsSL https://raw.githubusercontent.com/haxtheweb/webcomponents/master/scripts/haxthewebme.sh -o haxthewebme.sh && sh haxthewebme.sh

Manual Install (as a core dev, forks preferrable)

git clone https://github.com/haxtheweb/webcomponents.git
cd webcomponents
npm install --global @haxtheweb/create
yarn global add web-component-analyzer
yarn install

Lerna

This monorepo has configuration settings for lerna. Lerna is for the core team, but to bulk run commands against the monorepo consider things like npx lerna run build to run build against all elements. This is useful when getting ready to ship.

Syncing Your Fork

git remote add upstream https://github.com/haxtheweb/webcomponents.git
git fetch upstream
git pull

Windows Install

Installing Windows Subsystem for Linux (WSL)

Windows Subsystem for Linux (WSL) is required for this setup. To install WSL, run the following command in Command Prompt or PowerShell:

wsl --install

Installing Node.js in WSL

Refer to the official Windows guide: Install Node.js on Windows Subsystem for Linux (WSL2)

Installing Yarn in WSL

To install Yarn, open WSL and run:

curl -o- -L https://yarnpkg.com/install.sh | bash

To install Yarn globally, restart WSL and run:

npm install --global yarn

To verify installation, run:

yarn --version

Clone and Set Up webcomponents in WSL

Run this configuration in WSL to properly configure git endlines for Windows:

git config --global core.autocrlf true

Install bzip2 (required to required to extract PhantomJS during installation):

sudo apt install bzip2

To clone webcomponents, run:

git clone https://github.com/haxtheweb/webcomponents.git
cd webcomponents
npm install --global @haxtheweb/create
yarn global add web-component-analyzer
yarn install

To work on any element in our repo

cd elements/ELEMENTNAME
yarn start

Edit files in lib/, src/, locales/ and demo/ in order to modify the element to contribute back to us via PR.

Scripts

• hax webcomponent my-element --y
  • Run HAX CLI to create a new web component
• yarn test
  • Run tests on ALL webcomponents.
• yarn run build
  • Run build on ALL webcomponents.
• yarn run gallery
  • Run component gallery (replaces storybook)
• yarn run build-gallery
  • Build component gallery for deployment

Web Component development

Because this is a monorepo, each web component will need to be independently built in order to actively work on and preview the changes. Every web component has its own Gulp file and Yarn/NPM script.

While still running yarn start in one terminal window (which runs the local server), you will need to open another terminal window, drill into the directory of the web component you'd like to work on, and execute the yarn run dev command. This command will use gulp tasks to watch the files within that web component directory and will automatically re-run the build command and refresh the browser when you make changes to the web component.

Working on elements (new-element)

Run hax webcomponent to make a new element. Go to the new element following the directions generated at the end of the element's creation. To work on the new-element run yarn start from it's directory. If you are pulling in another element to use, run yarn add projectname --save or edit the package.json file local to the element you are working on. ALWAYS INSTALL FROM THE REPO ROOT, NOT THE ELEMENT YOU ARE WORKING ON

Example development on a web component

cd /Sites/webcomponents
yarn start

# SHIFT + CTRL + T to open a new tab in Terminal

cd elements your-card  # or any other web component
yarn run dev

Make a change to the web component and save. The gulpfile will handle transpiling the element down to ES5 and will bring in the HTML and Sass into the template in the web component.

Test

To test all webcomponents, run yarn test from the root of the repo. If you only want to test the web component you're working on:

cd elements/your-card
yarn test

Also, if your tests are failing and you want access to a live browser to investigate why, the following flag will keep the browser open.

yarn test -- -p

Then open the URL that will be printed in the terminal. It looks something like this: http://localhost:8081/components/@@haxtheweb/haxtheweb/generated-index.html?cli_browser_id=0.

Component Gallery

We've replaced Storybook with our own Component Gallery to preview and document our web components. The Component Gallery provides a better integrated experience with HAX design system and build tools.

To run the component gallery locally

yarn run gallery

This will build the gallery and start a web server. Navigate to the URL shown in the terminal to see the Component Gallery in action. The gallery will automatically rebuild when components change.

To build the component gallery for deployment

yarn run build-gallery

This generates the component gallery as a single HTML file: component-gallery.html.

Component Gallery Features

• HAX Integration: Built-in support for HAX-enabled components
• DDD Design System: Uses our Design, Develop, Destroy design tokens
• Live Demos: Interactive component demonstrations
• CodePen Export: Direct export to CodePen for experimentation
• Search & Filter: Easy component discovery
• Mobile Responsive: Works on all device sizes

Tech Stack

Client: JavaScript, LitElement, Lit(https://lit.dev/)

Server: Node.js

Contributing

Contributions are always welcome!

Active contributors

• @btopro

Additional contributions

Past contributors, student and larger community, can be found here: https://github.com/haxtheweb/webcomponents/graphs/contributors