|
1 | | -# @equinor/fusion-framework-app |
| 1 | +--- |
| 2 | +title: "@equinor/fusion-framework-app" |
| 3 | +description: "Application foundation package for the Fusion Framework" |
| 4 | +category: "Application" |
| 5 | +tag: |
| 6 | + - app |
| 7 | + - core |
| 8 | + - foundation |
| 9 | + - modules |
| 10 | + - framework |
| 11 | + - typescript |
| 12 | +--- |
2 | 13 |
|
3 | | -> support package for initializing application modules |
| 14 | +[<img src="https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fapp%2Fpackage.json&label=@equinor/fusion-framework-app&style=for-the-badge" />](https://github.com/equinor/fusion-framework/tree/main/packages/app) |
4 | 15 |
|
5 | | -## 📚 read the [Doc](https://equinor.github.io/fusion-framework/) |
| 16 | +## Overview |
6 | 17 |
|
7 | | -## Bookmarks |
| 18 | +The `@equinor/fusion-framework-app` package serves as the foundation for building Fusion applications. It provides a streamlined way to initialize and configure essential modules that most applications need, while keeping the setup lightweight and flexible. |
8 | 19 |
|
9 | | -The bookmark module provides a way to save and restore the state of the application. This is useful for saving the state of the application when the user navigates away from the application and then returns to the application. |
| 20 | +This package acts as a curated collection of core modules with sensible defaults, allowing developers to quickly bootstrap applications without having to manually wire up common functionality like authentication, HTTP communication, and event handling. |
10 | 21 |
|
11 | | -> [!IMPORTANT] |
12 | | -> please use the `enableBookmark` from `@equinor/fusion-framework-app/bookmark` or `@equinor/fusion-framework-react-app/bookmark` to enable the bookmark module. |
| 22 | +### Key Features |
13 | 23 |
|
14 | | -> [!WARNING] |
15 | | -> The application must be install the `@equinor/fusion-framework-module-bookmark` package to use the bookmark module. |
16 | | -> |
17 | | -> __Do not use the `enableBookmark` from that package when developing Fusion Apps__ |
| 24 | +- **Pre-configured Core Modules**: Essential modules like authentication (MSAL), HTTP client, and event handling are included and configured by default |
| 25 | +- **Optional Module System**: Advanced features like state management and bookmarks can be easily enabled when needed |
| 26 | +- **Lightweight Design**: Only includes essential dependencies, with optional modules available as peer dependencies |
| 27 | +- **Type Safety**: Full TypeScript support with comprehensive type definitions |
| 28 | +- **Framework Agnostic**: Works with any JavaScript framework, with specialized React integrations available |
| 29 | + |
| 30 | +### When to Use |
| 31 | + |
| 32 | +Use this package when building: |
| 33 | +- Fusion Applications |
| 34 | +- Standalone applications that need Fusion Framework capabilities |
| 35 | +- Applications requiring authentication, API communication, and event handling |
| 36 | + |
| 37 | +## 📚 Documentation |
| 38 | + |
| 39 | +For comprehensive guides, examples, and API documentation, visit the [Fusion Framework Documentation](https://equinor.github.io/fusion-framework/). |
| 40 | + |
| 41 | +## Modules |
| 42 | + |
| 43 | +The `@equinor/fusion-framework-app` package provides a set of modules that can be used to enhance the functionality of your application. These modules are designed to be used in conjunction with the Fusion Framework and provide a way to integrate various features into your application. |
| 44 | + |
| 45 | +In conjunction, this package offers some module enabler methods for easy integration and configuration of these modules. |
| 46 | + |
| 47 | +### Enabled by default |
| 48 | + |
| 49 | +#### HTTP Module |
| 50 | +[<img src="https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fmodules%2Fhttp%2Fpackage.json&label=@equinor/fusion-framework-module-http&style=for-the-badge" />](https://github.com/equinor/fusion-framework/tree/main/packages/modules/http) |
| 51 | + |
| 52 | +_The HTTP module provides a way to make HTTP requests and handle responses within the application._ |
| 53 | + |
| 54 | +> [!TIP] |
| 55 | +> If the service is registered in [Service Discovery](#service-discovery) module, you can use the service name to resolve the API endpoint. |
| 56 | +
|
| 57 | +```typescript |
| 58 | +import type { AppModuleInitiator } from '@equinor/fusion-framework-app'; |
| 59 | + |
| 60 | +const configure: AppModuleInitiator = (configurator) => { |
| 61 | + configurator.configureHttp((builder) => { |
| 62 | + builder.configureHttpClient( |
| 63 | + 'my-api-client', |
| 64 | + { |
| 65 | + baseUri: '/api', |
| 66 | + defaultScopes: ['api://default'] |
| 67 | + } |
| 68 | + ); |
| 69 | + }); |
| 70 | +}; |
| 71 | +``` |
| 72 | + |
| 73 | +#### Auth Module |
| 74 | +[<img src="https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fmodules%2Fmsal%2Fpackage.json&label=@equinor/fusion-framework-module-msal&style=for-the-badge" />](https://github.com/equinor/fusion-framework/tree/main/packages/modules/msal) |
| 75 | + |
| 76 | +_The MSAL module provides a way to integrate Microsoft Authentication Library (MSAL) into the application._ |
| 77 | + |
| 78 | + |
| 79 | +#### Service Discovery |
| 80 | + |
| 81 | +[<img src="https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fmodules%2Fservice-discovery%2Fpackage.json&label=@equinor/fusion-framework-module-service-discovery&style=for-the-badge" />](https://github.com/equinor/fusion-framework/tree/main/packages/modules/service-discovery) |
| 82 | + |
| 83 | +_The service discovery module provides a way to resolve API endpoints and interact with microservices within the application._ |
| 84 | + |
| 85 | +> [!NOTE] |
| 86 | +> To resolve a service, it need to be configured which service(s) to use in the application. |
| 87 | +
|
| 88 | +```typescript |
| 89 | +import type { AppModuleInitiator } from '@equinor/fusion-framework-app'; |
| 90 | + |
| 91 | +const configure: AppModuleInitiator = (configurator) => { |
| 92 | + configurator.useFrameworkServiceClient('my-registered-service', { /** options */}); |
| 93 | +}; |
| 94 | + |
| 95 | +// example usage after application module initialization |
| 96 | +const client = appModules.http.createHttpClient('my-api-client'); |
| 97 | +``` |
| 98 | + |
| 99 | + |
| 100 | +#### Event Module |
| 101 | +[<img src="https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fmodules%2Fevent%2Fpackage.json&label=@equinor/fusion-framework-module-event&style=for-the-badge" />](https://github.com/equinor/fusion-framework/tree/main/packages/modules/event) |
| 102 | + |
| 103 | +_The event module provides a way to manage and handle events within the application._ |
| 104 | + |
| 105 | +### User Enabled |
| 106 | + |
| 107 | +`@equinor/fusion-framework-app` exposes modules for application enablement, since some modules might require application-specific configurations. |
| 108 | + |
| 109 | +> [!NOTE] |
| 110 | +> `@equinor/fusion-framework-app` only has these modules as optional dependencies, which means the module need to be installed in the application project to work. |
18 | 111 | > |
19 | | -> _We might in the future allow application configure their own module, but for now, use the enabler in the app package_ |
| 112 | +> _We chosen not to include the optional modules to keep the core package lightweight and focused on essential functionality._ |
| 113 | +
|
| 114 | +> [!WARNING] |
| 115 | +> Event though an application may enable modules directly, it is important to ensure that the necessary configurations are in place for each module to function as intended. |
20 | 116 |
|
21 | | -### Usage |
| 117 | +#### State Management |
22 | 118 |
|
23 | | -```ts |
24 | | -import type { AppModuleInitiator, IAppConfigurator } from '@equinor/fusion-framework-react-app'; |
| 119 | +[<img src="https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fmodules%2Fstate%2Fpackage.json&label=@equinor/fusion-framework-module-state&style=for-the-badge" />](https://github.com/equinor/fusion-framework/tree/main/packages/modules/state) |
| 120 | + |
| 121 | +_The state management module provides a way to manage the state of the application. This is useful for keeping track of user preferences, application settings, and other data that needs to persist across sessions._ |
| 122 | + |
| 123 | +```sh |
| 124 | +# Install the state management module |
| 125 | +pnpm add @equinor/fusion-framework-module-state |
| 126 | +``` |
| 127 | + |
| 128 | +```typescript |
| 129 | +import type { AppModuleInitiator } from '@equinor/fusion-framework-app'; |
| 130 | +import { enableState } from '@equinor/fusion-framework-app/state'; |
| 131 | + |
| 132 | +const configure: AppModuleInitiator = (configurator) => { |
| 133 | + enableState(configurator); |
| 134 | +}; |
| 135 | +``` |
| 136 | + |
| 137 | +#### Bookmarks |
25 | 138 |
|
26 | | -import { enableBookmark } from '@equinor/fusion-framework-react-app/bookmark'; |
| 139 | +[<img src="https://img.shields.io/github/package-json/v/equinor/fusion-framework?filename=packages%2Fmodules%2Fbookmark%2Fpackage.json&label=@equinor/fusion-framework-module-bookmark&style=for-the-badge" />](https://github.com/equinor/fusion-framework/tree/main/packages/modules/bookmark) |
27 | 140 |
|
28 | | -export const configure: AppModuleInitiator = (configurator: IAppConfigurator) => { |
| 141 | +_The bookmark module provides a way to save and restore the state of the application. This is useful for saving the state of the application when the user navigates away from the application and then returns to the application._ |
| 142 | + |
| 143 | +```sh |
| 144 | +# Install the bookmark module |
| 145 | +pnpm add @equinor/fusion-framework-module-bookmark |
| 146 | +``` |
| 147 | + |
| 148 | +```ts |
| 149 | +import type { AppModuleInitiator } from '@equinor/fusion-framework-app'; |
| 150 | +import { enableBookmark } from '@equinor/fusion-framework-app/bookmark'; |
| 151 | + |
| 152 | +const configure: AppModuleInitiator = (configurator) => { |
29 | 153 | enableBookmark(configurator); |
30 | 154 | }; |
31 | 155 | ``` |
32 | 156 |
|
| 157 | +## Advance |
| 158 | + |
| 159 | +### Extending the Application Configuration |
| 160 | + |
| 161 | +In some case one might want to extend the application configuration to include pre-defined modules and custom behavior, |
| 162 | +like maintaining a suite of applications that requires a common set of modules. |
| 163 | + |
| 164 | +> [!NOTE] |
| 165 | +> At the moment the utility functions for initializing application modules does not support defining custom application configurations, |
| 166 | +> which means that scaffolding needs to be re-implemented. |
| 167 | +
|
| 168 | +```ts |
| 169 | +import { AppConfigurator, AppEnv } from '@equinor/fusion-framework-app'; |
| 170 | + |
| 171 | +type CustomAppManifest = { /** custom attributes */ } |
| 172 | +type MyFrameworkModuleInstance = { /** custom module selection */ } |
| 173 | + |
| 174 | +type CustomAppEnv = AppEnv & { |
| 175 | + manifest: CustomAppManifest; |
| 176 | + /** other custom environment properties */ |
| 177 | +}; |
| 178 | + |
| 179 | +// extending the Fusion AppConfigurator |
| 180 | +class ExtendedAppConfigurator< |
| 181 | + TModules extends Array<AnyModule> | unknown = unknown, |
| 182 | + TRef extends MyFrameworkModuleInstance = MyFrameworkModuleInstance, |
| 183 | + TEnv extends CustomAppEnv = CustomAppEnv, |
| 184 | + > |
| 185 | + extends AppConfigurator<TModules, TRef, TEnv> { |
| 186 | + constructor(env: TEnv) { |
| 187 | + super(env); |
| 188 | + this._modules.push(MyCustomModule); |
| 189 | + } |
| 190 | +} |
| 191 | +``` |
| 192 | + |
| 193 | +### Application Configuration with custom framework |
| 194 | + |
| 195 | +`AppConfigurator` in `@equinor/fusion-framework-app` is a superset of `ModulesConfigurator` in `@equinor/fusion-framework-module`, |
| 196 | +which means that creating a custom application configuration outside the __Fusion Framework__ is most likely better of with starting from scratch with `ModulesConfigurator`. |
0 commit comments