0
# Sharp
1

2
Sharp is a high-performance Node.js image processing library that provides fast image transformations including resizing, format conversion, rotation, extraction, compositing, and color space management. Built on the libvips image processing library, it delivers 4x-5x faster performance than ImageMagick while maintaining quality through Lanczos resampling and proper handling of color spaces, ICC profiles, and alpha channels.
3

4
## Package Information
5

6
- **Package Name**: sharp
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install sharp`
10

11
## Core Imports
12

13
```javascript
14
const sharp = require('sharp');
15
```
16

17
For TypeScript:
18

19
```typescript
20
import sharp from 'sharp';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const sharp = require('sharp');
27

28
// Basic resize operation
29
await sharp('input.jpg')
30
  .resize(300, 200)
31
  .toFile('output.jpg');
32

33
// Pipeline with multiple operations  
34
const result = await sharp('input.png')
35
  .rotate(90)
36
  .resize({ width: 800, fit: 'contain' })
37
  .jpeg({ quality: 90 })
38
  .toBuffer();
39

40
// Stream processing
41
const transformer = sharp()
42
  .resize(400)
43
  .webp({ quality: 80 });
44

45
readableStream
46
  .pipe(transformer)
47
  .pipe(writableStream);
48
```
49

50
## Architecture  
51

52
Sharp is built around several key components:
53

54
- **Fluent API**: All operations return Sharp instances for method chaining
55
- **Stream Interface**: Implements Node.js Duplex streams for pipeline processing
56
- **Format Support**: Native support for JPEG, PNG, WebP, GIF, AVIF, TIFF, HEIF, SVG, and RAW formats
57
- **Performance Controls**: Multi-threading, SIMD optimizations, and caching management
58
- **Metadata Preservation**: Comprehensive EXIF, ICC, XMP, and IPTC metadata handling
59
- **Memory Management**: Configurable limits and monitoring for production use
60

61
## Capabilities
62

63
### Constructor and Input Handling
64

65
Create Sharp instances from various input sources including files, buffers, streams, and generated content.
66

67
```javascript { .api }
68
function sharp(input?: SharpInput | SharpInput[], options?: SharpOptions): Sharp;
69

70
type SharpInput = Buffer | ArrayBuffer | Uint8Array | Uint8ClampedArray | 
71
  Int8Array | Uint16Array | Int16Array | Uint32Array | Int32Array | 
72
  Float32Array | Float64Array | string;
73

74
interface SharpOptions {
75
  autoOrient?: boolean;
76
  failOn?: 'none' | 'truncated' | 'error' | 'warning';
77
  limitInputPixels?: number | boolean;
78
  density?: number;
79
  pages?: number;
80
  page?: number;
81
  animated?: boolean;
82
  raw?: CreateRaw;
83
  create?: Create;
84
  text?: CreateText;
85
  join?: Join;
86
}
87
```
88

89
[Constructor and Input](./constructor-input.md)
90

91
### Image Resizing and Geometry
92

93
Resize, crop, extend, and extract regions from images with multiple fit strategies and interpolation methods.
94

95
```javascript { .api }
96
resize(width?: number | ResizeOptions, height?: number, options?: ResizeOptions): Sharp;
97
extract(region: Region): Sharp;
98
extend(extend: number | ExtendOptions): Sharp;
99
trim(options?: TrimOptions): Sharp;
100

101
interface ResizeOptions {
102
  width?: number;
103
  height?: number;
104
  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
105
  position?: string | number;
106
  background?: string | object;
107
  kernel?: 'nearest' | 'cubic' | 'mitchell' | 'lanczos2' | 'lanczos3';
108
  withoutEnlargement?: boolean;
109
  withoutReduction?: boolean;
110
}
111
```
112

113
[Resizing and Geometry](./resize-geometry.md)
114

115
### Image Operations and Filters
116

117
Apply filters, effects, and transformations including rotation, sharpening, blurring, and color adjustments.
118

119
```javascript { .api }
120
rotate(angle?: number, options?: RotateOptions): Sharp;
121
sharpen(options?: SharpenOptions): Sharp;
122
blur(sigma?: number | boolean | BlurOptions): Sharp;
123
gamma(gamma?: number, gammaOut?: number): Sharp;
124
negate(negate?: boolean | NegateOptions): Sharp;
125
normalise(options?: NormaliseOptions): Sharp;
126
modulate(options?: ModulateOptions): Sharp;
127

