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

# Incremental Adoption

> Learn how to gradually adopt Typeconf in your existing TypeScript project

Typeconf is designed to be adopted gradually in your existing TypeScript
projects. This guide will show you how to introduce Typeconf step by step
without having to rewrite your entire codebase or change your habits too much.

## Adding to existing project

Instead of create a separate package for Typeconf you can use it directly in
your project.

1. Create a directory which will contain your configurations:

```bash theme={null}
mkdir configs
cd configs
```

2. Create a configuration model:

```typescript theme={null}
// main.tsp
model NotificationConfig {
  email: boolean;
  push: boolean;
}

model UserSettings {
  theme: string;
  notifications: Record<NotificationConfig>;
}
```

2. Create config values file:

```typescript theme={null}
// user-settings.config.ts
import { UserSettings } from "./types/all.js";

const config: UserSettings = {
  theme: "light",
  notifications: {
    promo: {
      email: true,
      push: false,
    },
    alerts: {
      email: true,
      push: true,
    },
  },
};
export default config;
```

3. Generate config types and JSON:

```bash theme={null}
$ npx @typeconf/typeconf build configs
```

4. Install SDK;

```bash theme={null}
$ npm install --save @typeconf/sdk
# Or with React/Next
$ npm install --save @typeconf/react-sdk
```

5. Use the configuration in your app:

```typescript theme={null}
import { UserSettings } from "./configs/types";
import { readConfig } from "@typeconf/sdk";
// with React: import { readConfig } from "@typeconf/react-sdk/server";

function UserPreferences() {
  // Path to your config without extension
  const config: UserSettings = readConfig("configs/user-settings");

  // Your config is now fully typed and validated
  console.log(config.theme); // 'light'
}
```

## Best Practices for Incremental Adoption

1. **Start with New Features**: When adding new features, use Typeconf from the
   start rather than converting existing code.

2. **Identify High-Value Targets**: Focus on areas where type-safe configuration would provide the most value:

   * Complex configuration objects
   * Frequently changing settings
   * Areas prone to configuration errors

3. **Maintain Backward Compatibility**: When converting existing configurations:

   ```typescript theme={null}
   // Wrap existing config with Typeconf type while maintaining
   // the old interface
   const legacyConfig = {
     // ... your existing config
   } as TypeconfConfig;

   const newConfig: TypeconfConfig = readConfig(...);

   // Provide both until migration is complete
   export const config = {
     ...legacyConfig,
     ...newConfig
   };
   ```

## Integration with Other Tools

Typeconf works well with other tools in your ecosystem:

* **Environment Variables**: Use with `dotenv` or similar tools
* **CI/CD**: Add config generation in your CI pipeline
* **Testing**: Use in your test environment for consistent configuration