TwicPics Domains

Upon creating your account, your very own TwicPics domain is available. All your image interactions will now be made through it and you will be able to attach as many image sources as you want using our powerful path system.

Single Domain

Pay-As-You-Go customers get a unique, auto-generated subdomain. Pro customers can create organizations encompassing multiple subdomains whose names they can choose. Enterprise customers can even go beyond subdomains and use their own domain names if they so desire.

As an introduction to TwicPics, a single domain is plenty enough given you are not limited to a single source of images per domain. We will explore the advantages of multiple domains later on in this documentation nonetheless.

Single Path

A TwicPics domain is, simply put, a collection of paths that each reference a folder online.

The simplest possible configuration is to have the root of your domain (/) pointing to the root of your media server.

For instance, if the root of <sub>.twic.pics points to https://media.my-company.com/ then https://<sub>.twic.pics/my-image.png will point to https://media.my-company.com/my-image.png.

Passing through the TwicPics domain has the following advantages:

• the image is optimized right away: WebP will be delivered to browsers that support the format, users with a bad connection will get a lighter image, etc
• the image will be delivered through the TwicPics CDN, reducing latency and removing pressure on your own media server
• the image can now be transformed using the TwicPics URL API
• the actual location of the image is private, only TwicPics knows where it is located
• you can further protect your images using source authentication and/or default manipulations
• crucially, you decide and control where your images are stored and you are free to move them wherever your want without breaking your website, provided you update your TwicPics domain configuration in a timely fashion

Furthermore, even if TwicPics only recognizes AVIF, GIF, HEIF, JPEG, PNG and WebP files as transformable images, other files will pass through, unaltered.

Multiple Paths

What if your images are spread on several servers?

While it is quite common for most assets to be stored on a media server (say https://media.my-company.com/), some are still usually kept on the same server as the website (say https://www.my-company.com/).

Thankfully, the solution is as simple as creating two paths on the same domain!

One possible configuration would be:

which would make it so:

• https://<sub>.twic.pics/media/logo.png points to https://media.my-company.com/logo.png
• https://<sub>.twic.pics/web/banner.png points to https://www.my-company.com/banner.png

If you are using the TwicPics Script, then:

• a data-twic-src referencing image:media/logo.png points to https://media.my-company.com/logo.png
• a data-twic-src referencing image:web/banner.png points to https://www.my-company.com/banner.png

Paths do not have to be on the same hierarchical level. For instance, the following configuration:

would make it so:

• https://<sub>.twic.pics/media/logo.png still points to https://media.my-company.com/logo.png
• while https://<sub>.twic.pics/banner.png now points to https://www.my-company.com/banner.png

Keep in mind that doing so will make it impossible to access any image inside https://www.my-company.com/media/.

Also:

• a path can point to a subfolder of your server rather than its root
• you can have more than two paths in your domain
• two paths can point to the same server

See this configuration as a more complex example:

Using Absolute URLs as Paths

Paths can have any format and as such, they can look like absolute URLs.

For instance, the following configuration:

would make it so https://<sub>.twic.pics/https://www.my-company.com/assets/image.png points to https://www.my-company.com/assets/image.png.

Nothing impressive so far but it can come in handy when combined with the TwicPics Script.

Since the Script understands relative URLs in both data-twic-src, data-twic-poster and data-twic-background attributes, you can seamlessly handle assets located on the same server as your webpages.

Let's say https://www.my-company.com/my-page.html contains the following img element:

<img data-twic-src="assets/image.png">

This will be rightfully understood as https://www.my-company.com/assets/image.png and the image will be optimized by TwicPics automagically.

Multiple Subdomains

If you are a Pro or Enterprise customer, you can create Organizations and those Organizations can have multiple domains that can be named as you please.

This is pretty handy in order to switch from one environment to another, say between your production and staging environment.

Here is an example of such a two-domains configuration:

All you have to do now is reference the domain corresponding to the environment you are currently in (prod.twic.pics or staging.twic.pics) throughout your code base, which is usually as simple as setting a single variable and using it wherever you reference your TwicPics domain.

A Path of Many Options

There are a lot more options available on paths and you can learn more about them in the dedicated section of the documentation but, in a nutshell:

• authentication,
• fallbacks for non-existing assets,
• default manipulations,
• custom headers to be sent to your origin server,
• control over metadata filtering,
• canonical link header generation for SEO,
• and watermarking!

That's a lot so make sure to check them all out.