Nova Config Reference

The nova.config.json file lives at the monorepo root and drives every Nova command. This page documents each section and its fields.

Use the nova utility initialize wizard to create or update this file interactively.

`project`

Describes the project identity, display info, and build metadata.

Field	Type	Description
`name.slug`	`string`	URL-safe project identifier. Letters, numbers, hyphens, and underscores only. The 214-character npm limit is enforced by the `nova utility initialize` wizard; the parser only requires a non-empty trimmed string.
`name.title`	`string`	Human-readable project name for display.
`description.short`	`string`	One-line summary used in `package.json` and meta tags.
`description.long`	`string`	Extended description for README and documentation pages.
`keywords`	`string[]`	Search keywords (max 50 characters each).
`legalName`	`string`	Legal entity name used in LICENSE and copyright notices.
`pronouns`	`string`	Controls first-person wording in generated files. One of `"business"` (we/our) or `"personal"` (I/my).
`platforms`	`string[]`	Supported platforms for bug report dropdowns. One or more of `"nodejs"`, `"swift"`, `"android"`, `"java"`, `"kotlin"`, `"csharp"`, `"php"`, `"python"`, `"macos"`, `"linux"`, `"windows"`. Unknown values are dropped.
`startingYear`	`number`	Year the project began (integer >= 1970). Used in LICENSE copyright ranges.
`license`	`string`	License identifier. One of `"AGPL-3.0"`, `"Apache-2.0"`, `"BSD-2-Clause"`, `"BSD-3-Clause"`, `"BSL-1.0"`, `"CC0-1.0"`, `"EPL-2.0"`, `"GPL-2.0"`, `"GPL-3.0"`, `"LGPL-2.1"`, `"MIT"`, `"MPL-2.0"`, `"Proprietary"`, or `"Unlicense"`.

json

{
  "project": {
    "name": {
      "slug": "example",
      "title": "Example"
    },
    "description": {
      "short": "A sample Nova project.",
      "long": "Extended description for documentation and README files."
    },
    "keywords": ["example", "nova"],
    "legalName": "Example Author LLC",
    "pronouns": "business",
    "platforms": ["nodejs", "macos", "linux", "windows"],
    "startingYear": 2025,
    "license": "MIT"
  }
}

`entities`

An array of people and organizations associated with the project.

Field	Type	Description
`name`	`string`	Display name.
`email`	`string`	Contact email (must contain `@` and a domain).
`url`	`string`	Profile or organization URL (`http://` or `https://`).
`roles`	`string[]`	One or more of `"author"`, `"contributor"`, `"supporter"`.

json

{
  "entities": [
    {
      "name": "Example Author",
      "email": "[email protected]",
      "url": "https://example.com/author",
      "roles": ["author"]
    },
    {
      "name": "Example Collaborator",
      "email": "[email protected]",
      "url": "https://example.com/collaborator",
      "roles": ["contributor", "supporter"]
    }
  ]
}

`emails`

Canonical contact addresses referenced by tools and metadata.

Field	Type	Description
`bugs`	`string`	Email for bug reports and support.

json

{
  "emails": {
    "bugs": "[email protected]"
  }
}

`github`

Identifies the GitHub repository and configures repository-level metadata that the GitHub recipes synchronize. Consumed by the nova recipe github commands.

Field	Type	Description
`owner`	`string`	Repository owner (user or organization). Must match `/^[A-Za-z0-9-]+$/`.
`repo`	`string`	Repository name. Must match `/^[A-Za-z0-9._-]+$/`.
`recipes`	`object`	Optional. Toggles for repository-level sync recipes. See Recipes Fields below.
`topics`	`string[]`	Optional. Repository topics. An empty array is preserved and clears topics on sync.
`features`	`object`	Optional. Toggles for repository features (issues, wiki, projects, discussions). See Features Fields below.
`policies`	`object`	Optional. Repository policy settings (visibility, default branch, merge methods, branch deletion). See Policies Fields below.

Recipes Fields

Booleans that enable or disable each repository-level sync recipe.

Field	Type	Description
`sync-identity`	`boolean`	Optional. Synchronizes repository description, homepage, and topics.
`sync-features`	`boolean`	Optional. Synchronizes the repository feature toggles in `features`.
`sync-policies`	`boolean`	Optional. Synchronizes the repository policy settings in `policies`.

