# Add typed package options

Package options define the values cluster authors may place under an
instance's `config`. Kix validates those values while evaluating the cluster,
before it renders Kubernetes manifests.

This guide extends the local package from
[Create a local package](/docs/how-to/author-packages-and-clusters/create-a-local-package/).

## Declare the options

Add an `options` attribute beside `meta` and `build`:

<Snippet {...typedOptions} />

Each `lib.mkOption` declaration can provide:

- `type`, which rejects values outside the package contract.
- `default`, which supplies a value when the instance omits the option.
- `description`, which explains the setting in generated reference material.
- `example`, when a useful value is not obvious from the default.

The example also composes `kix.options.healthCheck`, a shared option set. You
can combine shared option sets with package-specific fields using `//`, as the
post-deploy health-check guide demonstrates.

## Read options from the build function

Add `config` to the build function arguments. Read evaluated values from that
attribute set:

```nix title="web-package.nix"
build = {
  self,
  config,
  scope,
  kix,
  ...
}: {
  deployment = scope.mkDeployment {
    name = scope.instanceName;
    spec.replicas = config.replicas;
  };
};
```

`config` includes defaults as well as values set by the instance. Package code
therefore does not need a separate fallback for `replicas` or `environment`.

## Configure an instance

Set option values under `config`:

```nix title="cluster.nix"
instances.apps.web = {
  package = webPackage;
  config = {
    message = "Hello from production";
    environment = "production";
    replicas = 2;
  };
};
```

Fields not declared by the package are rejected. Values must also satisfy the
declared type.

## Check a validation error

For example, the package allows `preview` and `production` as environment
names. Setting `environment = "staging"` produces this error:

<Command {...invalidEnvironment} />

The error names the option and the rejected definition. Restore an allowed
value and check the cluster again:

<Command {...check} />

:::note[Reference]
See [`build`](/docs/reference/package-schema/build/),
[`options`](/docs/reference/package-schema/options/), and
[`root`](/docs/reference/package-schema/root/) for the complete package
interface.
:::