|
| 1 | +# ngx-fastboot |
| 2 | + |
| 3 | +[](https://github.com/semantic-release/semantic-release) |
| 4 | +[](https://github.com/KernelPanic92/ngx-fastboot/actions) |
| 5 | +[](https://codecov.io/gh/KernelPanic92/ngx-fastboot) |
| 6 | +[](https://angular.io/) |
| 7 | +[](https://github.com/egoist/tsup) |
| 8 | + |
| 9 | +**ngx-fastboot** is a dynamic configuration loader for Angular applications. It optimizes the startup performance by loading configurations in a separate chunk during compilation. |
| 10 | + |
| 11 | +## Why Use ngx-fastboot? |
| 12 | +Modern web applications often require a multitude of providers, which can increase the initial bundle size and slow down application startup. Splitting code into multiple chunks helps mitigate these issues by: |
| 13 | + |
| 14 | +- **Reducing Initial Bundle Size:** By moving configuration-related code into separate chunks, the initial bundle size is minimized, leading to faster load times and improved performance. |
| 15 | +- **Improving Load Performance:** Smaller initial bundles load quicker, especially over slower network connections, enhancing the user experience. |
| 16 | +- **Mitigating Compilation Warnings:** Angular may generate warnings if the initial bundle size exceeds recommended limits. ngx-fastboot helps distribute the load, reducing the likelihood of these warnings. |
| 17 | + |
| 18 | +## Features |
| 19 | + |
| 20 | +- **Dynamic Configuration Loading**: Load and resolve Angular providers dynamically. |
| 21 | +- **Performance Optimization**: Improve application startup performance by offloading configuration to a separate chunk. |
| 22 | +- **Seamless Integration**: Easy integration with existing Angular projects. |
| 23 | +- **Support for Lazy Configurations**: Load Angular Providers lazily for better performance. |
| 24 | + |
| 25 | +## Installation |
| 26 | + |
| 27 | +with npm: |
| 28 | +```bash |
| 29 | +npm install ngx-fastboot |
| 30 | +``` |
| 31 | + |
| 32 | +with pnpm: |
| 33 | +```bash |
| 34 | +pnpm add ngx-fastboot |
| 35 | +``` |
| 36 | + |
| 37 | +with yarn: |
| 38 | +```bash |
| 39 | +yarn add ngx-fastboot |
| 40 | +``` |
| 41 | + |
| 42 | +## Usage |
| 43 | + |
| 44 | +To use **ngx-fastboot**, import the `fast` function and call it with your Angular application's `bootstrapApplication` function, root component, and configuration options. |
| 45 | + |
| 46 | +### Example |
| 47 | + |
| 48 | + |
| 49 | + |
| 50 | +#### Before |
| 51 | + |
| 52 | +```typescript |
| 53 | +import { AppComponent } from './app.component'; |
| 54 | +import { bootstrapApplication } from '@angular/platform-browser'; |
| 55 | +import provideMyDefaultExportFeatures from './default-export-features.config'; |
| 56 | +import { provideMyOtherFeatures } from './my-other-features.config'; |
| 57 | +import { fast } from 'ngx-fastboot'; |
| 58 | + |
| 59 | +bootstrapApplication(AppComponent, { |
| 60 | + providers: [ |
| 61 | + MyProvider, |
| 62 | + provideMyDefaultExportFeatures, |
| 63 | + provideMyOtherFeatures, |
| 64 | + ] |
| 65 | +}).then(appRef => { |
| 66 | + console.log('App is bootstrapped'); |
| 67 | +}).catch(error => { |
| 68 | + console.error('Error bootstrapping the app', error); |
| 69 | +}); |
| 70 | +``` |
| 71 | + |
| 72 | +#### After |
| 73 | + |
| 74 | +```typescript |
| 75 | +import { AppComponent } from './app.component'; |
| 76 | +import { bootstrapApplication } from '@angular/platform-browser'; |
| 77 | +import { fast } from 'ngx-fastboot'; |
| 78 | + |
| 79 | +fast(bootstrapApplication, AppComponent, { |
| 80 | + providers: [ |
| 81 | + MyProvider, |
| 82 | + () => import('./default-export-features.config'), // default export config |
| 83 | + () => import('./my-other-features.config').then((m) => m.provideMyOtherFeatures), |
| 84 | + ] |
| 85 | +}).then(appRef => { |
| 86 | + console.log('App is bootstrapped'); |
| 87 | +}).catch(error => { |
| 88 | + console.error('Error bootstrapping the app', error); |
| 89 | +}); |
| 90 | +``` |
| 91 | + |
| 92 | +## API |
| 93 | + |
| 94 | +### `fast` |
| 95 | + |
| 96 | +Dynamically loads the specified providers in the configuration and bootstraps an Angular application. |
| 97 | + |
| 98 | +#### Parameters |
| 99 | + |
| 100 | +- **`bootstrap`**: The Angular application's bootstrap function (typically `bootstrapApplication`). |
| 101 | +- **`rootComponent`**: The root component of the application, which should be of type `Type<unknown>`. |
| 102 | +- **`options`**: (Optional) The application configuration, including the providers to be loaded. It should conform to the `FastApplicationConfig` type. Providers can be `Provider`, `EnvironmentProviders`, or lazy modules that return these providers. |
| 103 | + |
| 104 | +#### Returns |
| 105 | + |
| 106 | +A `Promise` that resolves to an `ApplicationRef` instance of the bootstrapped application. The bootstrap method is called with the root component and the updated configuration with the resolved providers. |
| 107 | + |
| 108 | +## Types |
| 109 | + |
| 110 | +### `FastApplicationConfig` |
| 111 | + |
| 112 | +```typescript |
| 113 | +export type FastApplicationConfig = ApplicationConfig & { |
| 114 | + providers: Array<FastProvider> |
| 115 | +} |
| 116 | +``` |
| 117 | +
|
| 118 | +### `FastProvider` |
| 119 | +
|
| 120 | +```typescript |
| 121 | +export type FastProvider = Provider | EnvironmentProviders | LazyModule<Provider | EnvironmentProviders | Array<Provider | EnvironmentProviders>>; |
| 122 | +``` |
| 123 | + |
| 124 | +### `LazyModule` |
| 125 | + |
| 126 | +```typescript |
| 127 | +export type LazyModule<T> = () => Promise<T | { default: T }>; |
| 128 | +``` |
| 129 | + |
| 130 | +### `AngularProvider` |
| 131 | + |
| 132 | +```typescript |
| 133 | +export type AngularProvider = Provider | EnvironmentProviders; |
| 134 | +``` |
| 135 | + |
| 136 | +## Contributing |
| 137 | + |
| 138 | +We welcome contributions! Please read our [Contributing Guide](CONTRIBUTING.md) to learn how you can help improve **ngx-fastboot**. |
| 139 | + |
| 140 | +## License |
| 141 | + |
| 142 | +**ngx-fastboot** is licensed under the MIT License. See the [LICENSE](LICENSE) file for more information. |
| 143 | + |
| 144 | +## Keywords |
| 145 | + |
| 146 | +angular, angular performance, dynamic configuration, lazy loading, angular bootstrap, ngx-fastboot |
| 147 | + |
| 148 | +## Contact |
| 149 | + |
| 150 | +For any questions or feedback, please [open an issue](https://github.com/KernelPanic92/ngx-fastboot/issues). |
0 commit comments