Features Fields

Booleans controlling which repository features are enabled. Each field is optional; omitted fields leave the corresponding GitHub setting untouched.

Field	Type	Description
`issues`	`boolean`	Optional. Enables the Issues tab.
`wiki`	`boolean`	Optional. Enables the Wiki tab.
`projects`	`boolean`	Optional. Enables the Projects tab.
`discussions`	`boolean`	Optional. Enables the Discussions tab.

Policies Fields

Repository policy settings. Each field is optional.

Field	Type	Description
`visibility`	`string`	Optional. One of `"public"`, `"private"`, or `"internal"`.
`defaultBranch`	`string`	Optional. Default branch name (e.g., `"main"`).
`mergeMethods`	`object`	Optional. Per-method enablement: `merge`, `squash`, `rebase`. Each is a boolean.
`autoDeleteHeadBranch`	`boolean`	Optional. When `true`, GitHub deletes the head branch after a pull request is merged.

json

{
  "github": {
    "owner": "example-org",
    "repo": "example-project",
    "recipes": {
      "sync-identity": true,
      "sync-features": true,
      "sync-policies": true
    },
    "topics": ["nova", "monorepo", "typescript"],
    "features": {
      "issues": true,
      "wiki": false,
      "projects": false,
      "discussions": true
    },
    "policies": {
      "visibility": "public",
      "defaultBranch": "main",
      "mergeMethods": {
        "merge": false,
        "squash": true,
        "rebase": false
      },
      "autoDeleteHeadBranch": true
    }
  }
}

`workflows`

An array of GitHub Actions workflow entries consumed by nova generate github workflows. Each entry maps to one generated .yml file.

Field	Type	Description
`template`	`string`	Name of a bundled workflow template: `"publish"`, `"lock-inactive-issues"`, or `"check-sponsor-gated-issues"`.
`name`	`string`	Required label appended to the output filename and workflow name. Must be unique within the same template.
`triggers`	`array`	Triggers for the template. Each is a bare string or an object such as `{ "name": "push", "branches": ["main"] }`.
`build`	`string[]`	Optional. Workspace paths (keys from `workspaces`) that the `check` / `build` step should filter to.
`deploy`	`object[]`	Optional. Publish destinations for the `publish` template. Each destination has `to`, `path`, `after`, `with`.
`with`	`object`	Optional. Key-value pairs that remap secret / variable names or supply values for literal template variables.

Field names changed in the rebuilt generator: suffix is now name, scopes is now build, targets is now deploy, and settings is now with. The former top-level depends-on moved onto the workflow-run trigger object as a workflows array.

Deploy Fields

Each entry in the deploy array pins one publish destination to a workspace.

Field	Type	Description
`to`	`string`	One of: `"npm"`, `"github-action"`, `"github-packages"`, `"docker-hub"`, `"ghcr"`, `"cloudflare-pages-docusaurus"`, `"cloudflare-workers"`, `"github-pages-docusaurus"`, `"vercel-nextjs"`.
`path`	`string`	Path to the workspace that owns the destination (e.g., `"./packages/nova"`).
`after`	`string[]`	Optional. Paths of other same-type destinations that must finish publishing before this one starts.
`with`	`object`	Optional. Key-value pairs for this destination that remap names or supply literal values, overriding the workflow-level `with`.

Variable Formats

Each template declares variables with one of three formats. The format determines how values in with are used:

Format	What happens
`secret`	Produces `${{ secrets.NAME }}` in the YAML. A `with` value remaps the secret name.
`var`	Produces `${{ vars.NAME }}` in the YAML. A `with` value remaps the variable name.
`literal`	Replaces the placeholder with the exact string from `with`. Must be provided or the entry is skipped.

Output Filenames

Generated files follow the pattern nova-{template}-{name}.yml under .github/workflows/.

json

{
  "workflows": [
    {
      "template": "lock-inactive-issues",
      "name": "project",
      "triggers": ["schedule-weekly"]
    },
    {
      "template": "publish",
      "name": "project",
      "triggers": ["release"],
      "build": [
        "./packages/core",
        "./packages/preset",
        "./apps/docs"
      ],
      "deploy": [
        {
          "to": "npm",
          "path": "./packages/core"
        },
        {
          "to": "npm",
          "path": "./packages/preset",
          "after": ["./packages/core"]
        },
        {
          "to": "cloudflare-pages-docusaurus",
          "path": "./apps/docs"
        }
      ]
    }
  ]
}

