@startinblox/boilerplate 4.3.0 → 5.0.0

package/.gitlab-ci.yml

@@ -10,7 +10,7 @@ cache:
     - .npm/
 
 default:
-  image: node:22
+  image: node:24
 
 stages:
   - prepare
@@ -19,7 +19,7 @@ stages:
 
 prepare:
   stage: prepare
-  image: node:22
+  image: node:24
   before_script:
     - npm ci --cache .npm --prefer-offline
     - npm install -g semantic-release@24 @semantic-release/gitlab@13
@@ -37,7 +37,7 @@ prepare:
 test:
   stage: test
   image: 
-    name: cypress/included:15.5.0
+    name: cypress/included:15.9.0
     entrypoint: [""]
   before_script:
     - npm ci --cache .npm --prefer-offline

package/README.md

@@ -2,48 +2,57 @@
 
 ## Introduction
 
-This repository provides a boilerplate for developing Startin'blox web components. It streamlines the creation and deployment of web components, whether used independently or integrated with the Startin'blox ecosystem, including Lit, Startin'blox Core, Startin'blox Store, Startin'blox Router, and Startin'blox Orbit. The primary objective is to enable developers to concentrate on web component logic by abstracting common complexities and providing out-of-the-box functionalities.
+This repository provides a boilerplate for developing Startin'blox web components. It streamlines the creation and deployment of web components, whether used standalone or integrated within the Startin'blox ecosystem (Lit, Startin'blox Core, Store, Router, and Orbit). The primary objective is to enable developers to concentrate on web component logic by abstracting common complexities and providing essential functionalities out-of-the-box.
 
 ## Features
 
 This boilerplate includes:
 
-* **Localization:** Compatibility with platforms like Weblate, powered by [`@lit/localize`](https://www.npmjs.com/package/@lit/localize).
+* **Localization:** Supports internationalization with platforms like Weblate, powered by [`@lit/localize`](https://www.npmjs.com/package/@lit/localize).
 * **Data Management:** A comprehensive wrapper around the Startin'blox Store for simplified property handling (RDF or named).
 * **Component Awareness:** Mechanisms to manage race conditions and inheritance across external components.
 * **Helper Utilities:** Functions for data reactivity, filtering, and sorting.
 * **Development Tools:**
-  * **Storybook:** For component documentation and isolated development, reducing the need for a heavy local environment.
+  * **Storybook:** For isolated component development and documentation, reducing the need for a heavy local environment.
   * **Cypress:** For component testing.
   * **Unpluggin Icons:** Access to a vast library of icons from [Iconify](https://icon-sets.iconify.design/).
   * **Lit Integration:** Pre-made component classes to accelerate development.
-  * **Vite-powered:** Typescript, SASS, PostCSS, Autoprefixer... Focus on your component logic, not the build process.
-  * **BiomeJS:** For linting and formatting, preconfigured for Startin'blox JS styling, using the most [reasonable one](https://github.com/airbnb/javascript). Use [Biome](https://biomejs.dev/fr/) within your preferred editor.
+  * **Vite-powered:** Typescript, SASS, PostCSS and Autoprefixer, allowing you to focus on component logic rather than build configurations.
+  * **BiomeJS:** Preconfigured for Startin'blox JS styling, using the most [reasonable one](https://github.com/airbnb/javascript), for linting and formatting. Integrate [Biome](https://biomejs.dev/fr/) with your preferred editor.
 
-## Getting started
+## Quick Start for Developers
 
-### Creating a new components repository
+This section guides you through setting up the local development environment and using the boilerplate to create and test web components.
 
-To initialize a new component repository from this boilerplate:
+### Local Development Setup
+
+To get started with local development:
 
-1. Clone this repository.
-2. Rename the `origin` remote to `upstream`:
+1. **Clone the repository:**
 
     ```bash
-    git remote rename origin upstream
+    git clone https://git.startinblox.com/components/your-component-name.git
+    cd your-component-name
     ```
 
-3. Update the `name`, `description`, and `repository.url` fields in [`package.json`](package.json).
-4. Commit the changes with a `major: Initial commit` message.
-5. Create a new repository on [git.startinblox.com/components](https://git.startinblox.com/components/).
-6. Add the new repository as the `origin` remote:
+    *Note: If you are starting a new project from this boilerplate, refer to the "Developping new components from the boilerplate" section below.*
+
+2. **Install dependencies:**
 
     ```bash
-    git remote add origin https://git.startinblox.com/components/your-component-name.git
+    npm install
     ```
 
-7. Configure Gitlab settings (branch protection rules, FF merge only, clone instead of fetch).
-8. Push to `origin master`.
+3. **Run Storybook:**
+    Storybook is the primary development environment for isolated component development and documentation.
+
+    ```bash
+    npm run storybook
+    ```
+
+    This will open Storybook in your browser, typically at `http://localhost:6006`.
+
+### Using Your Components
 
 For production usage, components can be served via a CDN like JSDelivr or self-hosted.
 
@@ -60,18 +69,58 @@ For production usage, components can be served via a CDN like JSDelivr or self-h
   <!-- etc. -->
 ```
 
-### Installation
+## Developping new components from the boilerplate
 
-To set up the local development environment with Storybook:
+### Creating a New Component Repository
 
-```bash
-npm install
-npm run storybook
-```
+To initialize a new component repository from this boilerplate:
+
+1. **Clone this repository:**
+
+    ```bash
+    git clone https://git.startinblox.com/components/solid-boilerplate.git your-new-component-name
+    cd your-new-component-name
+    ```
 
-## Development environment
+2. **Rename the `origin` remote to `upstream`:**
 
-This boilerplate is designed as a **library** for multiple web components and intentionally **does not include** a default `index.html` file.
+    ```bash
+    git remote rename origin upstream
+    ```
+
+3. **Update project details:**
+    Modify the `name`, `description`, and `repository.url` fields in [`package.json`](package.json) to reflect your new component.
+
+4. **Initial commit:**
+    Commit the changes with a `major: Initial commit` message.
+
+5. **Create a new repository:**
+    Create a new repository on [git.startinblox.com/components](https://git.startinblox.com/components/).
+
+6. **Add the new repository as the `origin` remote:**
+
+    ```bash
+    git remote add origin https://git.startinblox.com/components/your-component-name.git
+    ```
+
+7. **Configure Gitlab settings:**
+    Set up branch protection rules, enforce FF merge only, and configure cloning instead of fetching in your new repository's Gitlab settings.
+
+8. **Push to `origin master`:**
+
+    ```bash
+    git push -u origin master
+    ```
+
+## Important Considerations
+
+This boilerplate is designed as a **library** for multiple web components and intentionally **does not include** a default `index.html` file. Developers should use Storybook for isolated component development.
+
+* **Avoid Blind Copy-Pasting:** Do not simply copy files without understanding their purpose. This boilerplate includes specific configurations and integrations (e.g., Orbit, localization) that may not be relevant to all projects. Always review and adapt the code to your specific needs.
+* **Understand Core Concepts:** Familiarize yourself with the "Core Concepts" section to understand how data management, component awareness, and helper utilities are implemented.
+* **Orbit Integration:** The `import @src/initializer;` statement is **only required if your component will be integrated with Startin'blox Orbit**. If you are not using Orbit, you **do not need** this import.
+
+## Development Environment
 
 **Storybook** is the primary development environment for isolated component development and documentation. **Cypress** is integrated for component testing.
 
@@ -236,15 +285,13 @@ npm run build-storybook
 npm run build
 ```
 
-## Orbit integration
+## Orbit Integration
 
 Components built with this boilerplate are designed to work seamlessly with Orbit without requiring specific configurations.
 
-To prevent potential race conditions, include `import @src/initializer;` at the top of your component's file, before the `@customElement` declaration.
-
-Application performance can be optimized by utilizing the `gatekeeper` method within your `OrbitComponent`'s render methods.
-
-Note that without a complete Orbit environment, interactions with external components (e.g., route management, component deduplication, global localization, conditional component display) may be limited.
+* **Initializer:** To prevent potential race conditions when integrating with Orbit, include `import @src/initializer;` at the top of your component's file, before the `@customElement` declaration. **This import is only necessary if your component will be used within an Orbit environment.**
+* **Performance Optimization:** Application performance can be optimized by utilizing the `gatekeeper` method within your `OrbitComponent`'s render methods.
+* **Limitations without Orbit:** Without a complete Orbit environment, interactions with external components (e.g., route management, component deduplication, global localization, conditional component display) may be limited.
 
 ## Best practices
 

package/biome.json

@@ -1,6 +1,6 @@
 {
   "root": false,
-  "$schema": "https://biomejs.dev/schemas/2.0.0/schema.json",
+  "$schema": "https://biomejs.dev/schemas/2.3.13/schema.json",
   "vcs": {
     "enabled": true,
     "clientKind": "git",