Search Params
Here you will find all of the search parameter-based control mechanisms for Edgemesh® Server.
Flow Control
The search parameters below are used to control how requests flow through the Edgemesh® System.
em-cache
Controls for the Edgemesh® Cache.
Purge
Setting this search parameter to purge
will purge the cache for the current page or resource for your region.
This purge is region based. Anyone accessing the page from within the purged region will be served the new cached resources. If you need to purge globally, you will want to use the Portal or API.
https://example.com?em-cache=purge
Revalidate
Setting this search parameter to revalidate
will fetch the asset from the origin and update the cache in the background for your region. The difference between purge
and revalidate
is that the request will respond with the stale cached object until the background revalidation updates the cache. This is useful when a more performant stale response is more desirable than an un-cached response from the origin.
This revalidate is region based. Anyone accessing the page from within the revalidated region will be served the new cached resources once the background revalidation is completed. Until then they will receive a stale response. Revalidation happens automatically every 15 minutes in all regions (globally).
https://example.com?em-cache=revalidate
em-bypass
Bypass for Edgemesh® Optimizations.
Server
Setting this search parameter to server
will instruct Edgemesh® Server to skip all server-side optimizations for the given request. This is equivalent to navigating directly to your upstream origin.
https://example.com?em-bypass=server
Client
Setting this search parameter to client
will instruct Edgemesh® Client to skip all client-side optimizations for the given request. This is equivalent to requesting the given resource directly from the origin. Edgemesh® Server optimizations will still be applied where applicable.
https://example.com?em-bypass=client
All
Setting this search parameter to all
will instruct Edgemesh® Client and Server to skip all optimizations for the given request. This is equivalent to requesting the given resource directly from the origin as if there are no Edgemesh® Products installed.
https://example.com?em-bypass=all
Domain Un-sharding
The search parameters below are used by the Edgemesh® domain un-sharding feature. In most cases, you will not have to set any of these manually, but they are described here for clarity and to aid in custom solution development.
em-origin
This search parameter instructs Edgemesh® Server to fetch the given resource from the specified origin. It is defined as the hostname only (no protocol).
This search parameter is set automatically by the Edgemesh® Server optimizer and can be controlled by the
unshardScripts
,unshardCss
, andunshardImages
configuration options. You should not have to set this manually, but custom solutions can take advantage of domain un-sharding by defining this parameter.
https://example.com/script.js?em-origin=cdn.shopify.com
em-referrer-proto
This search parameter instructs Edgemesh® Server to set the request referer header to the specified protocol. It is defined as the protocol only (no colon or forward slashes).
This search parameter is set automatically by the Edgemesh® Server optimizer and can be controlled by the
unshardScripts
,unshardCss
, andunshardImages
configuration options. You should not have to set this manually, but custom solutions can take advantage of domain un-sharding by defining this parameter.
https://example.com/style.css?em-referrer-proto=https
em-referrer-host
This search parameter instructs Edgemesh® Server to set the request referer header to the specified hostname.
This search parameter is set automatically by the Edgemesh® Server optimizer and can be controlled by the
unshardScripts
,unshardCss
, andunshardImages
configuration options. You should not have to set this manually, but custom solutions can take advantage of domain un-sharding by defining this parameter.
https://example.com/style.css?em-referrer-host=cdn.shopify.com
Image Optimization
The search parameters below can be applied to images to control the Edgemesh® image optimization service.
em-format
Specify the format the image should be converted to. The auto
option will serve the AVIF
or WebP
format to browsers that support it. If not applicable or is not specified, the original format will be used. The lossless
option will bypass all optimizations for the image.
auto
- Select the best image format for the requesting browser.
AVIF
is preferred overWebP
.
avif
- Generate images in AVIF format if possible (with WebP as a fallback).
webp
- Generate images in Google WebP format. Set the quality to
100
to get the WebP lossless format.
json
- Instead of generating an image, outputs information about the image in JSON format. The JSON object will contain data such as image size (before and after resizing), source image's MIME type, and file size.
lossless
- Serve the image with no modifications or optimizations. This setting will override all other settings.
https://example.com/image.png?em-format=auto
https://example.com/image.png?em-format=avif
https://example.com/image.png?em-format=webp
https://example.com/image.png?em-format=json
https://example.com/image.png?em-format=lossless
em-quality
Specifies quality for images in JPEG
, WebP
, and AVIF
formats. The quality is on a 1-100
scale, but useful values are between 50
(low quality, small file size) and 90
(high quality, large file size). 85
is the default. When using the PNG format, an explicit quality setting allows the use of PNG8
(palette) variant of the format.
https://example.com/image.png?em-quality=50
em-width
Specifies the maximum width of the image in pixels. The exact behavior depends on the fit mode.
https://example.com/image.png?em-width=250
em-height
Specifies the maximum height of the image in pixels. The exact behavior depends on the fit mode.
https://example.com/image.png?em-height=250
em-dpr
Device Pixel Ratio. The default is 1
. A multiplier for width/height that makes it easier to specify higher DPI sizes in <img srcset />
.
https://example.com/image.png?em-dpr=1
em-background
Background color to add underneath the image. Applies only to images with transparency (for example, PNG). Accepts any CSS color, such as #RRGGBB and rgba(…).
https://example.com/image.png?em-background=%23RRGGBB
em-blur
Blur radius between 1 (slight blur) and 250 (maximum). Be aware that you cannot use this option to reliably obscure image content because savvy users can modify an image's URL and remove the blur option.
https://example.com/image.png?em-blur=50
em-border
Adds a border around the image. The border is added after resizing. Border width takes DPR into account, and can be specified either using a single width property or individually for each side (in pixels). The color can be any valid CSS value.
https://example.com/image.png?em-border=white;10
https://example.com/image.png?em-border=white;10;5;20;5
em-brightness
Increase the brightness by a factor. A value of 1.0
equals no change, a value of 0.5
equals half brightness, and a value of 2.0
equals twice as bright. 0
is ignored.
https://example.com/image.png?em-brightness=0.5
em-contrast
Increase the contrast by a factor. A value of 1.0
equals no change, a value of 0.5
equals low contrast, and a value of 2.0
equals high contrast. 0
is ignored.
https://example.com/image.png?em-contrast=0.5
em-gamma
Increase the exposure by a factor. A value of 1.0
equals no change, a value of 0.5
darkens the image, and a value of 2.0
lightens the image. 0
is ignored.
https://example.com/image.png?em-gamma=0.5
em-sharpen
Specifies the strength of the sharpening filter to apply to the image. The value is a floating-point number between 0
(no sharpening, default) and 10
(maximum). 1
is a recommended value for downscaled images.
https://example.com/image.png?em-sharpen=2
em-fit
Affects the interpretation of width
and height
. All resizing modes preserve the aspect ratio. Used as a string in Workers integration. Available modes are:
contain
- The image will be resized (shrunk or enlarged) to be as large as possible within the given
width
orheight
while preserving the aspect ratio. If you only provide a single dimension (for example, onlywidth
), the image will be shrunk or enlarged to exactly match that dimension.
scale-down
- Similar to
contain
, but the image is never enlarged. If the image is larger than the givenwidth
orheight
, it will be resized. Otherwise, its original size will be kept.
cover
- Resizes (shrinks or enlarges) to fill the entire area of
width
andheight
. If the image has an aspect ratio different from the ratio ofwidth
andheight
, it will be cropped to fit.
crop
- Image will be shrunk and cropped to fit within the area specified by
width
andheight
. The image will not be enlarged. For images smaller than the given dimensions, it is the same asscale-down
. For images larger than the given dimensions, it is the same ascover
. See also trim.
pad
- Resizes to the maximum size that fits within the given
width
andheight
, and then fills the remaining area with a background color (white by default). This mode is not recommended, since you can achieve the same effect more efficiently with the contain mode and the CSSobject-fit: contain
property.
https://example.com/image.png?em-fit=contain
https://example.com/image.png?em-fit=scale-down
https://example.com/image.png?em-fit=cover
https://example.com/image.png?em-fit=crop
https://example.com/image.png?em-fit=pad
em-trim
Specifies the number of pixels to cut off on each side. Allows removal of borders or cutting out a specific fragment of an image. Trimming is performed before resizing or rotation and takes DPR into account. Trim is defined as four numbers in pixels separated by a semicolon, in the form of top;right;bottom;left
.
https://example.com/image.png?em-trim=20;30;20;0
em-rotate
The number of degrees (90
, 180
, or 270
) to rotate the image. The width
and height
options refer to axes after rotation.
https://example.com/image.png?em-rotate=90
em-gravity
When cropping with em-fit=cover
or em-fit=crop
, this parameter defines the side or point that should not be cropped.
auto
- Selects focal point based on saliency detection (using maximum symmetric surround algorithm).
side
- A side (
left
,right
,top
,bottom
) or coordinates specified on a scale from 0.0 (top or left) to 1.0 (bottom or right), 0.5 being the center. The X and Y coordinates are separated by a semicolon. For example,0;1
means left and bottom,0.5;0.5
is center, and0.5;0.33
is a point in the top third of the image.
https://example.com/image.png?em-gravity=left
https://example.com/image.png?em-gravity=0.5;0.33
em-metadata
Controls the amount of invisible metadata (EXIF data) that should be preserved. Color profiles and EXIF rotation are applied to the image even if the metadata is discarded. Note that if the Polish feature is enabled, all metadata may have been removed already and this option will have no effect.
keep
- Preserves most of EXIF metadata, including GPS location if present.
copyright
- Discard all metadata except
EXIF
copyright tag. This is the default behavior forJPEG
images.
none
- Discard all invisible EXIF metadata. Currently,
WebP
andPNG
output formats always discard metadata.
https://example.com/image.png?em-metadata=keep
https://example.com/image.png?em-metadata=copyright
https://example.com/image.png?em-metadata=none
Static Pre-rendering
The search parameters below are related to the Edgemesh® pre-rendering service.
em-prerender
Setting this parameter instructs Edgemesh® Server to respond with the pre-rendered version of the website. This is the version that is served to bots and search engines. This parameter is provided to test and optimize pages for SEO.
https://example.com?em-prerender=true
https://example.com?em-prerender=false
Ad Protect
The search parameters below are related to the Edgemesh® ad fraud detection and prevention service.
em-emulate-bot
Setting this parameter instructs Edgemesh® Server to treat the requesting browser as a bot. This is used to test routing for unverified and malicious bots.
This parameter is a boolean and no value is required.
https://example.com?em-emulate-bot
Debugging and Profiling
The search parameters below are used to profile and debug Edgemesh® Server rendered pages.
em-profile
Setting this parameter instructs Edgemesh® Server to add Server-Timing
headers that will display server-side performance timings in supporting developer tools.
This parameter is a boolean and no value is required.
https://example.com?em-profile
em-debug
Enabling this parameter on Edgemesh® Server provides additional debugging details. Currently, it stops dynamic fragments from removing configuration parameters in server responses, allowing you to view their setup directly in the developer tools inspector instead of referring back to the source code. Future updates will expand this parameter's functionality to include more debugging information as new use cases are identified.
This parameter is a boolean and no value is required.
https://example.com?em-debug
Config Overrides
Configuration options can be overridden via search parameters to test different values locally before deploying them globally. Each configuration option is prefixed with em and converted to kebab-case.
em-cdn-track
This parameter sets the deployment track for all static assets, namely the Edgemesh® Client script.
stable
- Production track. All customers run on this track unless a new feature is being tested on a customer's behalf.
canary
- This track is for testing features that are stable and ready to be promoted to production. Customers can set their staging sites to this track to run integration tests with new features.
nightly
- This track is used to test potentially unstable new features. Customer production sites are never set to this track. Only staging sites are eligible for this track.
https://example.com?em-cdn-track=canary
em-api-track
This parameter sets the deployment track for the Edgemesh API used to collect performance metrics and analytic data. You should not change this unless instructed to by an Edgemesh® Engineer.
stable
- Production track. All customers run on this track unless a new feature is being tested on a customer's behalf.
canary
- This track is for testing features that are stable and ready to be promoted to production. Customers can set their staging sites to this track to run integration tests with new features.
nightly
- This track is used to test potentially unstable new features. Customer production sites are never set to this track. Only staging sites are eligible for this track.
https://example.com?em-api-track=canary
em-enable-prerender
This parameter can be used to enable or disable the static prerender feature.
https://example.com?em-enable-prerender=true
em-enable-caching
This parameter can be used to enable or disable the edge caching feature.
https://example.com?em-enable-caching=true
em-revalidate-time
This parameter can be used to set the revalidation time for site resources. Pages are continuously revalidated. The value is the number of seconds before the cached responses are revalidated.
https://example.com?em-revalidate-time=600
em-default-max-age
This parameter can be used to set the default max-age a resource will exist in the edge cache. This value is only used if the upstream origin does not provide a cache-control header.
https://example.com?em-default-max-age=3600
em-enable-analytics
This parameter can be used to enable or disable the tag-less tracking and edge analytics feature.
https://example.com?em-enable-analytics=true
em-enable-image-optimization
This parameter can be used to enable or disable the image optimization feature.
https://example.com?em-enable-image-optimization=true
em-default-image-quality
This parameter can be used to set the default image quality used by the image optimization feature. This can be overridden by specific assets using the em-quality attribute.
https://example.com?em-default-image-quality=85
em-enable-bot-protection
This parameter can be used to enable or disable the bot and ad fraud protection feature.
https://example.com?em-enable-bot-protection=true
em-unshard-images
This parameter can be used to enable or disable domain unsharding for images.
https://example.com?em-unshard-images=true
em-unshard-css
This parameter can be used to enable or disable domain unsharding for CSS.
https://example.com?em-unshard-css=true
em-unshard-scripts
This parameter can be used to enable or disable domain unsharding for scripts.
https://example.com?em-unshard-scripts=true
em-minify-html
This parameter can be used to enable or disable minification for HTML.
https://example.com?em-minify-html=true
em-minify-css
This parameter can be used to enable or disable minification for CSS.
https://example.com?em-minify-css=true
em-minify-scripts
This parameter can be used to enable or disable minification for scripts.
https://example.com?em-minify-scripts=true
em-inject-client
This parameter can be used to enable or disable injection of the Edgemesh® Client.
https://example.com?em-inject-client=true
em-shopify-plugin
This parameter can be used to enable or disable the Shopify platform plugin.
https://example.com?em-shopify-plugin=true