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 (max 214 chars).
`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: `"business"` (we/our) or `"individual"` (I/my).
`platforms`	`string[]`	Supported platforms for bug report dropdowns (e.g., `"nodejs"`, `"macos"`, `"linux"`, `"windows"`).
`startingYear`	`number`	Year the project began (integer >= 1970). Used in LICENSE copyright ranges.
`license`	`string`	SPDX license identifier (e.g., `"MIT"`, `"Apache-2.0"`, `"Proprietary"`).

{
  "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"`.

{
  "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.

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

`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"`.
`suffix`	`string`	Label appended to the output filename and workflow name. Required when the same template appears more than once.
`triggers`	`string[]`	Trigger names from the template's `triggers/` folder. Use an empty array for templates with baked-in triggers.
`depends-on`	`string[]`	Optional. Workflow references as `"{template}-{suffix}"`. Required for `workflow-run-*` triggers.
`scopes`	`string[]`	Optional. Workspace paths (keys from `workspaces`) that the `check` / `build` step should filter to.
`targets`	`object[]`	Optional. Publish destinations for the `publish` template. Each target has `type`, `workingDir`, and `needs`.
`settings`	`object`	Optional. Key-value pairs that remap secret / variable names or supply values for literal template variables.

Target Fields

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

Field	Type	Description
`type`	`string`	One of: `"npm"`, `"github-packages"`, `"docker-hub"`, `"ghcr"`, `"cloudflare-pages-docusaurus"`, `"github-pages-docusaurus"`, `"aws-amplify-nextjs"`, `"vercel-nextjs"`.
`workingDir`	`string`	Path to the workspace that owns the target (e.g., `"./packages/nova"`).
`needs`	`string[]`	Optional. Working directories of other same-type targets that must finish publishing before this one starts.

Variable Formats

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

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

Output Filenames

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

{
  "workflows": [
    {
      "template": "lock-inactive-issues",
      "suffix": "project",
      "triggers": ["schedule-weekly"]
    },
    {
      "template": "publish",
      "suffix": "project",
      "triggers": ["release"],
      "scopes": [
        "./packages/core",
        "./packages/preset",
        "./apps/docs"
      ],
      "targets": [
        {
          "type": "npm",
          "workingDir": "./packages/core"
        },
        {
          "type": "npm",
          "workingDir": "./packages/preset",
          "needs": ["./packages/core"]
        },
        {
          "type": "cloudflare-pages-docusaurus",
          "workingDir": "./apps/docs"
        }
      ],
      "settings": {
        "CLOUDFLARE_ACCOUNT_ID": "CLOUDFLARE_ACCOUNT_ID",
        "CLOUDFLARE_API_TOKEN": "CLOUDFLARE_API_TOKEN",
        "CLOUDFLARE_PROJECT_NAME": "CLOUDFLARE_PROJECT_NAME",
        "NPM_TOKEN": "NPM_TOKEN",
        "ROOT_WORKING_DIR": "./"
      }
    }
  ]
}

`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.
`github`	`string`	GitHub repository URL.
`npm`	`string`	npm package 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.

{
  "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",
    "github": "https://github.com/example/example-project",
    "npm": "https://www.npmjs.com/package/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`.
`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]`.

{
  "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",
      "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 }]
      }
    }
  }
}