Incremental Adoption

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:

mkdir configs
cd configs

2. Create a configuration model:

// main.tsp
model NotificationConfig {
  email: boolean;
  push: boolean;
}

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

2. Create config values file:

// 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:

$ npx @typeconf/typeconf build configs

4. Install SDK;

$ npm install --save @typeconf/sdk
# Or with React/Next
$ npm install --save @typeconf/react-sdk

5. Use the configuration in your app:

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:

   Copy

   // 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