ng-image-optimizer 0.0.1 → 0.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/LICENSE +19 -0
  2. package/README.md +73 -34
  3. package/package.json +2 -1
package/LICENSE ADDED
@@ -0,0 +1,19 @@
1
+ Copyright (c) 2026 Hasan Kakeh
2
+
3
+ Permission is hereby granted, free of charge, to any person obtaining a copy
4
+ of this software and associated documentation files (the "Software"), to deal
5
+ in the Software without restriction, including without limitation the rights
6
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
7
+ copies of the Software, and to permit persons to whom the Software is
8
+ furnished to do so, subject to the following conditions:
9
+
10
+ The above copyright notice and this permission notice shall be included in all
11
+ copies or substantial portions of the Software.
12
+
13
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
14
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
15
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
16
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
17
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
18
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
19
+ SOFTWARE.
package/README.md CHANGED
@@ -1,64 +1,103 @@
1
1
  # NgImageOptimizer
2
2
 
3
- This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.2.0.
3
+ An image optimization library for Angular SSR. It provides a customized `IMAGE_LOADER` for Angular's `NgOptimizedImage` and a back-end Express middleware for processing and caching images using `sharp`.
4
4
 
5
- ## Code scaffolding
5
+ ## 📦 Installation
6
6
 
7
- Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
7
+ Install the library and its peer dependencies:
8
8
 
9
9
  ```bash
10
- ng generate component component-name
10
+ npm install ng-image-optimizer sharp lru-cache
11
11
  ```
12
12
 
13
- For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
13
+ ## 🚀 Setup
14
14
 
15
- ```bash
16
- ng generate --help
17
- ```
15
+ ### 1. Automated (Recommended)
18
16
 
19
- ## Building
20
-
21
- To build the library, run:
17
+ Run the schematic to automatically configure your application:
22
18
 
23
19
  ```bash
24
- ng build ng-image-optimizer
20
+ ng add ng-image-optimizer
25
21
  ```
26
22
 
27
- This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
23
+ ---
24
+
25
+ ### 2. Manual Setup
28
26
 
29
- ### Publishing the Library
27
+ If you prefer to configure things manually, follow these steps:
30
28
 
31
- Once the project is built, you can publish your library by following these steps:
29
+ #### Client-Side Configuration
30
+ Register the image loader in your `app.config.ts`:
32
31
 
33
- 1. Navigate to the `dist` directory:
32
+ ```typescript
33
+ import { provideImageOptimizerLoader } from 'ng-image-optimizer';
34
34
 
35
- ```bash
36
- cd dist/ng-image-optimizer
37
- ```
35
+ export const appConfig: ApplicationConfig = {
36
+ providers: [
37
+ provideImageOptimizerLoader({
38
+ routePrefix: '/_ng/image' // Must match server-side route
39
+ })
40
+ ]
41
+ };
42
+ ```
38
43
 
39
- 2. Run the `npm publish` command to publish your library to the npm registry:
40
- ```bash
41
- npm publish
42
- ```
44
+ #### Server-Side Configuration
45
+ Add the middleware to your `server.ts` before other routes:
43
46
 
44
- ## Running unit tests
47
+ ```typescript
48
+ import { imageOptimizerHandler } from 'ng-image-optimizer/server';
45
49
 
46
- To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
50
+ // ... early in your express app setup
51
+ const browserDistFolder = resolve(serverDistFolder, '../browser');
47
52
 
48
- ```bash
49
- ng test
53
+ server.get('/_ng/image', imageOptimizerHandler(browserDistFolder, {
54
+ remotePatterns: [
55
+ { hostname: 'images.unsplash.com' } // Allow external domains
56
+ ],
57
+ formats: ['image/webp', 'image/avif'] // Targeted formats
58
+ }));
50
59
  ```
51
60
 
52
- ## Running end-to-end tests
61
+ ---
53
62
 
54
- For end-to-end (e2e) testing, run:
63
+ ## 🛠️ Usage
55
64
 
56
- ```bash
57
- ng e2e
65
+ Use standard Angular `NgOptimizedImage` in your templates. The library will automatically handle the resolution and optimization.
66
+
67
+ ```html
68
+ <img ngSrc="assets/photo.jpg" width="800" height="600" priority>
58
69
  ```
59
70
 
60
- Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
71
+ ---
72
+
73
+ ## ⚙️ Configuration (`ImageConfig`)
74
+
75
+ When initializing `imageOptimizerHandler`, you can pass an optional configuration object:
76
+
77
+ | Property | Type | Default | Description |
78
+ | :--- | :--- | :--- | :--- |
79
+ | `deviceSizes` | `number[]` | `[640, 750, 828, ...]` | Allowed widths for device breakpoints. |
80
+ | `imageSizes` | `number[]` | `[16, 32, 48, ...]` | Allowed widths for smaller UI elements. |
81
+ | `remotePatterns` | `RemotePattern[]` | `[]` | List of allowed external domains. |
82
+ | `minimumCacheTTL` | `number` | `14400` (4h) | Minimum time (seconds) to cache an image. |
83
+ | `formats` | `string[]` | `['image/webp']` | Favored output formats (supports webp/avif). |
84
+ | `dangerouslyAllowSVG` | `boolean` | `false` | Whether to allow processing SVG images. |
85
+ | `contentSecurityPolicy` | `string` | `...` | CSP headers for the served images. |
86
+
87
+ ---
88
+
89
+ ## 🔐 Security
90
+
91
+ - **Allowlist Driven**: Remote images are only fetched if they match `remotePatterns`.
92
+ - **Parameter Validation**: Requests are strictly validated for matching widths and valid URLs.
93
+ - **Sandboxed**: CSP headers are automatically applied to prevent script injection via images.
94
+
95
+ ## 💾 Caching
61
96
 
62
- ## Additional Resources
97
+ The library uses a highly optimized file-based cache located in `.image-cache/`.
98
+ - **High Entropy Keys**: Cache keys are generated based on the URL, width, quality, and format.
99
+ - **Vary Headers**: Correctly handles `Accept` headers to serve different formats to different browsers.
100
+ - **Etag Support**: Implements strong ETags for browser-level caching.
63
101
 
64
- For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
102
+ ## 📄 License
103
+ MIT
package/package.json CHANGED
@@ -1,6 +1,7 @@
1
1
  {
2
2
  "name": "ng-image-optimizer",
3
- "version": "0.0.1",
3
+ "version": "0.0.2",
4
+ "license": "MIT",
4
5
  "peerDependencies": {
5
6
  "@angular/common": "^21.2.0",
6
7
  "@angular/core": "^21.2.0",