Web Boilerplate

The boilerplate for the Xtra Preact Custom Elements.

Introduction

This project contains everything needed to build a working Custom Element with Preact & TypeScript.

Using a custom element on a website

As these elements are supposed to be used inside a normal HTML context, the person implementing these can follow these steps in order to get a running app.

Add the stylesheet & script tag at the top of the page with:

<link href="style.css" rel="stylesheet" />
<script src="xtra-web.js"></script>

Add a custom element with the required parameters from the list

Development

Software dependencies

• Node.JS managed with asdf
• pre-commit

It is important to note that a postinstall script will run after the installation process in order to install the pre-commit hook. If you (the developer) do not have this installed, it will try to install pre-commit using brew.

For windows devices, this can be installed using Conda. If a developer makes use of this, please be so kind to update the postinstall-local.sh script 😊.

Installation proces

• Clone this repository
• Run asdf install to get the right version of Node & npm
• Run npm install to install the required dependencies
• Run npm run dev to get a working example at localhost:1234

Testing and build the application

Testing the application

Test are run with Jest & Preact Testing Library, in order to run the tests you can use the following commands:

npm run test

npm run test:coverage

Building the application

In order to get a production ready build, you can run the following command:

npm run build

Publishing the application

In order to publish a new version on npm, run the following command:

npm run release -- --release-as <majore|minor|patch>

git push --follow-tags origin main

Contributing

Folder Structure

When creating a new Custom Element it is important to follow the following directory structure to ensure parity within the codebase:

Profile (Custom Element)
 ┣ Statistics (feature inside Profile)
 ┃ ┗ Overview (Page)
 ┃ ┃ ┣ hooks (hooks used for this page)
 ┃ ┃ ┣ Overview.module.css
 ┃ ┃ ┣ Overview.test.tsx
 ┃ ┃ ┗ index.tsx
 ┃ ┣ GraphQL (Generated GraphQL)
 ┃ ┃ ┣ Statistics.generated.ts
 ┃ ┃ ┗ Statistics.ts
 ┃ ┣ Statistics.module.css
 ┗ index.tsx

As these Custom Elements will also make use of common components, suchs as buttons, form elements, etc., these elements should be placed inside the common folder. In order to structure these, we make use of atomic design

Git Workflow

In order to contribute to this project, clone the project and create a new branch following this convention. When you're finished with your changes, you can create a PR.

Make sure to follow the styleguide provided with ESLint, Prettier and StyleLint!