Otter Framework

Description

The Otter project is a highly modular framework whose goal is to provide a common platform to accelerate and facilitate the development on Angular web applications. It is split into several units to cover different aspects of these applications (localization, testing, customization, etc.). Also, to customize an application, metadata can be extracted from the application source code and injected into a CMS to manage dynamic configuration.

Tip

The full list of modules and their documentation is available in the /docs folder. An overview of the technical module interactions and the architecture of the dependencies is available in the architecture section.

A demonstration of a list of features provided by Otter is accessible on the showcase application.

Built With

• Angular
• Typescript
• RxJs
• Redux
• Sass
• Nx

Get Started

To set up a new Otter project with a monorepo structure, use the following simple command:

# Creating a new Otter monorepo
npm create @o3r my-project

Tip

Please refer to Otter Get Started and Angular Get Started for complete documentation.

Contributing

Please read the Contributing file for details on our code of conduct and the process to submit pull requests.

Versioning

Please refer to Security file.

License

Please refer to the License file.

Acknowledgments

The Otter Team, @AmadeusITGroup/otter_admins, is responsible for the review of the code of this repository. Any bug of feature request can be addressed via issue report.

Developer

Experimental

In this monorepo, certain APIs across all packages are marked with the @experimental tag in their TypeScript documentation (TSDoc). This tag highlights that these exports — whether classes, functions, types, or constants — are experimental and may change without warning.

What does @experimental mean?

• The marked APIs are not stable and can undergo breaking changes in future releases.
• Experimental features may be added, modified, or removed at any time.
• These APIs are intended for early adopters and should be used with caution.

What should you do?

• When using any @experimental APIs from any package in this monorepo, pin the package versions explicitly to avoid unexpected breaking changes.
• Regularly check release notes and changelogs for updates on experimental features.
• Treat these APIs as preview or evolving interfaces that may mature or be deprecated in upcoming versions.

Building and Testing library

These documents describe how to set up your development environment to build and test the framework. It also explains the basic mechanics of using git, node, and npm.

• Description
• Built With
• Get Started
• Contributing
• Versioning
• License
• Acknowledgments
• Developer
  • Building and Testing library
    • Prerequisite Software
    • Getting the sources
    • Installing NPM modules
    • Build command
    • Running tests locally
    • Manage task cache
    • Debugging with Visual Studio Code
    • Link local packages
    • SSL Certificate issue (behind proxy)

Refer to the contribution guidelines if you'd like to contribute to the framework.

Prerequisite Software

Before you can build and test Otter modules, you must install and configure the following products on your development machine:

• Git and/or the GitHub app (for Mac or Windows)

  • GitHub's Guide to Installing Git is a good source of information.

• Node.js, (version >=18.0.0)

  • This is used to run tests and generate distributable files. We strongly encourage to use an up-to-date LTS version of Node.js to ensure the support of all the Otter packages. Each package comes with a minimum Node.js version range defined in the engine property of its package.json file.

• Yarn, a Node's Package Manager

  • You can install yarn using NPM manager (coming with Node.js). The version of Yarn currently used is embedded in the repository and it can be installed using the provided Node.js corepack. In case you need to link this library with your project, you can check the section "Link local packages".

• Chrome

  • We use Chrome to run our tests.

Getting the sources

Clone the Otter repository using the button Code or using the following git command:

git clone https://github.com/AmadeusITGroup/otter.git

Installing NPM modules

Next, install the JavaScript modules needed to build:

# Install library project dependencies (package.json)
yarn install

Build command

To build the modules, run:

yarn run build

Each module can be built independently thanks to Nx commands:

# ex: Build Core package only
yarn nx build core

Note

Results are put in the dist of each module (packages/@<scope>/<module>/dist).

Running tests locally

Check the formatting:

yarn run lint

Check Unit Tests:

yarn run test

Check Integration Tests:

yarn run test-int

Verdaccio is used to run the integration tests as close as possible to a real npm publication.

Each module can be tested independently thanks to Nx commands:

# ex: Test Core package only
yarn nx test core

# ex: Lint Core package only
yarn nx lint core

Manage task cache

When running the Build, Lint, or Test commands, Nx can use its cache mechanism. In some cases, it may be useful to clear the cache to investigate an issue. This can be done with the following command:

yarn nx reset

Debugging with Visual Studio Code

The repository contains the mandatory configuration and the recommended VSCode plugins to ensure optimal comfort and productivity while developing on the Otter Framework.

The default configuration of the repository provides a way to run Unit Tests one by one and to define, within VSCode, break points using the vscode-jest-tests debugger task.

Link local packages

For Yarn v1, add the resolutions property in the main package.json. It should be filled with the relative path to the dist of the local packages you want to link. The protocol link: can be used.

NOTE: It will not import the transitive dependencies of the linked packages.

Example:

{
  "resolutions": {
    "@o3r/localization": "./relative/path/to/otter/packages/@o3r/localization/dist",
    "@o3r/core": "link:./relative/path/to/otter/packages/@o3r/core/dist",
  }
}

For Yarn v2+, the protocol portal: can also be used.

NOTE: The portal protocol will also import all the transitive dependencies of the linked packages. Please keep in mind that mismatched versions of these dependencies may cause some issues.

Example:

{
  "resolutions": {
    "@o3r/localization": "./relative/path/to/otter/library/@o3r/localization/dist",
    "@o3r/core": "link:./relative/path/to/otter/library/@o3r/core/dist",
    "@o3r/rules-engine": "portal:./relative/path/to/otter/library/@o3r/rules-engine/dist",
  }
}

SSL Certificate issue (behind proxy)

Due to proxy redirection you may face an SSL certificate issue on Yarn when installing the Otter project locally:

Request Error: self-signed certificate in certificate chain

To solve this, you can provide your own certificate in two different ways:

• Specify your certificate path in the Environment Variable NODE_EXTRA_CA_CERTS.
• Specify your certificate path in the Yarn configuration httpsCertFilePath.