Configuration

When deploying to Freestyle, there are two distinct parameter groups:

Source: Where your code comes from—a Git repository, raw files, or a tarball link.
Options: Settings like domains, build configuration, entrypoint, timeout, and more.

Deployment Source

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

A Git repository containing your code. 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 the most common and recommended approach because it provides observability and debuggability.

import { freestyle } from "freestyle-sandboxes";

await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  branch: "main",        // optional, defaults to default branch
  rootPath: "./web",     // optional, defaults to root
  domains: ["app.style.dev"],
  build: true,
});

Code

A code snippet to deploy directly. Useful for simple deployments or rapid iteration.

import { freestyle } from "freestyle-sandboxes";

await freestyle.serverless.deployments.create({
  code: `
    import express from 'express';
    const app = express();
    app.get('/', (req, res) => res.send('Hello World'));
    app.listen(3000);
  `,
  nodeModules: {
    express: "^4.18.2",
  },
  domains: ["api.style.dev"],
});

Tar Link

A link to a gzipped tarball containing your files. This is useful when your main app is hosted on a serverless platform with request size limits. Instead of uploading files directly, your users upload to a storage service (like S3) and provide a signed link.

import { freestyle } from "freestyle-sandboxes";

await freestyle.serverless.deployments.create({
  tarUrl: "https://s3.example.com/signed-url/app.tar.gz",
  domains: ["app.style.dev"],
  build: true,
});

When deploying to Freestyle you never upload node_modules. Include your package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lock file in your source. Freestyle automatically installs dependencies, keeping deployments small and fast.

Deployment Options

Domains

Specify which domains to deploy to. You can use any *.style.dev subdomain that isn't taken, or any verified custom domain.

await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  domains: ["app.style.dev", "app.yourdomain.com"],
});

Entrypoint

The main file of your application. By default, Freestyle automatically detects the entrypoint for frameworks like Next.js, Vite, and Expo. For custom setups, specify it manually.

await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  entrypoint: "server.js",
  domains: ["app.style.dev"],
});

Node Modules

By default, Freestyle installs dependencies from your lockfile. You can also specify additional packages directly.

await freestyle.serverless.deployments.create({
  code: `import express from 'express'; /* ... */`,
  nodeModules: {
    express: "^4.18.2",
    cors: "^2.8.5",
  },
  domains: ["api.style.dev"],
});

Environment Variables

Environment variables available at runtime. These are not available at build time—use build options for that. Environment variables are tied to deployments; to change them, create a new deployment.

await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  envVars: {
    API_KEY: "your-api-key",
    DATABASE_URL: "postgres://...",
  },
  domains: ["app.style.dev"],
});

Timeout

The maximum idle time before your deployment is scaled down. Unlike most serverless platforms that timeout after the last request, Freestyle timeouts after the last TCP packet. This means websockets can stay alive indefinitely as long as you ping faster than the timeout.

await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  timeout: 60, // seconds
  domains: ["app.style.dev"],
});

Build

By default, Freestyle deploys files as-is. Set build: true to have Freestyle build your code. It automatically detects frameworks like Next.js, Vite, and Expo.

await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  build: true,
  domains: ["app.style.dev"],
});

For more control, pass build options:

await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  build: {
    command: "npm run build",    // custom build command
    outDir: "dist",              // output directory
    envVars: {                   // build-time environment variables
      NEXT_PUBLIC_API_URL: "https://api.example.com",
    },
  },
  domains: ["app.style.dev"],
});

Await

By default, the deployment request waits until the deployment is built and propagated before returning. Set await: false to return immediately with a deployment ID for polling.

const { deploymentId } = await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  await: false,
  domains: ["app.style.dev"],
});

// Poll for status
const status = await freestyle.serverless.deployments.get({ deploymentId });

Combined Example

All options can be combined:

import { freestyle } from "freestyle-sandboxes";

await freestyle.serverless.deployments.create({
  repo: "https://github.com/your-org/your-repo",
  branch: "production",
  rootPath: "./apps/web",

  domains: ["app.yourdomain.com", "app.style.dev"],
  entrypoint: "server.js",
  timeout: 120,

  envVars: {
    API_KEY: "runtime-secret",
  },

  build: {
    command: "npm run build",
    outDir: "dist",
    envVars: {
      NEXT_PUBLIC_API_URL: "https://api.example.com",
    },
  },
});