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!

Getting Started

Quick contribution install: Dev Containers

HAXTheWeb is dedicated to making contribution an accessible and simple experience. That's why we prepare an environment tailored with the right tools for getting started! Our project follows the Dev Container specification to provide a consistent, UX-focused experience across operating systems.

Install Docker (or another container runtime)
- Windows
  - Ensure that you select the WSL 2 Backend option
- macOS
- Linux
- Dev Containers are broadly supported across OCI-compliant runtimes like Docker, Podman, and OrbStack.

After this step you're ready to go, no fiddling with the command line! Clone the project, open your IDE, accept our recommended extensions, then select Reopen in Container!

Manual Quick Install: Git Bash/WSL/macOS/Linux

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.

You can also install the webcomponents monorepo natively. Use our onboarding script or follow the manual steps below:

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

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

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 global add symlink-dir
yarn global add @web/test-runner
yarn global add @web/test-runner-commands
yarn global add @web/test-runner-puppeteer
yarn global add @web/test-runner-playwright
yarn global add lerna
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 Support

Git Bash or Windows Subsystem for Linux (WSL) are recommended for the best cross-compatibility with HAX's developer tooling. We also support PowerShell for Windows contributors, although certain utilities may experience instability.

Windows Developer Mode

The monorepo uses symlinks in many parts of its local environment. This allows us to emulate the functionality of a live HAXsite without running the full system. On Windows, symlinks normally require running the shell as Administrator.

Enabling Developer Mode removes this Administrator requirement for common development tasks. Start by opening your Windows Settings:

On Windows 10: Update and Security -> For developers -> Developer Mode
On Windows 11: System -> Advanced -> For developers -> Developer Mode

Quick Install: Windows

irm https://raw.githubusercontent.com/haxtheweb/webcomponents/master/scripts/haxthewebme.ps1 | iex

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 --sa

Webcomponents

Install / Use

README