{"id":18458503,"url":"https://github.com/appgeist/storage","last_synced_at":"2025-04-08T05:34:20.911Z","repository":{"id":35008109,"uuid":"196002834","full_name":"appgeist/storage","owner":"appgeist","description":"An opinionated Express-based storage server featuring assets uploading and on-demand image-resizing, like a self-hosted Cloudinary","archived":false,"fork":false,"pushed_at":"2022-12-10T21:52:38.000Z","size":306,"stargazers_count":4,"open_issues_count":6,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-17T20:07:56.651Z","etag":null,"topics":["assets-management","file-storage","image-resizing","imagemagick","nodejs","server-side","webp"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appgeist.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-07-09T12:20:05.000Z","updated_at":"2020-08-08T16:24:23.000Z","dependencies_parsed_at":"2023-01-15T11:54:23.461Z","dependency_job_id":null,"html_url":"https://github.com/appgeist/storage","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appgeist%2Fstorage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appgeist%2Fstorage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appgeist%2Fstorage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appgeist%2Fstorage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appgeist","download_url":"https://codeload.github.com/appgeist/storage/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247785919,"owners_count":20995641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assets-management","file-storage","image-resizing","imagemagick","nodejs","server-side","webp"],"created_at":"2024-11-06T08:18:55.714Z","updated_at":"2025-04-08T05:34:15.884Z","avatar_url":"https://github.com/appgeist.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @appgeist/storage\n\n[![NPM version][npm-image]][npm-url]\n[![License][license-image]][license-url]\n\n![AppGeist Storage](https://user-images.githubusercontent.com/581999/61737873-c8120c80-ad91-11e9-8442-d73f86dde003.png)\n\nAn opinionated Express-based storage server featuring assets uploading and on-demand image-resizing. Like a self-hosted [Cloudinary](https://cloudinary.com).\n\nUses [ImageMagick](https://imagemagick.org), [multer](https://www.npmjs.com/package/multer) and [UUID](https://www.npmjs.com/package/uuid).\n\n**Requires ImageMagick with WebP support**. Most linux distributions provide it by default and `brew install imagemagick` is everything you need to run to install it on macOS.\n\n## Why\n\nBecause:\n\n- Sometimes you want your assets to be stored on your own server;\n- Most browsers can display [WebP](https://developers.google.com/speed/webp/) images and you should definitely use the new format whenever possible instead of `jpg`, `png` or `gif`;\n- You need your pictures in various sizes and/or formats for different screen resolutions, sizes and device capabilities, but you don't always know all the possible combinations _a priori_.\n\n## Usage\n\nSimple, with default options:\n\n```js\nconst storage = require(\"@appgeist/storage\");\n\nstorage().listen(3000, err =\u003e {\n  if (err) throw err;\n  // eslint-disable-next-line no-console\n  console.log(\"Storage server running...\");\n});\n```\n\nAs Express middleware, with custom config options:\n\n```js\nconst express = require(\"express\");\nconst storage = require(\"@appgeist/storage\");\n\nconst app = express();\napp.use(\n  \"/assets\",\n  storage({\n    storageDir: \"./files\",\n    tmpDir: \"./temp-uploads\",\n    maxUploadSize: 1024 * 1024 * 50, // 50 megabytes\n    pictureQuality: 90,\n    maxPicturePixels: 3840 * 2160 // 4K\n  })\n);\n\napp.listen(3000, err =\u003e {\n  if (err) throw err;\n  // eslint-disable-next-line no-console\n  console.log(\"Server running...\");\n});\n```\n\nSee [@appgeist/example-storage-simple](https://github.com/appgeist/example-storage-simple) and [@appgeist/example-storage-with-auth](https://github.com/appgeist/example-storage-with-auth) for more.\n\n## Default config options\n\nHave a look at [index.js](index.js) to see the default config options; JSDoc comments are provided for IDE support.\n\n## Uploading files\n\n### Request payload\n\nFiles can be uploaded by `POST`ing to the mountpoint or a subfolder (i.e. `POST /assets` or `POST /assets/a/subfolder/to/store/the/uploaded/files`) with the following body payload:\n\n```js\n{\n  file: fileData;\n}\n```\n\n...where file represents the file `multipart/form-data` (provided, for instance by an `\u003cinput type=\"file\" /\u003e` tag, see [multer](https://www.npmjs.com/package/multer) docs for more info).\n\nInstead of simply uploading a file, the server can be instructed to dowload it from an accesible remote location by `POST`ing a URL instead of file data:\n\n```js\n{\n  url: \"http://example.com/catz.jpg\";\n}\n```\n\nThe uploaded file will end up in `${storageDir}/assets` or a subfolder, such as `${storageDir}/assets/a/subfolder/to/store/the/uploaded/files`.\n\nA [UUID](https://www.npmjs.com/package/uuid)/v4-based name will be generated for the uploaded file.\n\nIf the uploaded file is an image (`jpg`/`webp`/`png`/`gif`), it will be converted to webp using [ImageMagick](https://imagemagick.org) library and resized to `maxPicturePixels`, otherwise it will simply be stored in the original format.\n\nExamples:\n\n- uploading `catz.jpg` to `/assets` will generate a file like `/assets/9752d427-e6e2-4868-8abf-720db82421c2.webp`;\n- uploading `doc.pdf` to `/assets/docs` will generate a file like `/assets/docs/9752d427-e6e2-4868-8abf-720db82421c2.pdf`;\n\n### Server response\n\nWhen succesfully uploading `catz.jpg` to `/assets/pics/animals`, the server will respond with the following JSON:\n\n```json\n{\n  \"path\": \"/pics/animals\",\n  \"uuid\": \"9752d427-e6e2-4868-8abf-720db82421c2\",\n  \"isPicture\": true,\n  \"originalName\": \"catz.jpg\",\n  \"aspectRatio\": 1.77778\n}\n```\n\n...where:\n\n- **path** is where the the image was uploaded;\n- **uuid** is a [RFC-4122](https://www.ietf.org/rfc/rfc4122.txt) unique identifier generated by [UUID](https://www.npmjs.com/package/uuid)/v4;\n- **isPicture** is `true` (and `false` for non-picture uploads);\n- **originalName** is the original file name (or URL);\n- **aspectRatio** is the picture aspect ratio (determined by [ImageMagick](https://imagemagick.org) `identify` utility; this property is only present for picture file uploads).\n\n## Serving files\n\nStored picture files can be served in multiple formats, resized/centered/cropped to a specified size.\n\nAssuming a `9752d427-e6e2-4868-8abf-720db82421c2` uuid was issued by a previous picture upload, new files will be generated and served to `GET` requests like so:\n\n- `/9752d427-e6e2-4868-8abf-720db82421c2.webp`\n  will serve the original picture;\n- `/9752d427-e6e2-4868-8abf-720db82421c2-w800-h600.webp`\n  will serve the picture resized/centered/cropped to a **width** of 800px and a **height** of 600px;\n- `/9752d427-e6e2-4868-8abf-720db82421c2-w50-h50-lq.webp`\n  will serve a **low-quality** picture resized/centered/cropped to 50x50 pixels (useful for LQIPs).\n\nCropping and resizing only work for pictures. Other types of assets will only be served in the original format.\n\n## Caution\n\nFiles generated for different sizes and formats **are never deleted**. **This can quickly eat up your server space.** Make sure to implement your own mechanism to delete old/unnecessary files!!!\n\n## License\n\nThe [ISC License](LICENSE).\n\n[npm-image]: https://img.shields.io/npm/v/@appgeist/storage.svg?style=flat-square\n[npm-url]: https://www.npmjs.com/package/@appgeist/storage\n[license-image]: https://img.shields.io/npm/l/@appgeist/storage.svg?style=flat-square\n[license-url]: LICENSE\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappgeist%2Fstorage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappgeist%2Fstorage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappgeist%2Fstorage/lists"}