Working with Client Projects

Client projects are created and managed using the yuuvis client CLI, a command-line tool that streamlines development, building, and deployment of yuuvis shell applications. Using the CLI ensures consistency and compatibility with the yuuvis shell platform.

Creating a New Client Project

Create a new client project by running:

yuv new myclient

This generates a directory named myclient with the complete project structure and configuration files required for development.

During initialization, the CLI prompts you to select a shell version. You can specify:

• An exact version number (e.g., 2.0.5) for precise version control
• A release channel (latest or stable) for automatic version resolution

Release channels are resolved to a concrete version at the time of execution, allowing you to leverage tested releases without manually tracking version numbers.

Updating the Shell

Keeping your shell libraries up to date ensures you have access to the latest features, bug fixes, and security patches. There are two approaches to updating shell dependencies in your project.

Using the Update Script (Recommended)

The simplest method is to use the provided npm script, which updates all shell libraries to a specified version in one command:

npm run update:shell -- 2.6.0

This script automatically updates @yuuvis/client-core, @yuuvis/client-shell-core, @yuuvis/client-framework, @yuuvis/client-shell, and @yuuvis/material to the specified version, ensuring consistency across all shell libraries.

Manual Update

Alternatively, you can manually update each library using npm. When updating manually, execute the commands in the following order to respect the dependency graph:

npm install @yuuvis/client-core@2.6.0
npm install @yuuvis/client-shell-core@2.6.0
npm install @yuuvis/material@2.6.0
npm install @yuuvis/client-framework@2.6.0
npm install @yuuvis/client-shell@2.6.0

This sequence ensures that foundation libraries are updated first, followed by libraries that depend on them, preventing version conflicts.

Version Consistency

Always update all shell libraries to the same version. Mixing different versions can lead to compatibility issues and unexpected behavior.

Creating a New App

Create a new app by running:

yuv generate app myapp

The CLI will prompt you for additional configuration parameters to set up your app, such as the app title, identifier, and routing options.

Importing an Existing App

To integrate a published app that was developed outside your project, use the add command:

yuv add app @yuuvis/app-drive

This command installs the app package as a dependency and integrates it into your client application.

Project Structure

A generated client project follows a structured Angular workspace layout, combining standard Angular conventions with yuuvis-specific configurations.

myclient/
├── src/                          # Host application
│   ├── app/                      # Application root
│   ├── assets/_yuuvis/           # yuuvis configuration and theming
│   │   ├── config/               # Shell configuration files
│   │   └── theme/                # Theme assets (icons, logos, CSS)
│   ├── environments/             # Environment configurations
│   └── styles/                   # Global stylesheets
├── projects/                     # App libraries workspace
│   └── myapp/                    # Your application library
│       ├── src/                  # Application source code
│       │   ├── lib/              # Components, services, routing
│       │   └── assets/           # App-specific assets
│       ├── extensions/           # Optional shell extensions
│       ├── shared/               # Shared library code
│       └── yuv-manifest.json     # App manifest configuration
├── scripts/                      # Build and maintenance scripts
├── angular.json                  # Angular workspace configuration
├── package.json                  # Package configuration
└── tsconfig.json                 # TypeScript configuration

Host Application (src/)

The host application bootstraps the yuuvis shell and provides the runtime environment. It contains:

• Global configuration in assets/_yuuvis/config/
• Theming assets including logos, icons, and custom CSS
• Environment-specific settings for development and production

App Library (projects/myapp/)

Your app code resides in an Angular library within the workspace. This structure enables:

• Modular, reusable components and services
• Independent versioning and packaging with ng-packagr
• Clear separation between application logic and shell infrastructure

App Manifest (yuv-manifest.json)

The manifest file defines how your application integrates with the shell:

{
  "id": "com.example.myapp",
  "title": "Myapp Title",
  "ui": {
    "path": "myapp",
    "iconName": "logo_dev",
    "requires": ["osdrive"]
    "routes": "MyappRoutes",
    "options": {
      "appHeader": false,
      "hideFromNav": false
    }
  },
  "extension": "MyappExtension"
}

