# imgt

> A small, self-hosted image optimizer on Cloudflare. Sharp resizes public images to WebP; Workers Cache and a private R2 bucket cache derivatives. Original images are never stored.

Maintained by [FASHN AI](https://github.com/fashn-AI).
Source repository: [fashn-AI/imgt](https://github.com/fashn-AI/imgt).

This website is the project's documentation and playground. Deploy your own
instance and use your own endpoint for application image requests. The FASHN AI
demo is not a shared optimization service.

`GET /image?url=<encoded-HTTPS-source>&w=<width>&q=<quality>` returns WebP.
Use `URLSearchParams` to encode the source. Width is required and accepts any
integer from 1 to 3840 pixels. Quality accepts any integer from 1 to 100 and
defaults to 77. Each width and quality combination has its own cached derivative.

`ALLOWED_HOSTS` is a Worker environment variable containing original image
hostnames. Set it as Text in Cloudflare's Worker Settings → Variables and Secrets,
then select Deploy. The starter uses `keep_vars: true` and leaves this variable
out of `wrangler.jsonc` so dashboard values survive code deployments. An explicit
`vars.ALLOWED_HOSTS` would override the dashboard value even with `keep_vars`.
The frontend belongs here only if it serves originals. Exact entries allow
only that host; `*.example.com` allows subdomains but excludes `example.com`.
An empty list denies all sources; every redirect is checked against the list.
Sources must be public HTTPS URLs. Inputs: JPEG, PNG, WebP or AVIF, up to
25 MiB and 50 megapixels. Small images are not enlarged.

For Next.js, use the TypeScript custom loader in the guide below. Set
`images.qualities` to the values your components use; the custom loader forwards
each requested quality to imgt.
Relative local assets need a public HTTPS origin. `GET /health` checks Worker
configuration; use the smoke command in the deployment guide to verify the image
pipeline.

These Markdown resources are served from this deployment without GitHub access.
For local development, copy `.env.example` to `.env`.

Production storage setup requires an R2 lifecycle rule: in the private `imgt`
bucket, delete objects under `derivatives/` after 30 days. Deployment provisions
the bucket and `DERIVATIVES` binding but does not create this cleanup rule.
Expired optimized images are regenerated when requested. See the deployment
guide for setup and existing-bucket migration details.

## Guides

- [Overview and API](/index.md): Usage, defaults, deployment and local development.
- [Configuration](/docs/configuration.md): Allowed source hosts, matching rules, application settings and fixed limits.
- [Next.js integration](/docs/nextjs.md): `next.config.ts`, `image-loader.ts` and `app/page.tsx` examples.
- [Agent setup prompt](/docs/setup-prompt.md): A copyable prompt for self-hosting imgt and integrating it into a project using the user's own endpoint.
- [Deployment](/docs/deployment.md): Cloudflare setup, resource names, costs, cleanup, updates and troubleshooting.
- [Complete documentation](/llms-full.txt): All repository guides combined into one text file.

## Optional

- [Architecture](/docs/architecture.md): Request flow, cache policy, deduplication, deadlines and container lifecycle.
- [Performance](/docs/performance.md): Measured decisions behind the current runtime and defaults.
- [Contributing](/CONTRIBUTING.md): Checks, change scope and release expectations.
- [License](/LICENSE): MIT license.