`urls`

Canonical links with validation and normalization.

Field	Type	Description
`homepage`	`string`	Project homepage URL.
`repository`	`string`	Source repository URL. Accepts `git:`, `git+https:`, `git+ssh:`, `git+http:`, `http://`, `https://`.
`bugs`	`string`	Issue tracker URL.
`license`	`string`	License file URL.
`logo`	`string`	Project logo URL.
`documentation`	`string`	Documentation site URL.
`npm`	`string`	npm package page URL.
`docker`	`string`	Docker image registry page URL.
`fundSources`	`string[]`	Funding URLs (entered comma-separated in the wizard, saved as a list).
`privacyPolicy`	`string`	Privacy policy URL. Appears in generated GitHub issue templates.
`termsOfUse`	`string`	Terms of use URL. Appears in generated GitHub issue templates.

json

{
  "urls": {
    "homepage": "https://example.com",
    "repository": "https://github.com/example/example-project",
    "bugs": "https://github.com/example/example-project/issues",
    "license": "https://github.com/example/example-project/blob/main/LICENSE",
    "logo": "https://example.com/assets/logo.svg",
    "documentation": "https://docs.example.com/project",
    "npm": "https://www.npmjs.com/package/example-project",
    "docker": "https://hub.docker.com/r/example/example-project",
    "fundSources": [
      "https://github.com/sponsors/example",
      "https://opencollective.com/example"
    ],
    "privacyPolicy": "https://example.com/privacy",
    "termsOfUse": "https://example.com/terms"
  }
}

`workspaces`

A map of relative paths to workspace definitions. Each key is a path from the monorepo root (e.g., "./", "./apps/docs", "./packages/nova").

Field	Type	Description
`name`	`string`	Package name for `package.json`. Must follow the naming pattern for its role. See Workspace Rules for details.
`displayName`	`string`	Optional. Human-readable label used by Nova commands and tooling (e.g., status output, generated docs).
`role`	`string`	Workspace role: `"project"`, `"docs"`, `"config"`, `"app"`, `"package"`, `"tool"`, or `"template"`. See Workspace Rules for details.
`policy`	`string`	Workspace policy: `"freezable"`, `"trackable"`, or `"distributable"`. See Workspace Rules for details.
`recipes`	`object`	Optional. Enabled recipes and their settings, keyed by recipe name. Each value is a tuple: `[enabled]` or `[enabled, settings]`.
`dotenv`	`object`	Optional. Environment variables for the workspace's generated `.env` files and, on a publish `build` scope, its build-time environment. See Dotenv Fields below.

Dotenv Fields

warning

Retired — use environment instead

The per-workspace dotenv block is retired. Environment variables and secrets now live in the top-level environment block, classified by a required secret flag and delivered by a required buildOnly flag. A config that still declares dotenv, visibility, or from is a load-time error. The fields below document the old shape for reference only.

A dotenv block holds a variables array, and each entry describes one environment variable. The nova generate must-haves dotenv command reads these to write .env and .env.sample, while the publish workflow reads the visibility to decide what gets baked into a static build.

Field	Type	Description
`key`	`string`	Environment variable name written to the workspace's `.env` files.
`defaultValue`	`string`	Value written to `.env.sample`; the `.env` entry is left blank so real secrets stay out of version control.
`visibility`	`string`	Optional. `"public"` bakes the value into the build; `"private"` never bakes it. Required on any variable of a publish `build` scope.
`from`	`string`	Optional. On a `public` variable, the GitHub Variable its value is read from at build time (defaults to `key`). On a `private` variable, the GitHub Secret its value syncs from at deploy time — required and explicit on `cloudflare-workers` and `vercel-nextjs`.

A public variable is client-exposed and read from a GitHub Variable when the publish build job writes the scope's .env, so it suits values that ship to the browser (analytics IDs, public site keys). A private variable is a backend or runtime secret that Nova never bakes into the build.

On a cloudflare-workers or vercel-nextjs deploy, a private variable must declare a from and Nova syncs its value from that GitHub Secret into the platform's runtime-secret store. See Runtime Secret Sync for the reconcile and full-authority behavior.

