SmartGridready Declaration Tool

A web-based editor for creating and editing SmartGridready device and functional profile XML declarations. This tool provides a form-based interface with validation, XML preview and import/export capabilities.

For more information about SmartGridready, visit the SGrSpecifications repository and smartgridready.ch.

Table of Contents

• Getting Started
• Project Overview
• Project Structure
• Used Libraries
• Commit Rules
• Releasing
• Pipeline and Deployment

Getting Started

1. Clone the repository

   git clone https://github.com/SmartGridready/SGrDeclarationTool.git

2. Install dependencies

   npm ci

3. Run the development server

   npm run dev

4. Open your browser

   Navigate to http://localhost:3000.

Available Commands

Command	Description
npm run dev	Start development server with Turbopack
npm run build	Build for production
npm run start	Start production server
npm run test	Run Jest tests
npm run lint	Run ESLint and Prettier checks
npm run format	Format code with Prettier
npm run format:check	Check code formatting

Project Overview

The src/ folder contains the following top-level directories:

• app/ - Next.js App Router pages and layouts for the main routes (devices, functional profiles)
• components/ - Reusable React components including editor dialogs, form inputs, navigation, and shadcn UI primitives
• constants/ - Constant values for error, info, and success messages used throughout the application
• hooks/ - Custom React hooks for file import/export, validation, debouncing, and XSL preview
• models/ - TypeScript type definitions for functional profiles and products
• sections/ - Form sections and related logic (builders, mappers, schemas, slices) for device and functional profile editors
• test/ - Jest test files for library API integration tests
• utils/ - Utility functions for XML building, mapping, validation, and other shared logic

Used Libraries

Dependencies

• Next.js - React framework for routing and optimization features
• React - Core React library for building user interfaces
• TypeScript - Typed superset of JavaScript for type safety
• Tailwind CSS - Utility-first CSS framework for styling
• Zustand - Lightweight state management solution
• xml2js - XML parser for SmartGridready declarations
• Shadcn UI - Reusable UI components built with Radix UI and Tailwind CSS
• Zod - TypeScript-first schema validation library
• Sonner - Toast notification library for React

Dev Dependencies

• ESLint & Prettier - Code linting and formatting
• Jest & Testing Library - Testing framework and utilities
• Husky - Git hooks for pre-commit checks
• standard-version - Automated versioning and changelog generation

Commit Rules

This project follows the Conventional Commits specification for commit messages.

Commit Message Format

Each commit message should follow this format:

<type>(<scope>): <subject> (GL-<Issue Number>)

• Type (required): The type of change being made
• Scope (optional): The area of the codebase affected
• Subject (required): A short, imperative description of the change
• Issue Number (optional but preferred): The linked Issue from GitLab

Example:

git commit -m "feat(api): change device endpoint structure (GL-99)"

Husky Pre-commit Checks

This project uses Husky to run automated checks before commits:

• Pre-commit hook: Runs npm run lint and npm run format:check
• Commit-msg hook: Validates commit messages follow the Conventional Commits specification

Releasing

Releases are performed manually using semantic versioning (patch, minor, major). The project uses standard-version.

1. Choose the release type and run the command

   Patch (0.2.0 → 0.2.1): Bug fixes, patches

   npm run release:patch

   Minor (0.2.0 → 0.3.0): New features, backwards compatible

   npm run release:minor

   Major (0.2.0 → 1.0.0): Breaking changes

   npm run release:major

   This will:

   • Bump the version in package.json
   • Generate/update CHANGELOG.md based on commit history
   • Create a git tag with the new version
   • Create a commit with the version bump and changelog

2. Push the release

   git push --follow-tags origin main

Docker

Build Image

docker build --rm -t sgr-declaration-tool:latest .

The Docker build process has 2 stages:

1. Build using NodeJS image
2. Copy to Nginx runtime image

Run

Run container:

docker compose up -d

Stop:

docker compose down

Pipeline and Deployment

Github

The Github CI/CD pipeline consists of three stages:

1. Lint: Runs npm run lint on all branches and commits
2. Test: Runs npm run test on all branches and commits
3. Build Runs npm run build on all branches and commits

Gitlab

The GitLab CI/CD pipeline consists of three stages:

1. Lint: Runs npm run lint on all branches and commits
2. Test: Runs npm run test on all branches and commits
3. Build Runs npm run build on all branches and commits