Configure your initial Site settings

Last modified: October 29th, 2024

When you create a new Site on CloudCannon, the syncing and building steps require you to provide values for your Site configuration (e.g., SSG, hosting mode, and build commands). Rather than enter these details during Site creation, you can configure them in an initial site settings file.

The /.cloudcannon/initial-site-settings.json file is useful for streamlining your Site creation process. If you manage website templates or a Site repository that you might upload to CloudCannon multiple times, specifying your build configuration in advance will make this process more efficient.

To create an initial Site settings file:

Using your local development environment, navigate to the .cloudcannon folder in your root of your repository, or create one.
Create a new file named initial-site-settings.json.
Configure your settings.
Save your initial Site settings file to you Git repository.

The next time you use this repository to create a Site, CloudCannon will skip the relevant steps during syncing and build configuration.

You can update these values in your Site Settings at any time. CloudCannon only uses the initial Site settings file during Site creation.

If you create a Site by branching an existing one, CloudCannon will copy the Site settings from the original branch and ignore the initial Site settings file.

Options#

/.cloudcannon/initial-site-settings.json

copied

{
  "ssg": "hugo",
  "mode": "hosted",
  "build": {
    "install_command": "[ -f package.json ] && npm i",
    "build_command": "hugo -b /",
    "output_path": "public",
    "environment_variables": [
      {
        "key": "HUGO_CACHEDIR",
        "value": "/usr/local/__site/src/.hugo_cache/"
      }
    ],
    "preserved_paths": "resources/,.hugo_cache/",
    "preserve_output": false,
    "include_git": false,
    "manually_configure_urls": false,
    "hugo_version": "0.128.1",
    "ruby_version": "2.7.3",
    "node_version": "18",
    "deno_version": "1.40.2",
  }
}

Your initial Site settings file has the following options available:

ssg — String#

This key determines which Static Site Generator CloudCannon uses to provide build suggestions.

Value must be one of:

astro bridgetown docusaurus eleventy gatsby hugo jekyll legacy lume mkdocs nextjs nuxtjs other* static sveltekit

Note: The other value is called Custom SSG in the CloudCannon interface.

mode — String#

This key determines the hosting mode for your Site. Defaults to hosted.

Value must be either:

hosted - enables builds, visual editing, the Testing and Custom Domains, and page previews in the collection browser.
headless - disables builds for dynamic and externally-hosted Sites.

If you have not defined mode in your initial Site settings file, CloudCannon will build your Site during Site creation by default.

build — Object#

This key determines the initial build configuration settings for your Site. These options are ignored if mode is set to headless.

build.install_command — String#

This key determines the command to install any dependencies required for your Site to build.

build.build_command — String#

This key determines the command to build your Site.

build.output_path — String#

This key determines the location your Site will build to.

build.environment_variables — Array#

This key determines the environment variables required for your Site to build.

build.preserved_paths — String#

This key determines which paths to cache between builds. Value must be a comma separated list of path prefixes.

build.preserve_output — Boolean#

This key toggles whether CloudCannon will cache the files in your output directory between builds. Defaults to false.

build.include_git — Boolean#

This key toggles whether CloudCannon will include your Git folder in your build. Defaults to false.

build.manually_configure_urls — Boolean#

This key toggles whether CloudCannon will skip automatic URL detection and rely on the URLs specified in your CloudCannon configuration file. This is useful for larger Sites.

Setting this key to true will prevent CloudCannon from automatically assigning URLs to your files.

By default, this key is false (i.e., CloudCannon will automatically assign URLs to your files).

For more information, please read our documentation on manually configuring URLs.

build.hugo_version — String#

This key determines which version of Hugo is installed in your build environment.

build.ruby_version — String#

This key determines which version of Ruby is installed in your build environment.

build.node_version — String#

This key determines which version of Node is installed in your build environment.

build.deno_version — String#

This key determines which version of Deno is installed in your build environment.