Static sites

Define a site

Use a site for documentation, a landing page, or a browser application that builds to static files. Use an app when your project needs a running server.

nubes.hclCopyCopied

version = 1

site "web" {
  source "directory" {
    path = "./dist"
  }

  builder = "pnpm build"
  routing = "directory"
}

path points to the built output, relative to the configuration directory. When the configuration is in .ai/, paths resolve from its parent. Site names start with a lowercase letter, contain lowercase letters, numbers, or hyphens, and have at most 20 characters.

Build and preview the plan

nubes build nubes.hcl
nubes plan nubes.hcl

nubes build runs the site’s builder command locally from the configuration’s working directory and checks the output. Install your project’s dependencies before building. Omit builder if you already generate the output separately.

nubes plan does not run builders, so the output directory must already exist. To discover and build multiple configurations in a repository, run nubes build ..

Choose routing

Use routing = "directory" (the default) for pages organized as files and directories, such as a generated documentation site.

Use routing = "spa" for a single-page application. Missing extensionless routes requested as HTML can fall back to the root index.html, letting the browser application handle navigation.

Deploy the output

nubes deploy nubes.hcl --project-id YOUR_PROJECT_ID --environment production

Deployment runs configured site builders before uploading the output. A failed build stops deployment. Use --skip-build to upload existing output after reviewing it. See deployment setup for authentication.

Sites are public. Only include files intended to be downloaded by visitors; never bundle server credentials. Each site artifact is limited to 12 MiB and 10,000 files. Use site.web.url in an app’s env to reference the deployed site URL.