For a comprehensive reference of all manifest properties and configuration options, see the App Manifest documentation.

Keep your manifest synchronized

The App Manifest defines the configuration that will be used when your app is published and installed in other client projects. Always keep the manifest synchronized with your app’s actual configuration—update it whenever you change routes, UI options, or extension settings to ensure your published app integrates correctly in host applications.

Package Configuration (package.json)

The root-level package.json defines the project’s dependencies and npm scripts:

• Dependencies: All yuuvis shell libraries (@yuuvis/client-core, @yuuvis/client-shell-core, etc.) and Angular packages
• Scripts: Development commands for building, serving, testing, and maintaining the project
• Shell updates: The update:shell script allows updating all yuuvis libraries to a specific version

TypeScript Configuration (tsconfig.json)

The root tsconfig.json contains path mappings that define import aliases for your app library:

{
  "compilerOptions": {
    "paths": {
      "myapp": [
        "./projects/myapp/src/public-api.ts"
      ],
      "myapp/shared": [
        "./projects/myapp/shared/src/index.ts"
      ],
      "myapp/extensions": [
        "./projects/myapp/extensions/src/index.ts"
      ]
    }
  }
}

These path mappings map library names to their entry points, enabling clean imports throughout your project, e. g.:

import { MyappComponent } from 'myapp';
import { SharedService } from 'myapp/shared';
import { MyappExtension } from 'myapp/extensions';

The CLI automatically updates these path mappings when you generate a new app in the project, ensuring that TypeScript can resolve the imports correctly.

Build Scripts

The scripts/ directory contains automation tools:

• update-shell.js - Updates shell dependencies to a specified version
• i18n-extract.js / i18n-collect.js - Internationalization workflow
• extract-client-version.js / extract-component-data.js - Collects the client’s version number as well as dependency and library metadata for About/License information

Building a Docker Image

When deploying the yuuvis client application to the yuuvis MOMENTUM ecosystem, it needs to be packaged as a Docker container. Since version 19.8, the yuuvis client CLI automatically generates the necessary files to build a Docker image for your client application.

Generated Docker Configuration

The CLI creates the following files when generating a new project:

• Dockerfile - Located in the project root directory
• nginx configuration - Located in misc/nginx/default.conf

The Dockerfile uses the official nginxinc/nginx-unprivileged base image and copies the built Angular application into the directory served by nginx.

Customizing Docker configuration

The generated Dockerfile and nginx configuration are generic templates that can be customized according to your application’s specific requirements. It is recommended to carefully review and adjust the configuration to ensure it meets your application’s security and performance needs.

Patching Older Projects

If your project was created with yuuvis client CLI version earlier than 19.8.0, it may be missing the Docker configuration files. Starting with shell version 19.8.0, you can add these resources to your existing project using the patch command:

yuv patch apply p0003

This patch automatically generates the missing Docker-related resources in your project, including:

• The Dockerfile in the project root
• The nginx configuration in misc/nginx/default.conf
• The build:docker npm script in package.json

The patch is idempotent—it only adds resources that are missing from your project, leaving existing customized files untouched.

Docker Build Script

The CLI automatically generates an npm script to build the Docker image:

{
  ...
  "scripts": {
    ...
    "build:docker": "npm run build && docker build -t client:latest ."
    ...
  }
  ...
}

This script creates a Docker image named client with the tag latest. This command first executes the standard Angular build process to compile the client application, then runs the Docker build process to create the Docker image. You can customize the image name and tag to identify different versions or environments.

Building the Docker Image

To build the Docker image, run:

npm run build:docker

Prerequisites

Ensure that Docker is installed and properly configured on your system before running the build script.

Deploying the Docker Image

Once built, the Docker image can be deployed using:

• A Docker registry (e.g., Docker Hub, private registry)
• Container orchestration tools like Kubernetes or Docker Swarm

Runtime requirements

While you can start the built Docker container locally, the client application running inside requires access to the yuuvis MOMENTUM API to function correctly. The container must be deployed within the yuuvis MOMENTUM cluster to have proper API access.