Merge pull request #179 from Loxeris/feat_extensions

feat: extensions

.github/workflows/basic.yml

@@ -22,6 +22,9 @@ jobs:
           cache: 'npm'
       - name: Install dependencies
         run: npm ci
+
+      - name: Build Library
+        run: npm run build-lib
 
       - name: Check formatting rules
         run: npx prettier . --check

.github/workflows/deployment.yml

@@ -28,6 +28,51 @@ jobs:
           config-file: release-please-config.json
           manifest-file: .release-please-manifest.json
 
+  build-deploy-library-package:
+    runs-on: ubuntu-latest
+    needs: release-please
+    if: ${{ github.event_name == 'push' && github.repository == 'DIRACGrid/diracx-web' && needs.release-please.outputs.release_created == 'true' }}
+    permissions:
+      contents: read
+      packages: write
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: actions/setup-node@v4
+      with:
+        node-version: 'latest'
+        registry-url: 'https://registry.npmjs.org'
+
+    - name: Install dependencies
+      run: npm ci
+
+    # Release Please has already incremented versions and published tags, so we just
+    # need to publish all unpublished versions to NPM here
+    - name: Publish to NPM
+      env:
+        NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}
+      run: npx lerna publish from-package --no-push --no-private --yes
+
+  build-deploy-storybook-docs:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      pages: write
+    if: ${{ github.event_name == 'push' && github.repository == 'DIRACGrid/diracx-web' && github.ref_name == 'main'}}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 'latest'
+          cache: 'npm'
+
+      - uses: bitovi/[email protected]
+        with:
+          build_command: npm run build-storybook -w @dirac-grid/diracx-web-components
+          path: packages/diracx-web-components/storybook-static
+          checkout: false
+
   build-deploy-dev-image:
     runs-on: ubuntu-latest
     if: ${{ github.event_name != 'push' || github.repository == 'DIRACGrid/diracx-web' }}
@@ -56,6 +101,7 @@ jobs:
 
   build-deploy-release-image:
     runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' && github.repository == 'DIRACGrid/diracx-web' }}
     needs: release-please
     steps:
       - uses: actions/checkout@v4
@@ -79,4 +125,31 @@ jobs:
           context: .
           push: true
           tags: ghcr.io/diracgrid/diracx-web/static:${{ needs.release-please.outputs.tag_name }}
+          platforms: linux/amd64,linux/arm64
+
+  build-deploy-gubbins-image:
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' && github.repository == 'DIRACGrid/diracx-web' }}
+    needs: build-deploy-library-package
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to GitHub container registry
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Build Docker image (extension example)
+        uses: docker/build-push-action@v6
+        with:
+          context: ./packages/extensions
+          push: ${{ github.event_name == 'push' && github.repository == 'DIRACGrid/diracx-web' && github.ref_name == 'main' }}
+          tags: ghcr.io/diracgrid/diracx-web/static:extension-example
           platforms: linux/amd64,linux/arm64

.gitignore

@@ -12,6 +12,9 @@
 /.next/
 /out/
 
+# Nx
+.nx
+
 # production
 /build
 
@@ -35,4 +38,4 @@ yarn-error.log*
 next-env.d.ts
 
 # eslint
-.eslintcache
+.eslintcache

.husky/pre-commit

@@ -1,4 +1,4 @@
 #!/bin/sh
 . "$(dirname "$0")/_/husky.sh"
 
-npx lint-staged
+npx lerna exec -- npx lint-staged

.prettierignore

@@ -4,6 +4,19 @@ dist
 public
 .github
 jest.config.mjs
-release-please-config.json
-.release-please-manifest.json
-CHANGELOG.md
+
+packages/*/node_modules
+packages/*/build
+packages/*/dist
+packages/*/public
+packages/*/.github
+packages/*/jest.config.mjs
+packages/*/tsconfig.json
+packages/*/tsup.config.ts
+packages/*/.next
+packages/*/.tsup
+packages/*/out
+
+**/release-please-config.json
+**/.release-please-manifest.json
+**/CHANGELOG.md

.release-please-manifest.json

@@ -1 +1,6 @@
-{".":"0.1.0-a1"}
+{
+  ".": "0.1.0-a1",
+  "packages/diracx-web": "0.1.0-a1",
+  "packages/diracx-web-components": "0.1.0-a1",
+  "packages/diracx-web-extension-example": "0.1.0-a1"
+}

CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing to This Project
+
+Thank you for your interest in contributing to our project! We appreciate all contributions, big and small. Below are some guidelines to help you get started.
+
+## Bug reporting and discussions
+
+- Want to report a bug?
+  Open an [Issue](https://github.com/DIRACGrid/diracx-web/issues).
+- Need technical support to configure `diracx-web`?
+  Start a [Support discussion](https://github.com/DIRACGrid/diracx-web/discussions/categories/support).
+
+- Want to make a general feedback about the [DIRAC web application](https://github.com/DIRACGrid/WebAppDIRAC)?
+  Answer to the [Survey](https://github.com/DIRACGrid/diracx-web/discussions/categories/surveys) by creating a new discussion.
+- Want to request a feature?
+  Create a [User Story](https://github.com/DIRACGrid/diracx-web/discussions/categories/user-personas-and-stories) to describe your need.
+- Want to discuss about UX/UI design?
+  Share your [Design idea](https://github.com/DIRACGrid/diracx-web/discussions/categories/design-ideas).
+
+## How to Contribute
+
+### 1. Opening an Issue
+
+- **Discuss Before Implementing:** Before making a pull request (PR), especially for non-trivial changes, please [open an issue](https://github.com/DIRACGrid/diracx-web/issues) to discuss your idea. This ensures that everyone is aligned on the proposed change.
+- **Check for Existing Issues:** Before opening a new issue, please check if a similar issue already exists. If a similar issue exists, consider contributing to the discussion there instead.
+
+### 2. Making Changes
+
+- **Code Documentation:** Ensure that any code you write is well-documented. This includes:
+  - Inline comments where necessary to explain complex logic.
+  - Updating or creating Storybook documentation if you are contributing to the `diracx-web-components` library.
+- **Writing/Updating Tests:** When you change or add new code, make sure to write or update tests accordingly. This helps maintain the reliability and stability of the codebase.
+- **Helping with Existing Issues:** If you want to start contributing right away, check out the issues labeled with ["good first issue"](https://github.com/DIRACGrid/diracx-web/labels/good%20first%20issue). These are issues that are well-suited for newcomers to the project.
+
+### 3. Commit Messages
+
+- **Conventional Commits:** All commits must follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. This ensures that commit messages are structured and consistent, which is important for automation and versioning.
+  - **Examples:**
+    - `feat(ui): add new button component`
+    - `fix(api): handle null values in response`
+    - `docs(readme): update contributing guidelines`
+  - **Why?** If your commit messages do not follow this convention, the Continuous Integration (CI) process will fail, and your PR will not be merged. Please ensure your commit messages are properly formatted before pushing.
+
+### 4. How to Make a Pull Request (PR)
+
+- **Fork the Repository:** Start by forking the repository and creating a new branch for your work. Use a descriptive name for your branch that reflects the work you're doing.
+- **Make Your Changes:** Commit your changes with clear and concise commit messages following the Conventional Commits format.
+- **Update Documentation and Tests:** As mentioned, ensure all relevant documentation and tests are updated to reflect your changes.
+- **Submit Your PR:** When you’re ready, submit your pull request. Please include a clear description of what your PR does and reference the issue number it addresses (if applicable).
+- **Review Process:** Your PR will be reviewed by project maintainers. Please be patient and responsive to any feedback you receive.
+
+### 5. Updating Storybook Stories
+
+If your changes affect the `diracx-web-components` library, you may need to update or add new Storybook stories to ensure components are well-documented and tested visually.
+
+- **Add New Stories:** If you’ve created a new component, add a corresponding Storybook story in the appropriate directory. This story should be placed inside a `*.stories.tsx` file alongside your new component.
+- **Update Existing Stories:** If your changes modify the behavior or appearance of an existing component, make sure to update its Storybook story accordingly.
+- **Run Storybook Locally:** Before submitting your PR, run Storybook locally to ensure that your changes are reflected correctly. You can do this by running `npm run storybook` in the `packages/diracx-web-components` directory.
+
+You can check the existing stories and the [Storybook documentation](https://storybook.js.org/docs) for more details on how to use Storybook.
+
+### 6. Additional Notes
+
+- **Trivial Changes:** For minor changes like fixing typos, feel free to skip the issue creation step and go straight to making a PR.
+- **Stay Up-to-Date:** Make sure your branch is up-to-date with the latest changes in the main branch before submitting your PR. Use `git rebase` if necessary.
+- **Project Setup:** See the README for instructions on how to set up the project and run tests locally.
+
+Thank you again for your contributions! We look forward to working with you.

Dockerfile

@@ -4,11 +4,10 @@
 # Stage 1: Build the Next.js application
 FROM node:alpine AS build
 WORKDIR /app
+# Copy the application to the working directory
+COPY . .
 # Install the project dependencies
-COPY package*.json ./
 RUN npm ci
-# Copy the rest of the application to the working directory
-COPY . .
 # Build the static export with telemetry disabled (https://nextjs.org/telemetry)
 RUN NEXT_TELEMETRY_DISABLED=1 npm run build
 

README.md

@@ -5,6 +5,36 @@
 
 # DiracX-Web
 
+## Overview
+
+`diracx-web` is a web application that provides a user interface to interact with the [DiracX](https://github.com/DIRACGrid/diracx) service and is part of the [DIRAC](https://github.com/DIRACGrid) ecosystem.
+
+This repository is organized as a monorepo, with the following key packages:
+
+- [diracx-web](packages/diracx-web)
+- [diracx-web-components](packages/diracx-web-components)
+- [extensions](packages/extensions)
+
+![Architecture diagram](docs/architecture_overview.png)
+
+### Packages
+
+- **DiracX-Web**: Vanilla Dirac web interface based on Next.js. Leverages components from `DiracX-Web-Components` to provide core functionalities.
+
+- **DiracX-Web-Components**: A library of reusable React components designed for integration within the `DiracX-Web` package and to facilitate the creation of custom DiracX web extensions.
+
+- **Extensions**: An illustrative example of a web extension demonstrating how to extend the functionality of `DiracX-Web` using the components from the `DiracX-Web-Components` package.
+
+### Project Management
+
+- [**Lerna**](https://lerna.js.org/docs/introduction): Utilized for efficient monorepo management. Useful to run scripts or commands across all packages while handling errors correctly.
+- [**npm**](https://docs.npmjs.com/): Used for dependency management.
+- [**Release-Please**](https://github.com/googleapis/release-please): Automated release management for the project.
+
+The dependency management is further detailed in the [Package Management](docs/package-management.md) documentation.
+
+For more detailed and interactive documentation, visit our [Storybook](https://diracgrid.github.io/diracx-web) instance.
+
 ## Getting started
 
 _Requirements: docker, internet_
@@ -34,17 +64,7 @@ diracx-charts/run_demo.sh ./diracx-web
 
 ## Contributing
 
-- Want to report a bug?
-  Open an [Issue](https://github.com/DIRACGrid/diracx-web/issues).
-- Need technical support to configure `diracx-web`?
-  Start a [Support discussion](https://github.com/DIRACGrid/diracx-web/discussions/categories/support).
-
-- Want to make a general feedback about the [DIRAC web application](https://github.com/DIRACGrid/WebAppDIRAC)?
-  Answer to the [Survey](https://github.com/DIRACGrid/diracx-web/discussions/categories/surveys) by creating a new discussion.
-- Want to request a feature?
-  Create a [User Story](https://github.com/DIRACGrid/diracx-web/discussions/categories/user-personas-and-stories) to describe your need.
-- Want to discuss about UX/UI design?
-  Share your [Design idea](https://github.com/DIRACGrid/diracx-web/discussions/categories/design-ideas).
+See the [Contributing guidelines](/CONTRIBUTING.md)
 
 ## Testing
 

cypress.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from "cypress";
 
 export default defineConfig({
   e2e: {
-    specPattern: "test/e2e/**/*.cy.ts",
+    specPattern: "packages/*/test/e2e/**/*.cy.ts",
     supportFile: false,
     setupNodeEvents(on, config) {
       // implement node event listeners here

docs/package-management.md

@@ -0,0 +1,28 @@
+# Package Management in the Monorepo
+
+## Using Local Packages
+
+When working on `diracx-web`, the monorepo configuration ensures that related packages (`diracx-web-components`) are automatically used from their local versions instead of fetching them from the npm registry. This setup allows developers to see the latest changes in real-time, so that any updates or modifications to these packages are immediately reflected in the `diracx-web` application during development.
+
+This approach streamlines the development process, reduces the need for frequent publishing to npm, and ensures consistency across the project.
+
+### Configuration
+
+Our monorepo is configured to use npm workspaces, which allows us to specify the projects and packages that should be linked locally.
+
+From the [npm documentation](https://docs.npmjs.com/cli/v10/using-npm/workspaces):
+
+> Workspaces is a generic term that refers to the set of features in the npm cli that provides support for managing multiple packages from your local file system from within a singular top-level, root package.
+>
+> This set of features makes up for a much more streamlined workflow handling linked packages from the local file system. It automates the linking process as part of npm install and removes the need to manually use npm link in order to add references to packages that should be symlinked into the current node_modules folder.
+
+**Example `package.json` Configuration:**
+
+```json
+{
+  "workspaces": ["packages/diracx-web-components", "packages/diracx-web"]
+}
+```
+
+Note that any packages not listed in the `workspaces` (i.e. `extensions` here) array are not considered workspaces. They will not be managed from the root of the monorepo and will not have access to the linked packages in the root `node_modules`, hence they will fetch them from the npm registry.
+Additionally, these packages will have their own `node_modules` folder.

lerna.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "node_modules/lerna/schemas/lerna-schema.json",
+  "version": "0.0.0"
+}