{"id":36980945,"url":"https://github.com/moritzebeling/kirby-headless-image-transformations","last_synced_at":"2026-01-13T22:50:43.338Z","repository":{"id":181800315,"uuid":"637746389","full_name":"moritzebeling/kirby-headless-image-transformations","owner":"moritzebeling","description":"Kirby plugin for headless image transformations","archived":false,"fork":false,"pushed_at":"2023-05-09T07:12:21.000Z","size":22,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-27T22:21:42.388Z","etag":null,"topics":["headless","kirby","plugin","thumbnail","transformations"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moritzebeling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2023-05-08T10:21:08.000Z","updated_at":"2024-04-09T07:53:00.000Z","dependencies_parsed_at":null,"dependency_job_id":"bae6e178-ee70-42dd-91e5-d9dcbe93d6e6","html_url":"https://github.com/moritzebeling/kirby-headless-image-transformations","commit_stats":null,"previous_names":["moritzebeling/kirby-headless-image-transformations"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/moritzebeling/kirby-headless-image-transformations","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzebeling%2Fkirby-headless-image-transformations","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzebeling%2Fkirby-headless-image-transformations/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzebeling%2Fkirby-headless-image-transformations/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzebeling%2Fkirby-headless-image-transformations/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moritzebeling","download_url":"https://codeload.github.com/moritzebeling/kirby-headless-image-transformations/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moritzebeling%2Fkirby-headless-image-transformations/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28402160,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["headless","kirby","plugin","thumbnail","transformations"],"created_at":"2026-01-13T22:50:42.892Z","updated_at":"2026-01-13T22:50:43.326Z","avatar_url":"https://github.com/moritzebeling.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kirby Headless Image Transformations\n\nThis plugin adds a new route to your Kirby CMS installation that allows you to transform images on the fly. This is useful when you want to let the frontend decide what image size to load:\n\n**Schema**\n```\nhttps://your-kirby-website.com/thumbs/{image-id}.{ext}?{transformations}\n```\n\n**Original image**\n```\nhttps://your-kirby-website.com/thumbs/{image-id}.{ext}\n```\n\n**Thumbnail with 640px width and auto height**\n```\nhttps://your-kirby-website.com/thumbs/{image-id}.{ext}?width=640\n```\n\n**Cropped thumbnail with 640px width and height**\n```\nhttps://your-kirby-website.com/thumbs/{image-id}.{ext}?width=640\u0026height=640\u0026crop=true\n```\n\n## Installation\n\n```bash\ncomposer require moritzebeling/kirby-headless-image-transformations\n```\n\nOr download/clone this repo into `site/plugins` of your Kirby project.\n\n## URL Query parameters\n\nYou can use all options offered by the [Kirby `thumb()` method](https://getkirby.com/docs/reference/objects/cms/file/thumb#options):\n\n```js\nlet options = {\n    'autoOrient' =\u003e true,  // bool\n    'crop'       =\u003e false, // bool\n    'blur'       =\u003e false, // bool\n    'grayscale'  =\u003e false, // bool\n    'height'     =\u003e null,  // int\n    'quality'    =\u003e 90,    // int 0-100\n    'width'      =\u003e null,  // int\n}\n```\n\n## Usage\n\nThis plugin can be helpful if you use Kirby as a Headless CMS and want to decide on your frontend which image size to load or to include in your srcset. You would only need the image id:\n\n```php\n$image_id = $file-\u003eid();\n```\n\n**Load single size:**\n\n```js\nfunction serializeObjectToQueryString( options = {} ){\n    const queryString = Object.keys(options).map(key =\u003e key + '=' + options[key]).join('\u0026');\n    return queryString ? '?' + queryString : '';\n}\n\nconst options = {\n    width: 640,\n    height: 640,\n    crop: true,\n};\n\nconst host = 'https://your-kirby-website.com/thumbs';\nconst image_id = 'page-id/image-filename.jpg';\n\nconst thumb_url = `${host}/${image_id}${serializeObjectToQueryString( options )}`;\n```\n```html\n\u003cimg src={thumb_url} width={options.width} height={options.height} /\u003e\n```\n\n**Load multiple widths for srcset:**\n\n```js\n// createQueryString, url_base, image_id same as in example above\n\nconst sizes = [240,480,960];\n\nlet src = `${host}/${image_id}${serializeObjectToQueryString({ width: sizes[0] })}`;\nlet srcset = sizes.map( size =\u003e {\n    const options = {\n        width: size\n    };\n    return `${host}/${image_id}${serializeObjectToQueryString( options )} ${size}w`;\n}).join(', ');\n\n```\n```html\n\u003cimg {src} {srcset} /\u003e\n```\n\n\u003e Note that the html code above is just an example and wouln’t work in a vanilla setup, but require some type of templating engine, e.g. Svelte.\n\n## Options and security considerations\n\nWhenever a thumbnail is requested for the first time, Kirby will generate it and store it in the `media` folder. So whenever a thumb is requested for the first time, it will take a little longer.\n\nThis also means that people with bad intentions could exploit this to overwhelm your server and fill up your disk space. In order to prevent this, you should restrict the allowed transformations to only the ones you actually need.\n\n**Default settings:**\n\n```php\n// site/config/config.php\n\nreturn [\n    'moritzebeling.headless-image-transformations' =\u003e [\n        /*\n        These values can either be:\n        - false (not allowed, will be ignored and might fallback to Kirby's default settings)\n        - true (any value is allowed, do not use in production)\n        - array (list of allowed values)\n        */\n        'allowed' =\u003e [\n            'autoOrient' =\u003e false,\n            'crop'       =\u003e [true,false],\n            'blur'       =\u003e false,\n            'grayscale'  =\u003e false,\n            'height'     =\u003e [40,80,160,240,360,480,640,720,960,1280,1440,1920,2560,3200],\n            'quality'    =\u003e false,\n            'width'      =\u003e [40,80,160,240,360,480,640,720,960,1280,1440,1920,2560,3200],\n        ]\n    ],\n];\n```\n\nWhen sticking to the default options, it is only allowed to request thumbs with the specified widths and heights as well as cropping. If you need the other options, you should enable them via your `site/config/config.php` file.\n\nYou can also set some thumbnail option defaults for Kirby:\nhttps://getkirby.com/docs/reference/system/options/thumbs\n\n## Development\n\n1. Install a fresh Kirby StarterKit\n2. `cd site/plugins`\n3. `git clone` this repo\n\nRoadmap:\n- [ ] Discuss if preset images sizes make sense\n- [ ] Check if browser caching works as expected\n\n## ☕️ Support\n\nIf you like this plugin, I would be glad if you would invite me for a coffee via [PayPal](http://more.moritzebeling.com/support).\nIf you have any ideas for further development or stumble upon any problems, please open an issue or PR. Thank you!\n\n## Warranty\n\nThis plugin is work in progress and comes without any warranty. Use at your own risk.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoritzebeling%2Fkirby-headless-image-transformations","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoritzebeling%2Fkirby-headless-image-transformations","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoritzebeling%2Fkirby-headless-image-transformations/lists"}