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.
A new application can be set up with this simple command:
# Starting a new Otter application
npm create @o3r my-app
Tip
Please refer to Otter Get Started and Angular Get Started for complete documentation.
Please read the Contributing file for details on our code of conduct and the process to submit pull requests.
Please refer to Security file.
Please refer to the License file.
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.
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
.
Refer to the contribution guidelines if you'd like to contribute to the framework.
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.
- 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
-
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".
-
- We use Chrome to run our tests.
Clone the Otter repository using the button Code
or using the following git command:
git clone https://github.com/AmadeusITGroup/otter.git
Next, install the JavaScript modules needed to build:
# Install library project dependencies (package.json)
yarn install
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
).
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
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
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.
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",
}
}
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.