Set from on a public variable when two apps declare the same key but need different per-app values, so each points at its own GitHub Variable.

json

{
  "workspaces": {
    "./": {
      "name": "example-project",
      "role": "project",
      "policy": "freezable",
      "recipes": {
        "cleanup": [true, { "removeUnknownKeys": true, "reorderKeys": true }],
        "normalize-dependencies": [true, { "pinDependencyVersions": true }],
        "sync-identity": [true],
        "sync-ownership": [true]
      }
    },
    "./packages/nova": {
      "name": "@company/example",
      "displayName": "Example Core",
      "role": "package",
      "policy": "distributable",
      "recipes": {
        "cleanup": [true, { "removeUnknownKeys": true, "reorderKeys": true }],
        "sync-identity": [true, { "description": true, "keywords": true }],
        "sync-ownership": [true, { "homepage": true, "bugs": true, "author": true }]
      }
    },
    "./apps/docs": {
      "name": "example-docs",
      "role": "docs",
      "policy": "freezable"
    }
  }
}

`environment`

Every environment variable and secret in the repository lives here, classified by a required secret flag and grouped by namespace. The nova generate must-haves dotenv command reads environment.apps to write each app's .env and .env.sample, and the publish workflow delivers each value by kind.

Field	Type	Description
`global`	`object`	Optional. Account-wide keys (deploy credentials, managed-only secrets) under one shared `prefix`. See Global Fields.
`apps`	`object`	Optional. Per-app environment values, keyed by the app's workspace path. See Apps Fields.
`workflows`	`object`	Optional. Workflow-config prefixes, keyed by workflow name. See Workflows Fields.

Each group declares a prefix that Nova joins to every key to form its GitHub name (for example, CBN_ joined to PUBLIC_SITE_KEY becomes CBN_PUBLIC_SITE_KEY). Prefixes must be disjoint, must not reuse the reserved GITHUB_ namespace, and a key must not repeat its own prefix.

Global Fields

global holds account-wide keys under a single prefix. Its variables are managed-only — provisioned on GitHub but not delivered to a build or server — so each carries only secret. Account-scoped deploy credentials (such as a Cloudflare API token) also derive their GitHub name from this prefix.

Field	Type	Description
`prefix`	`string`	Required. The uppercase namespace joined to every `key`.
`variables`	`array`	Optional. Managed-only values, each with a `key` and a `secret` flag.

Apps Fields

apps is keyed by an app workspace path that matches a workspaces entry. Each app declares a prefix and the variables delivered to its build and servers.

Field	Type	Description
`prefix`	`string`	Required. The uppercase namespace joined to every `key`.
`variables`	`array`	Optional. App environment values. See Value Fields.

Value Fields

Field	Type	Description
`key`	`string`	Environment variable name, joined to the group's `prefix` to form the GitHub name.
`secret`	`boolean`	Required. `true` stores the value as a GitHub Secret (encrypted); `false` as a GitHub Variable (plaintext).
`buildOnly`	`boolean`	Required on an app value. `true` delivers it to the build; `false` syncs it to every server-bearing deploy target. See Environment Variables and Secrets.
`defaultValue`	`string`	Optional, non-secret only. Seeds `.env.sample`; on a `buildOnly: true` value it is also the build fallback. Rejected on a `secret: true` value.

Workflows Fields

workflows is keyed by a workflow name and gives that workflow's config keys their own prefix.

Field	Type	Description
`prefix`	`string`	Required. The uppercase namespace joined to every `key`.

json

{
  "environment": {
    "global": {
      "prefix": "ACCT_",
      "variables": [
        { "key": "NPM_TOKEN", "secret": true }
      ]
    },
    "apps": {
      "./apps/web": {
        "prefix": "WEB_",
        "variables": [
          { "key": "PUBLIC_ANALYTICS_ID", "secret": false, "buildOnly": true, "defaultValue": "" },
          { "key": "AMAZON_REGION", "secret": false, "buildOnly": false, "defaultValue": "us-east-1" },
          { "key": "STRIPE_SECRET_KEY", "secret": true, "buildOnly": false }
        ]
      }
    },
    "workflows": {
      "sponsor-check": {
        "prefix": "SGI_"
      }
    }
  }
}