To get started with deploying a website, you should read the Deploying a Website guide. This document will cover all of the advanced configuration options available for web deployments, and should be read after you've gone through the basics guide.

When deploying a website to Freestyle, there are two distinct parameter groups you can configure:

Source: This defines where your website's code is coming from, such as a Git repository, raw files, or a tarball link.
Configuration: This includes settings like the domains to deploy to, whether to build the code, entrypoint of the application, timeout behavior, and more.

Deployment Source

There are 3 distinct types of sources you can use to deploy a website:

Files: A set of the files you want to deploy. You can encode the files in base64 or utf-8, however in most cases base64 is recommended — images seem to get corrupted when using utf-8. The format of the files is a dictionary where the keys are the file paths and the values are dictionaries with the file content and its encoding.

files.json

{
  "source" : {
    "kind": "files",
    "files": {
      "index.js": {
        "content": "
        import {createServer} from 'http';
        createServer((req, res) => { res.end('Hello World\\n'); }).listen(3000);
        ",
        "encoding": "utf-8"
      },
    }
  }
}

Tar Link: A link to a tarball that contains the files you want to deploy. This is most commonly used when your main app working with Freestyle is hosted on a serverless platform with aggressive request size limits that make uploading the files directly impractical. Instead, you allow your users to upload their files directly to a storage service (like S3) and then provide a signed link to the tarball. The format of the tarball should be a gzipped tar archive.

tar.json

{
  "source": {
    "kind": "tar",
    "url": "https://s3.example.com/signedurl/to/tarball.tar.gz"
  }
}

Git: A Git repository that contains the files you want to deploy. This can be a public repository, a repository with basic authentication in the url, or any repository in your account on Freestyle Git. This is our most common, and recommended way to deploy a website, because it provides observability and debugability into your deployments. The format of the Git repository is a dictionary with the kind set to git and the url set to the repository URL, optionally with a branch key to specify the branch to deploy (defaulting to the default branch when not specified), and a dir key to specify the directory to deploy (defaulting to the root directory when not specified).

git.json

{
  "source": {
    "kind": "git",
    "url": "https://git.freestyle.sh/gitrepoid",
    "branch": "prod",
    "dir": "web"
  }
}

When deploying a website, its normal to start using the files source for debugging and iteration, but move to the tar or git sources as your needs evolve.

When deploying to Freestyle you never upload node modules. Instead, you should include your package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lock file in your source. Freestyle will automatically install the dependencies for you when deploying the website. This is done to ensure that your deployment is as small as possible, which makes it faster to deploy and easier to scale.

Deployment Configuration

Freestyle provides a wide range of configuration options for web deployments.

Entrypoint

The entrypoint is the main file of your application. This is the file that will be executed when your website is accessed. By default, Freestyle will automatically detect the entrypoint based on the source type. For example, if you are deploying a Next.js, Vite, or Expo application it will automatically find the correct entrypoint to run the application from. However, if you are using a custom setup, you can specify the entrypoint manually.

entrypoint.json

{
  "config": {
    "entrypoint": "index.js"
  }
}

Domains

You can specify the domains you want to deploy your website to. This is a list of domain names that you have verified ownership of. You can also specify subdomains of a domain you own. As long as they are pointing to Freestyle's servers and you own a parent of them, you can deploy to them.

Behind the scenes, this creates Domain Mappings that map the domains to your deployment.

domains.json

{
  "config": {
    "domains": ["yourdomain.com", "subdomain.yourdomain.com"]
  }
}

Node Modules

By default, Freestyle will automatically install the dependencies for your website based on the lock file you provide in your source. However, if you want to use specific npm packages that are not in your lock file, you can specify them in the nodeModules field of the configuration.

nodeModules.json

{
  "config": {
    "nodeModules": {
      "express": "^4.17.1",
      "cors": "^2.8.5"
    }
  }
}

Environment Variables

You can specify environment variables that will be available to your website at runtime. These environment variables are not available at build time. Environment variables are tied directly to deployments, if you want to change them you should make a new deployment with the new environment variables.

env.json

{
  "config": {
    "envVars": {
      "API_KEY": "your-api-key",
      "ANOTHER_VAR": "another-value"
    }
  }
}

Timeout

You can specify the timeout for your website. This is the maximum amount of time that Freestyle will wait for your website to respond before timing out. Unlike most serverless platforms that start the timeout after the start of the last request, Freestyle starts the timeout after the last TCP packet from the client is recieved. This means you can have long-running websockets as long as you are pinging at a rate that is less than the timeout.

timeout.json

{
  "config": {
    "timeout": 60
  }
}

Build

By default, Freestyle will not build your app — it will deploy the files its given as is. However, if you want to send Freestyle your unbuilt code to build and deploy, you can set the build field to true. Freestyle will automatically detect the framework and build the code for you. This is useful for frameworks like Next.js, Vite, and Expo.

build.json

{
  "config": {
    "build": true
  }
}

However, sometimes you want to set your own configuration options. If you want to add environment variables at build time you can set the build field to a dictionary with the envVars field set to the environment variables you want to set at build time. If you don't specify a command, Freestyle will still try to automatically detect the framework and build the code for you with the specified environment variables.

build-env.json

{
  "config": {
    "build": {
      "envVars": {
        "API_KEY": "your-api-key",
        "ANOTHER_VAR": "another-value"
      }
    }
  }
}

You can also set the build field to include a command to specify a custom build command, and outDir to specify the output directory of the build. This is useful if you are using a custom build tool or if your framework does not have a standard build command.

build-custom.json

{
  "config": {
    "build": {
      "command": "npm run build",
      "outDir": "dist"
    }
  }
}

All of these options can be combined together to create a custom build configuration. For example, you can set the build field to include environment variables, a custom command, and an output directory.

build-combined.json

{
  "config": {
    "entrypoint": "index.js",
    "domains": ["yourdomain.com"],
    "envVars": {
      "API_KEY": "your-api-key",
      "SOME_OTHER_KEY": "some-other-value"
    },
    "build": {
      "envVars": {
        "ANOTHER_VAR": "another-value"
      },
      "command": "npm run build",
      "outDir": "dist"
    }
  }
}

Next Steps

When deploying a website, we also have specific guide for preparing common frameworks like NextJS, Vite, and Expo. These guides will help you set up your website with the best practices for each framework.

Advanced Configuration