# Web Boilerplate

The boilerplate for the Xtra Preact Custom Elements.

## Introduction

This project contains everything needed to build a working Custom Element with
[Preact](https://preactjs.com/) & [TypeScript](https://www.typescriptlang.org/).

## 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:

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

Add a custom element with the required parameters from [the list](CUSTOM_ELEMENTS.md)

## Development

### Software dependencies

- [Node.JS](https://nodejs.org/en/) managed with [asdf](https://github.com/asdf-vm/asdf)
- [pre-commit](https://pre-commit.com/)

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](https://brew.sh/).

For windows devices, this can be installed using [Conda](https://docs.conda.io/en/latest/).
If a developer makes use of this, please be so kind to update the
[postinstall-local.sh](scripts/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](https://jestjs.io/) &
[Preact Testing Library](https://testing-library.com/docs/preact-testing-library/intro/),
in order to run the tests you can use the following commands:

```sh
npm run test

npm run test:coverage
```

### Building the application

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

```sh
npm run build
```

### Publishing the application

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

```console
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:

```text
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](https://atomicdesign.bradfrost.com/chapter-2/)

### Git Workflow

In order to contribute to this project, clone the project and create a new
branch following [this convention](https://dcsecosystem.atlassian.net/wiki/spaces/BKB/pages/37225687/Git#Branch-names).
When you're finished with your changes, you can create a PR.

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