URL Aliases
URL aliases let you define short, memorable scheme names that map to full HTTP base URLs. Instead of embedding long CDN or storage URLs into every client request, you register an alias once in server configuration and use the short name in request paths.
Aliases are especially useful to avoid hardcoding full CDN URLs in client code. If you ever need to switch CDN providers or change your base URL, you only need to update the server configuration - no client changes required.
Configuration
Set the URL_ALIASES environment variable to a comma-separated list of name=https://base.url pairs:
URL_ALIASES=mycdn=https://assets.example.com,thumbs=https://thumbs.example.com
Each alias name must be a plain alphanumeric string. The base URL must start with http:// or https://.
URL Scheme
To use an alias in a request, use the alias name as the scheme followed by a single slash and the path:
/<params>/aliasname:/path/to/image.jpg
PreviewProxy resolves this by appending the path to the alias base URL:
aliasname:/path/to/image.jpg -> https://base.url/path/to/image.jpg
Example:
With URL_ALIASES=mycdn=https://assets.example.com:
/w=400/mycdn:/products/photo.jpg
Resolves to:
https://assets.example.com/products/photo.jpg
Multiple Aliases Example
URL_ALIASES=mycdn=https://assets.example.com,thumbs=https://thumbs.example.com,media=https://media.cdn.net
| Alias | Base URL | Example Request | Resolves To |
|---|---|---|---|
mycdn | https://assets.example.com | /w=400/mycdn:/products/photo.jpg | https://assets.example.com/products/photo.jpg |
thumbs | https://thumbs.example.com | /h=200/thumbs:/avatars/user1.jpg | https://thumbs.example.com/avatars/user1.jpg |
media | https://media.cdn.net | /format=webp/media:/videos/poster.png | https://media.cdn.net/videos/poster.png |
Reserved Names
The alias names s3 and local are reserved for the built-in S3 and local filesystem sources. Defining an alias with either of these names will have no effect - they will never be reachable as aliases regardless of the URL_ALIASES configuration.