1 | # sharp
|
2 |
|
3 | <img src="https://cdn.jsdelivr.net/gh/lovell/sharp@main/docs/image/sharp-logo.svg" width="160" height="160" alt="sharp logo" align="right">
|
4 |
|
5 | The typical use case for this high speed Node.js module
|
6 | is to convert large images in common formats to
|
7 | smaller, web-friendly JPEG, PNG, WebP, GIF and AVIF images of varying dimensions.
|
8 |
|
9 | Resizing an image is typically 4x-5x faster than using the
|
10 | quickest ImageMagick and GraphicsMagick settings
|
11 | due to its use of [libvips](https://github.com/libvips/libvips).
|
12 |
|
13 | Colour spaces, embedded ICC profiles and alpha transparency channels are all handled correctly.
|
14 | Lanczos resampling ensures quality is not sacrificed for speed.
|
15 |
|
16 | As well as image resizing, operations such as
|
17 | rotation, extraction, compositing and gamma correction are available.
|
18 |
|
19 | Most modern macOS, Windows and Linux systems running Node.js >= 12.13.0
|
20 | do not require any additional install or runtime dependencies.
|
21 |
|
22 | ## Documentation
|
23 |
|
24 | Visit [sharp.pixelplumbing.com](https://sharp.pixelplumbing.com/) for complete
|
25 | [installation instructions](https://sharp.pixelplumbing.com/install),
|
26 | [API documentation](https://sharp.pixelplumbing.com/api-constructor),
|
27 | [benchmark tests](https://sharp.pixelplumbing.com/performance) and
|
28 | [changelog](https://sharp.pixelplumbing.com/changelog).
|
29 |
|
30 | ## Examples
|
31 |
|
32 | ```sh
|
33 | npm install sharp
|
34 | ```
|
35 |
|
36 | ```javascript
|
37 | const sharp = require('sharp');
|
38 | ```
|
39 |
|
40 | ### Callback
|
41 |
|
42 | ```javascript
|
43 | sharp(inputBuffer)
|
44 | .resize(320, 240)
|
45 | .toFile('output.webp', (err, info) => { ... });
|
46 | ```
|
47 |
|
48 | ### Promise
|
49 |
|
50 | ```javascript
|
51 | sharp('input.jpg')
|
52 | .rotate()
|
53 | .resize(200)
|
54 | .jpeg({ mozjpeg: true })
|
55 | .toBuffer()
|
56 | .then( data => { ... })
|
57 | .catch( err => { ... });
|
58 | ```
|
59 |
|
60 | ### Async/await
|
61 |
|
62 | ```javascript
|
63 | const semiTransparentRedPng = await sharp({
|
64 | create: {
|
65 | width: 48,
|
66 | height: 48,
|
67 | channels: 4,
|
68 | background: { r: 255, g: 0, b: 0, alpha: 0.5 }
|
69 | }
|
70 | })
|
71 | .png()
|
72 | .toBuffer();
|
73 | ```
|
74 |
|
75 | ### Stream
|
76 |
|
77 | ```javascript
|
78 | const roundedCorners = Buffer.from(
|
79 | '<svg><rect x="0" y="0" width="200" height="200" rx="50" ry="50"/></svg>'
|
80 | );
|
81 |
|
82 | const roundedCornerResizer =
|
83 | sharp()
|
84 | .resize(200, 200)
|
85 | .composite([{
|
86 | input: roundedCorners,
|
87 | blend: 'dest-in'
|
88 | }])
|
89 | .png();
|
90 |
|
91 | readableStream
|
92 | .pipe(roundedCornerResizer)
|
93 | .pipe(writableStream);
|
94 | ```
|
95 |
|
96 | ## Contributing
|
97 |
|
98 | A [guide for contributors](https://github.com/lovell/sharp/blob/main/.github/CONTRIBUTING.md)
|
99 | covers reporting bugs, requesting features and submitting code changes.
|
100 |
|
101 | [![Test Coverage](https://coveralls.io/repos/lovell/sharp/badge.svg?branch=main)](https://coveralls.io/r/lovell/sharp?branch=main)
|
102 | [![Node-API v5](https://img.shields.io/badge/Node--API-v5-green.svg)](https://nodejs.org/dist/latest/docs/api/n-api.html#n_api_n_api_version_matrix)
|
103 |
|
104 | ## Licensing
|
105 |
|
106 | Copyright 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022 Lovell Fuller and contributors.
|
107 |
|
108 | Licensed under the Apache License, Version 2.0 (the "License");
|
109 | you may not use this file except in compliance with the License.
|
110 | You may obtain a copy of the License at
|
111 | [https://www.apache.org/licenses/LICENSE-2.0](https://www.apache.org/licenses/LICENSE-2.0)
|
112 |
|
113 | Unless required by applicable law or agreed to in writing, software
|
114 | distributed under the License is distributed on an "AS IS" BASIS,
|
115 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
116 | See the License for the specific language governing permissions and
|
117 | limitations under the License.
|