> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useshipd.com/llms.txt
> Use this file to discover all available pages before exploring further.

# defineFlags

> Authoring API for shipd.config.ts — types, defaults, tags, lifecycle.

## Overview

```ts theme={null}
import { defineFlags } from "shipdit/config";

export default defineFlags({
  "new-checkout": { type: "boolean", default: false },
});
```

Validates at runtime, normalizes for the CLI, and preserves key / variant unions in the return type. CLI loads this file with jiti (`shipd.config.ts` by default).

## Flag types

```ts theme={null}
type FlagType = "boolean" | "variant" | "number" | "json";
```

### Boolean

```ts theme={null}
{
  type: "boolean",
  default: false,
  description?: string,
  tags?: readonly string[],
  deprecated?: boolean,
}
```

### Variant

```ts theme={null}
{
  type: "variant",
  variants: ["control", "semantic", "hybrid"] as const,
  default: "control", // must be a member of variants
  description?: string,
  tags?: readonly string[],
  deprecated?: boolean,
}
```

### Number

```ts theme={null}
{ type: "number", default: 3 }
```

### JSON

```ts theme={null}
{ type: "json", default: { mode: "strict", showPromo: true } }
```

## Normalized output

`defineFlags` returns `{ version: 1, flags: { ... } }` with `key`, `tags: string[]`, and `lifecycle: "active" | "deprecated"` on each flag (`deprecated: true` → `lifecycle: "deprecated"`).

## Typegen

`shipd push`, `shipd pull`, and `shipd types gen` write `src/generated/flags.ts` unless `.shipd/config.json` sets `typesOut`:

```json .shipd/config.json theme={null}
{
  "org": "fieldkit",
  "project": "web-app",
  "env": "production",
  "typesOut": "src/generated/flags.ts"
}
```

```ts theme={null}
export interface FlagDefinitions {
  "new-checkout": { type: "boolean"; default: false };
  "search-variant": {
    type: "variant";
    variants: "control" | "semantic" | "hybrid";
    default: "control";
  };
}

export type FlagKey = keyof FlagDefinitions;
export type BooleanFlagKey = /* keys whose type is boolean */;
export type VariantFlagKey = /* ... */;
export type NumberFlagKey = /* ... */;
export type JsonFlagKey = /* ... */;
```

Pass that interface to `createClient<FlagDefinitions>` and `createShipdReact<FlagDefinitions>()`.

## Scope reminder

| Field                                        | Scope          |
| -------------------------------------------- | -------------- |
| type, variants, tags, lifecycle, description | Project-global |
| default                                      | Per `--env`    |

Guides: [Define flags in code](/guides/define-flags).