diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml index 80dec65c..e6865718 100644 --- a/.github/workflows/nodejs.yml +++ b/.github/workflows/nodejs.yml @@ -22,20 +22,13 @@ jobs: npm install -g @angular/cli@12.2.18 cd sdk npm install - cd tests/test-apps/sample-server - echo PRIVATE_KEY=${{ secrets.ik_private_key }} >> .env; - npm install - npm run server & - cd ../../../ npm run test:ci npm run build env: CI: true - PUBLIC_KEY: ${{ secrets.ik_public_key }} - PRIVATE_KEY: ${{ secrets.ik_private_key }} - URL_ENDPOINT: ${{ secrets.ik_url_endopint }} e2e: runs-on: ubuntu-latest + needs: build strategy: matrix: @@ -48,41 +41,37 @@ jobs: with: node-version: ${{ matrix.node-version }} - - name: Create e2e environment variables - run: | - cd sdk/src/environments - echo export const environment = { > environment.ts; - echo production: false, >> environment.ts; - echo URL_ENDPOINT:\"https://ik.imagekit.io/sdktestingik\", >> environment.ts; - echo PUBLIC_KEY:\"${{ secrets.ik_public_key }}\", >> environment.ts; - echo '};' >> environment.ts; - less environment.ts - - - name: Start client server + - name: Build and pack SDK run: | cd sdk npm install - npm start & - - name: Start auth server + npm run build + npm run pack + + - name: Install SDK in test-app run: | - cd sdk/tests/test-apps/sample-server - echo PRIVATE_KEY=${{ secrets.ik_private_key }} >> .env; + cd test-app + # Get SDK version from sdk/package.json + SDK_VERSION=$(node -p "require('../sdk/package.json').version") + echo "Installing SDK version: $SDK_VERSION" + + # Update package.json to use the packed tarball + npm install ../sdk/dist/imagekit-angular/imagekit-angular-${SDK_VERSION}.tgz npm install - npm run server & - env: - CI: true - PUBLIC_KEY: ${{ secrets.ik_public_key }} - PRIVATE_KEY: ${{ secrets.ik_private_key }} - URL_ENDPOINT: https://ik.imagekit.io/sdktestingik - - name: Run E2E tests - uses: cypress-io/github-action@v5 + + - name: Start test-app server + run: | + cd test-app + npm start & + npx wait-on http://localhost:4200 --timeout 60000 + + - name: Run Cypress E2E tests + uses: cypress-io/github-action@v6 with: install: false + working-directory: test-app wait-on: 'http://localhost:4200' - working-directory: sdk + wait-on-timeout: 60 env: DEBUG: 'cypress:server:browsers:electron' - CI: true - PUBLIC_KEY: ${{ secrets.ik_public_key }} - PRIVATE_KEY: ${{ secrets.ik_private_key }} - URL_ENDPOINT: https://ik.imagekit.io/sdktestingik \ No newline at end of file + CI: true \ No newline at end of file diff --git a/.github/workflows/npmpublish.yml b/.github/workflows/npmpublish.yml index 60ac782c..d1975a0e 100644 --- a/.github/workflows/npmpublish.yml +++ b/.github/workflows/npmpublish.yml @@ -25,18 +25,10 @@ jobs: npm install -g @angular/cli@12.2.18 cd sdk npm install - cd tests/test-apps/sample-server - echo PRIVATE_KEY=${{ secrets.ik_private_key }} >> .env; - npm install - npm run server & - cd ../../../ npm run test:ci npm run build env: CI: true - PUBLIC_KEY: ${{ secrets.ik_public_key }} - PRIVATE_KEY: ${{ secrets.ik_private_key }} - URL_ENDPOINT: ${{ secrets.ik_url_endopint }} publish: needs: build @@ -53,7 +45,7 @@ jobs: cd sdk npm install npm run build - cd dist/imagekitio-angular + cd dist/imagekit-angular npm config set //registry.npmjs.org/:_authToken=$NODE_AUTH_TOKEN npm publish env: diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index efc1367b..250164bd 100644 --- a/DEVELOPMENT.md +++ b/DEVELOPMENT.md @@ -1,34 +1,80 @@ ## SDK development -SDK is build in angular 4 for forward compatibilty and `ng-packagr` is used to create final package. Make sure `@angular/cli` is at `v1.4.*` and node ver `14.x` before building the package. +SDK is built using Angular 12.x and `ng-packagr` for packaging. The project is located in the `sdk/` directory. + +**Prerequisites:** +- Node.js v14.x +- Angular CLI compatible with Angular 12.x ## Building package -Execute following command from the `sdk` folder to build the library. This creates a package in `dist/imagekitio-angular` folder. +Execute the following command from the `sdk` folder to build the library. This creates a package in `dist/imagekit-angular` folder. ```sh -# run `npm install` for first time +# Install dependencies (first time) +npm install + +# Build the SDK npm run build ``` ## Running test cases -The designated directory for the tests is `sdk/tests/sdk-tests` folder. All tests will be executed once on the Chrome Headless browser. +### Unit Tests + +The designated directory for the tests is `sdk/tests/sdk-tests` folder. All tests are executed on Chrome Headless browser. -Execute following command from the `sdk` folder to start testing. +Execute the following command from the `sdk` folder to run unit tests: ```sh +# Run tests in watch mode npm run test + +# Run tests once for CI +npm run test:ci +``` + +### E2E Tests + +E2E tests are located in the `test-app/` directory and use Cypress for browser automation. + +To run E2E tests: +```sh +# Navigate to test-app directory +cd test-app + +# Install the SDK +./install_sdk.sh + +# Install dependencies +npm install + +# Start the dev server in one terminal +npm start + +# Run Cypress tests in another terminal +npm run e2e + +# Or open Cypress UI +npm run e2e:open ``` ## Building custom SDK for sample angular app Repository to get sample app: https://github.com/imagekit-samples/quickstart -Before sample apps can be used, `imagekitio-angular` library needs to be packed and installed using the file system within the sample apps. Use the following steps to run any sample app. +Before sample app can be used, `@imagekit/angular` library needs to be packed and installed using the file system within the sample app. Use the following steps to run any sample app: + +1. Navigate to the `test-app` directory +2. Run ./install_sdk.sh. This will build and pack the sdk and install it in the `test-app` project + +7. Use `npm start` from the `test-app` folder to run the app + +## Testing with the test-app + +The repository includes a `test-app/` directory that demonstrates SDK usage: -1. In the `sdk` folder, install dependencies with `npm install` -2. Build library with `npm run build` -3. In the `sdk/dist/imagekitio-angular` folder, use `npm pack` to create a tarball with version mentioned in the current package.json for sdk. -4. Go to the Angular sample app's root folder and use `npm install` to install dependencies. -5. Use `npm install /sdk/dist/imagekitio-angular/imagekitio-angular-x.x.x.tgz` where x.x.x needs to be replaced with the current version. For example, SDK version is `0.0.1`, then above command becomes `npm install /sdk/dist/imagekitio-angular/imagekitio-angular-2.0.0.tgz` -6. Configure sample app with required keys. Use each app's `Readme.md` for exact details. -7. Use npm start from the Angular sample app's root folder to run the app +1. Build the SDK as described above +2. Navigate to `test-app/` directory +3. Install the built SDK: `./install_sdk.sh` +4. Configure environment variables in `test-app/src/environments/` +5. Run the app: `npm start` +6. Access the demo at `http://localhost:4200` diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..ba7fe2e7 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2025 ImageKit Private Limited + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index e7e573a8..37bed53e 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ # ImageKit.io Angular SDK [![Node CI](https://github.com/imagekit-developer/imagekit-angular/workflows/Node%20CI/badge.svg)](https://github.com/imagekit-developer/imagekit-angular/) -[![npm version](https://img.shields.io/npm/v/imagekitio-angular)](https://www.npmjs.com/package/imagekitio-angular) +[![npm version](https://img.shields.io/npm/v/@imagekit/angular)](https://www.npmjs.com/package/@imagekit/angular) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Twitter Follow](https://img.shields.io/twitter/follow/imagekitio?label=Follow&style=social)](https://twitter.com/ImagekitIo) @@ -13,6 +13,30 @@ ImageKit is complete media storage, optimization, and transformation solution th ## Breaking changes +### Upgrading from 5.x to 6.x version + +1. **Package name change** + - The package has been renamed from `imagekitio-angular` to `@imagekit/angular` + - Update your package.json: `npm uninstall imagekitio-angular && npm install @imagekit/angular` + +2. **API parameter changes** + - The `path` parameter has been renamed to `src` in `ik-image` and `ik-video` components + - The `publicKey` parameter has been removed from the configuration provider + - New: `` + +3. **LQIP feature removed** + - The `lqip` (Low Quality Image Placeholder) parameter has been removed from `ik-image` component + - For placeholder functionality, consider using CSS-based solutions or the `loading="lazy"` attribute with appropriate styling + +4. **Responsive images by default** + - The `responsive` transformation is now enabled by default for better performance + - To disable responsive behavior, explicitly set `[responsive]="false"` on the `ik-image` component + +5. **Transformation position change** + - Default transformation position has changed from `path` to `query` parameter style + - URLs now use `?tr=` instead of `/tr:` by default + - To use path-based transformations, explicitly set `transformationPosition="path"` + ### Upgrading from 3.x to 4.x version 1. Overlay syntax update @@ -61,6 +85,7 @@ authenticator = async () => { ## Version Support | SDK Version | Angular 11.x | Angular 12.2.x | Angular 13.x | Angular 14.x | Angular 15.x | Angular 16.x | Angular 17.x | |-------------|---------|---------|---------|---------|---------|---------|---------| +| 6.x | ❌ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |✔️ | | 5.x | ❌ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |✔️ | | 4.x | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ❌ | ❌ | @@ -68,13 +93,13 @@ authenticator = async () => { ## Installation ```shell -npm install --save imagekitio-angular +npm install --save @imagekit/angular ``` or ```shell -yarn add imagekitio-angular +yarn add @imagekit/angular ``` ## Support @@ -86,9 +111,15 @@ Please note that this SDK version supports `Angular version 9 and onwards`. For ### Initialization -To use the SDK, you need to provide it with a few configuration parameters. The configuration parameters must be passed to the `ImagekitioAngularModule` module in your `app.module.ts` file. example: +The SDK supports both **module-based** and **standalone** Angular applications. + +#### Module-based Applications + +To use the SDK in a module-based app, import `ImagekitAngularModule` in your `app.module.ts`: + +```typescript +import { ImagekitAngularModule } from '@imagekit/angular'; -```js @NgModule({ declarations: [ AppComponent @@ -96,19 +127,37 @@ To use the SDK, you need to provide it with a few configuration parameters. The imports: [ BrowserModule, AppRoutingModule, - ImagekitioAngularModule.forRoot({ - publicKey: environment.publicKey, + ImagekitAngularModule.forRoot({ urlEndpoint: environment.urlEndpoint, }) ], providers: [], bootstrap: [AppComponent] }) +export class AppModule { } ``` +#### Standalone Applications (Angular 14+) + +For standalone Angular applications, use the `provideImageKit` function in your `app.config.ts`: + +```typescript +import { ApplicationConfig } from '@angular/core'; +import { provideImageKit } from '@imagekit/angular'; + +export const appConfig: ApplicationConfig = { + providers: [ + provideImageKit({ + urlEndpoint: environment.urlEndpoint, + }) + ] +}; +``` + +#### Configuration Options + * `urlEndpoint` is required to use the SDK. You can get URL-endpoint from your ImageKit dashboard - https://imagekit.io/dashboard/url-endpoints. -* `publicKey` and `authenticator` parameters are required if you want to use the SDK for client-side file upload. You can get `publicKey` from the developer section in your ImageKit dashboard - https://imagekit.io/dashboard/developer/api-keys. -* `transformationPosition` is optional. The default value for the parameter is `path`. Acceptable values are `path` & `query` +* `transformationPosition` is optional. The default value for the parameter is `query`. Acceptable values are `path` & `query` > Note: Do not include your [private key](https://docs.imagekit.io/api-reference/api-introduction/api-keys#private-key) in any client-side code. @@ -116,11 +165,11 @@ To use the SDK, you need to provide it with a few configuration parameters. The ```js // Render an image using a relative path - https://ik.imagekit.io/your_imagekit_id/default-image.jpg - + // Overriding URL endpoint - https://www.custom-domain.com/default-image.jpg @@ -133,18 +182,18 @@ To use the SDK, you need to provide it with a few configuration parameters. The }]' > -// Height and width manipulation - https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200/default-image.jpg +// Height and width manipulation - https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-200,w-200 -// Chained transformation - https://ik.imagekit.io/your_imagekit_id/tr:h-200,w-200:rt-90/default-image.jpg +// Chained transformation - https://ik.imagekit.io/your_imagekit_id/default-image.jpg?tr=h-200,w-200:rt-90 + -// Low-quality image placeholder and lazy loading of original image in the background +// Disable responsive behavior (enabled by default in v6) // Video element with basic transformation, reduced quality by 50% using q:50 -// File upload with optional custom event handling -// See section "ik-upload" in README for more info - +// For file uploads, see the File Upload section ``` ## Demo application @@ -219,11 +230,12 @@ To use the SDK, you need to provide it with a few configuration parameters. The ## Components -The library includes three components: +The library includes two components: * [ik-image](#ik-image) for image resizing. This renders a `` tag. * [ik-video](#ik-video) for video resizing. This renders a `