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");

Typeconf Storage

If you want dynamic configuration you can use our open-source and free storage, just register here! Typeconf Storage provides two main features (for now):

• Changing configs without full redeployment;
• Configuration revisions;

This essentially allows you to quickly experiment with the configs. Here's how to use it:

1. Upload your configs:

$ npx @typeconf/typeconf cloud update-config-value path/to/your.config.ts

2. Check the latest revision:

$ npx @typeconf/typeconf cloud get-config-value path/to/your.config.ts

3. Read in your code:

Just add these env variables to .env:

TYPECONF_CLOUD_EMAIL=<your-email>
TYPECONF_CLOUD_PASSWORD=<your-password>
TYPECONF_CLOUD_PROJECT=<your-project-name>

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.

Is the cloud storage free?

Yes! Typeconf Storage is the part of the platform and we want to provide it for free to complete the experience.