128
interface SharpenOptions {
129
  sigma: number;
130
  m1?: number;
131
  m2?: number;
132
  x1?: number;
133
  y2?: number;
134
  y3?: number;
135
}
136
```
137

138
[Operations and Filters](./operations-filters.md)
139

140
### Color Space and Channel Management
141

142
Control color spaces, manipulate channels, and apply color transformations.
143

144
```javascript { .api }
145
tint(tint: string | object): Sharp;
146
greyscale(greyscale?: boolean): Sharp;
147
toColourspace(colourspace?: string): Sharp;
148
extractChannel(channel: 0 | 1 | 2 | 3 | 'red' | 'green' | 'blue' | 'alpha'): Sharp;
149
removeAlpha(): Sharp;
150
ensureAlpha(alpha?: number): Sharp;
151

152
interface RGBA {
153
  r?: number;
154
  g?: number;
155
  b?: number;
156
  alpha?: number;
157
}
158
```
159

160
[Color and Channels](./color-channels.md)
161

162
### Image Composition
163

164
Composite multiple images with various blend modes and positioning options.
165

166
```javascript { .api }
167
composite(images: OverlayOptions[]): Sharp;
168

169
interface OverlayOptions {
170
  input: string | Buffer | object;
171
  blend?: 'clear' | 'source' | 'over' | 'multiply' | 'screen' | 'overlay' | 
172
    'darken' | 'lighten' | 'difference' | 'exclusion';
173
  gravity?: 'north' | 'northeast' | 'east' | 'southeast' | 'south' |
174
    'southwest' | 'west' | 'northwest' | 'center' | 'centre';
175
  top?: number;
176
  left?: number;
177
  tile?: boolean;
178
}
179
```
180

181
[Image Composition](./composition.md)
182

183
### Output and Format Control
184

185
Write images to files or buffers with format-specific options and metadata control.
186

187
```javascript { .api }
188
toFile(fileOut: string, callback?: (err: Error, info: OutputInfo) => void): Promise<OutputInfo>;
189
toBuffer(options?: BufferOptions, callback?: (err: Error, buffer: Buffer, info: OutputInfo) => void): Promise<Buffer>;
190
jpeg(options?: JpegOptions): Sharp;
191
png(options?: PngOptions): Sharp;
192
webp(options?: WebpOptions): Sharp;
193
avif(options?: AvifOptions): Sharp;
194
tiff(options?: TiffOptions): Sharp;
195

196
interface OutputInfo {
197
  format: string;
198
  size: number;
199
  width: number;
200
  height: number;
201
  channels: number;
202
  premultiplied: boolean;
203
}
204
```
205

206
[Output and Formats](./output-formats.md)
207

208
### Metadata and Statistics
209

210
Access comprehensive image metadata and pixel-level statistics without decoding image data.
211

212
```javascript { .api }
213
metadata(): Promise<Metadata>;
214
stats(): Promise<Stats>;
215

216
interface Metadata {
217
  format: string;
218
  width: number;
219
  height: number;
220
  channels: number;
221
  depth: string;
222
  space: string;
223
  hasProfile: boolean;
224
  hasAlpha: boolean;
225
  orientation?: number;
226
  density?: number;
227
  pages?: number;
228
}
229

230
interface Stats {
231
  channels: ChannelStats[];
232
  isOpaque: boolean;
233
  entropy: number;
234
  sharpness: number;
235
  dominant: { r: number; g: number; b: number };
236
}
237
```
238

239
[Metadata and Stats](./metadata-stats.md)
240

241
### Utility Functions and Performance
242

243
Control library behavior, performance settings, and access version information.
244

245
```javascript { .api }
246
// Static utility functions
247
sharp.cache(options?: boolean | CacheOptions): CacheResult;
248
sharp.concurrency(concurrency?: number): number;
249
sharp.counters(): SharpCounters;
250
sharp.simd(enable?: boolean): boolean;
251

252
// Library information
253
sharp.format: FormatEnum;
254
sharp.versions: VersionInfo;
255
sharp.interpolators: Interpolators;
256
```
257

258
[Utilities and Performance](./utilities-performance.md)
259

260
## Core Types
261

262
```javascript { .api }
263
interface Sharp {
264
  // Sharp extends Node.js Duplex stream
265
  clone(): Sharp;
266
}
267

268
interface Region {
269
  left: number;
270
  top: number;
271
  width: number;
272
  height: number;
273
}
274

275
interface Create {
276
  width: number;
277
  height: number;
278
  channels: 3 | 4;
279
  background: string | RGBA;
280
}
281

282
interface CreateText {
283
  text: string;
284
  font?: string;
285
  fontfile?: string;
286
  width?: number;
287
  height?: number;
288
  align?: 'left' | 'centre' | 'center' | 'right';
289
  justify?: boolean;
290
  dpi?: number;
291
  rgba?: boolean;
292
  spacing?: number;
293
  wrap?: 'word' | 'char' | 'word-char' | 'none';
294
}
295
```