Mapping Domains

Domain Mappings are a concept in Freestyle for routing traffic to deployments. They allow you to programmatically control where traffic flows from domains to deployments.

Semantics

Freestyle deployments are immutable, meaning that once you create a deployment it does not change and cannot be deleted.

Domain mappings are mutable traffic mappings that go from domain -> deployment.

Domain Mappings on Deployments

When you create a deployment with a list of domains in its configuration, Freestyle is automatically creating those domain mappings to that deployment.

import { Freestyle } from "freestyle-sandboxes";

const freestyle = new Freestyle({
  apiKey: process.env.FREESTYLE_API_KEY!,
});

async function deploy() {
  const result = await freestyle.deployWeb(
    {
      kind: "files",
      files: {
        /*...*/
      },
    },
    {
      domains: ["some.style.dev", "your.usersdomain.com"], // The domains here create domain mappings to the deployment
    }
  );
}

Creating Domain Mappings

This code creates a simple domain mapping from example.style.dev to a deployment with ID deployment-id. If example.style.dev was already mapped to another deployment, it will be updated to point to the new deployment.

import { Freestyle } from "freestyle-sandboxes";

const freestyle = new Freestyle({
  apiKey: process.env.FREESTYLE_API_KEY!,
});

async function createDomainMapping() {
  const result = await freestyle.insertDomainMapping({
    domain: "example.style.dev",
    deploymentId: "deployment-id", // The ID of the deployment you want to map the domain to
  });

  console.log("Created domain mapping:", result);
}

Deleting Domain Mappings

To delete a domain mapping, you can use the deleteDomainMapping method. This will remove the mapping for the specified domain, but will not delete the deployment itself. When a domain is pointed at Freestyle, but has no domain mapping, it returns a Site Not Found page to visitors.

import { Freestyle } from "freestyle-sandboxes";

const freestyle = new Freestyle({
  apiKey: process.env.FREESTYLE_API_KEY!,
});

async function removeDomainMapping() {
  const result = await freestyle.removeDomainMapping("example.style.dev");

  console.log("Deleted domain mapping:", result);
}

Unpublishing a Website

When you want to unpublish a website, rather than deleting the deployment, instead you should unmap every domain it uses. This will make the deployment inaccessible to any users and effectively inactive.

While you could do this by unmapping each domain to point at nothing, a nicer approach is to remap them to a "built with us" page. You can do this by creating a deployment with whatever you want to say about yourself, saving its ID, and then remapping all the domains of deployments you want to take down to point at it.

When users see a "Site not found" page, even if its their fault for not paying, they don't know that and blame you. By adding this page, its clear to them that your servers are working, and that they need to go check with you on whats going on.

Relevant Other docs

• Deploying Websites
• Verifying Custom Domains