Skip to content

Commit 41649bc

Browse files
author
utkace
committed
doc: add documentation
1 parent aa003db commit 41649bc

File tree

1 file changed

+152
-0
lines changed

1 file changed

+152
-0
lines changed

‎README.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# ImageKit.io Vue SDK
2+
3+
[![Node CI](https://github.com/imagekit-developer/imagekit-nodejs/workflows/Node%20CI/badge.svg)](https://github.com/imagekit-developer/imagekit-vuejs/)
4+
[![npm version](https://img.shields.io/npm/v/imagekit-vue)](https://www.npmjs.com/package/imagekit-vuejs)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
[![Twitter Follow](https://img.shields.io/twitter/follow/imagekitio?label=Follow&style=social)](https://twitter.com/ImagekitIo)
7+
8+
Vue SDK for [ImageKit.io](https://imagekit.io) which implements client-side upload and URL generation for use inside a vue application.
9+
10+
ImageKit is a complete image optimization and transformation solution that comes with an [image CDN](https://imagekit.io/features/imagekit-infrastructure) and media storage. It can be integrated with your existing infrastructure - storages like AWS S3, web servers, your CDN and custom domain names, allowing you to deliver optimized images in minutes with minimal code changes.
11+
12+
## Installation
13+
14+
`npm install --save imagekit-vue`
15+
16+
Include the components in your code:
17+
18+
`import {IKContext} from "imagekit-vue"`
19+
20+
## Usage
21+
22+
The library includes 3 Components:
23+
* IKContext
24+
25+
* Image
26+
27+
* Upload
28+
29+
### IKContext
30+
31+
In order to use the SDK, you need to provide it with a few configuration parameters. The configuration parameters can be applied directly to the `Image` component or using an `IKContext` component. example:
32+
33+
```js
34+
template: <IKContext publicKey="your_public_api_key" urlEndpoint="<https://ik.imagekit.io/your_imagekit_id>"><IKImage src="<full_image_url_from_db>"/></IKContext>
35+
```
36+
37+
`publicKey` and `urlEndpoint` are mandatory parameters for SDK initialization.
38+
`authenticationEndpoint` is essential if you want to use the SDK for client-side uploads.
39+
`transformationPosition` is optional. The default value for the parametere is `path`. Acceptable values are `path` & `query`
40+
41+
_Note: Do not include your Private Key in any client side code, including this SDK or its initialization. If you pass the `privateKey` parameter while initializing this SDK, it throws an error_
42+
43+
### Image
44+
45+
The image component component defines a ImageKit Image tag. example usage:
46+
47+
#### Using image path and image hostname or endpoint
48+
49+
```js
50+
template: '<IKImage publicKey="your_public_api_key" urlEndpoint="https://ik.imagekit.io/your_imagekit_id" path="/path_to_file"/>'
51+
52+
```
53+
#### Using full image URL
54+
55+
```js
56+
template: '<IKImage publicKey="your_public_api_key" urlEndpoint="https://ik.imagekit.io/your_imagekit_id" src="<full_image_url_from_db>"/>'
57+
```
58+
59+
`src` is the complete URL that is already mapped to ImageKit.
60+
`path` is the location of the image in the ImageKit cloud. `urlEndpoint` + `path` makes the complete url.
61+
`transformations` is optional. The transformations to be applied to a given image. It is declared in the form of an array of objects, where each object specifies the transformation you need. The values are mentioned below.
62+
63+
#### List of supported transformations
64+
65+
The complete list of transformations supported and their usage in ImageKit can be found [here](https://docs.imagekit.io/imagekit-docs/image-transformations). The SDK gives a name to each transformation parameter, making the code simpler and readable. If a transformation is supported in ImageKit, but a name for it cannot be found in the table below, then use the transformation code from ImageKit docs as the name when using in the `url` function.
66+
67+
| Supported Transformation Name | Translates to parameter |
68+
| ----------------------------- | ----------------------- |
69+
| height | h |
70+
| width | w |
71+
| aspectRatio | ar |
72+
| quality | q |
73+
| crop | c |
74+
| cropMode | cm |
75+
| x | x |
76+
| y | y |
77+
| focus | fo |
78+
| format | f |
79+
| radius | r |
80+
| background | bg |
81+
| border | bo |
82+
| rotation | rt |
83+
| blur | bl |
84+
| named | n |
85+
| overlayImage | oi |
86+
| overlayX | ox |
87+
| overlayY | oy |
88+
| overlayFocus | ofo |
89+
| overlayHeight | oh |
90+
| overlayWidth | ow |
91+
| overlayText | ot |
92+
| overlayTextFontSize | ots |
93+
| overlayTextFontFamily | otf |
94+
| overlayTextColor | otc |
95+
| overlayAlpha | oa |
96+
| overlayTextTypography | ott |
97+
| overlayBackground | obg |
98+
| overlayImageTrim | oit |
99+
| progressive | pr |
100+
| lossless | lo |
101+
| trim | t |
102+
| metadata | md |
103+
| colorProfile | cp |
104+
| defaultImage | di |
105+
| dpr | dpr |
106+
| effectSharpen | e-sharpen |
107+
| effectUSM | e-usm |
108+
| effectContrast | e-contrast |
109+
| effectGray | e-grayscale |
110+
| original | orig |
111+
112+
#### Applying Transforms
113+
```js
114+
115+
template: '<IKImage publicKey="your_public_api_key" urlEndpoint="https://ik.imagekit.io/gqyojxcwzxj/" src="<full_image_url_from_db>" v-bind:transformation="[{height:300,width:400}]" />'
116+
```
117+
The above image will apply transformation of width = 90 and height = 180 on the image. Since some transformatinos are destructive you might want to control the order in which the transforms are applied.
118+
119+
##### Chained Transforms
120+
Chained transforms make it easy to specify the order the transform are applied. example:
121+
122+
```js
123+
template: '<IKImage publicKey="your_public_api_key" urlEndpoint="https://ik.imagekit.io/your_imagekit_id" src="<full_image_url_from_db>" v-bind:transformation="[{height:300,width:400},{rotation:90}]"
124+
```
125+
In the above case, rotation will be performed first and resizing according to width and aspect ratio will be performed afterwards.
126+
127+
#### Low Quality Image Placeholders (LQIP) for images
128+
The SDK supports automatic support for LQIP for your images, if you set lqip to true in the image component. example:
129+
130+
```js
131+
<IKImage publicKey="your_public_api_key" urlEndpoint="https://ik.imagekit.io/your_imagekit_id" v-bind:lqip="{active:true,threshold:20}"/>
132+
```
133+
`active` tells the status for lqip, it can be either, `true` or `false`
134+
`threshold` decided the quaility of placeholder image. It can be any numeric value, a low number means low quality, and high number means high quality.
135+
136+
##### How does the lqip work?
137+
The component tries to keep the it simple, it loads a lower quality image using the quality parameter to load a lower quality image, which is then replaced with the actual quality image later.
138+
139+
#### File Upload
140+
The SDK provides a simple Component to upload files to the ImageKit Media Library. It accepts `fileName` parameter as a prop. The file parameter is provided as an input from the user. Additionally, this method uses the `authenticationEndpoint` that is specified at the time of SDK initialization. Client-side file upload requires a token, expiry timestamp and signature, and these values can be safely generated on the server-side using your ImageKit account's private key.
141+
142+
The SDK issues a GET request to the authentication endpoint provided and the endpoint must respond with a JSON object with the values for `token`, `signature` and `expire`.
143+
144+
For example, you can use ImageKit's NodeJS SDK which implements the `getAuthenticationParameters` method to create a simple API endpoint like this on your server and provide the API endpoint as the `authenticationEndpoint` parameter.
145+
146+
An example of this server is provided in the samples folder of the SDK.
147+
148+
Sample Usage
149+
```js
150+
template: '<IKContext publicKey="your_public_api_key" urlEndpoint="https://ik.imagekit.io/your_imagekit_id" authenticationEndpoint="http://www.yourserver.com/auth"><IKUpload fileName="your_desired_filename"/></IKContext>'
151+
```
152+
The SDK provides a simple interface using the .upload() method to upload files to the ImageKit Media Library. It accepts all the parameters supported by the [ImageKit Upload API](https://docs.imagekit.io/api-reference/upload-file-api/client-side-file-upload#request-structure-multipart-form-data).

0 commit comments

Comments
 (0)