Quickstart

​

Overview

Typeconf is a library that allows you to write configs in Typescript and produce JSONs while keeping the type validation. With Typeconf you create a configuration directory or package and manage all your configs there. Then for your configs we generate types in your project language and you can read them just list a regular object in code.

​

Typespec schema

In Typeconf, configurations are defined using schemas and values separately. The schema is written using a TypeSpec-based language, which is a TypeScript-like syntax. Learn more about TypeSpec here. Here’s an example of such schema:

model FeedParams {
  fetchLimit: int32;
  rankScore: float32;
}

model AppParams {
  feedParamsByPostType: Record<FeedParams>;
}

​

Typescript configuration files

To set the values of the configuration file you can create a TypeScript file with the name <config-name>.config.ts inside your configuration directory and this file will be compiled to JSON after build. You can create multiple files, this is useful for separating environments or different parts of the application.

Continuing our example, here are the values for the model defined above:

import { AppParams } from "./types/all.js";

const config: AppParams = {
  "promo-campaign": {
    fetchLimit: 3,
    rankScore: 2.0,
  },
  creators: {
    fetchLimit: 10,
    rankScore: 1.5,
  },
};

export default config;

​

Generated JSON files

After changing the config.ts file you can run npx @typeconf/typeconf build configs to produce JSON file which you can read in your app, either with Typeconf SDK with type validation or just as a plain JSON.

Here’s the JSON from our example:

{
  "promo-campaign": {
    "fetchLimit": 3,
    "rankScore": 2
  },
  "creators": {
    "fetchLimit": 10,
    "rankScore": 1.5
  }
}

​

Project structure

​

In project

The most straighforward way to use Typeconf is to create a separate directory in your project and put configs there:

your-project/
├── configs/
│   ├── main.tsp
│   └── my-config.config.ts
├── src/
└── next.config.js

​

Standalone

If you want to share configuration between multiple projects or inherit types you can create a separate package with this helper CLI:

npx create-typeconf-package

This will generate all the necessary boilerplate and you will be able to update configs with npm run build.

​

CLI

If you’re not using a separate package you need to use Typeconf CLI to update the configs:

npx @typeconf/typeconf build configs

​

Using the config in your code

To use your configuration in your code, you can install the configuration package you just created as a dependency. Paired with the package you need to install Typeconf SDK:

# Node.JS
$ npm install @typeconf/sdk

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

Once everything is installed, you can read the configuration from any JSON file like this:

import { ProductConfig } from "you-config-package";
import { readConfig } from "@typeconf/sdk";
// or in React: import { readConfig } from "@typeconf/react-sdk/server";

// pass path to config values file without extension
let conf: ProductConfig = readConfig("path/to/config-dir/my-config");

​

FAQ

How to update changes locally if I use a separate package for configs?

Use npx link@latest <path/to/package> to add a symlink to local version of the package.

Where can I see more examples

Check out the examples in the repository. Or check out playground, you can try out the examples without installing it locally.