CorentinTh/figue

Figue - Application configuration management

The modern way to handle and validate your application configuration with any standard-schema-compliant validation library.

Introduction

Figue is a modern configuration management library for Node.js. It is designed to be easy to use, flexible, it can used in any environment, and can be used with any standard-schema-compliant validation library, like zod or valibot.

Think of it as a modern version of convict but simpler, cross env and using battle tested validation libraries.

Features

• Environment variables support
• Validation with any standard-schema-compliant validation library
• Flat object support
• Multiple sources of configuration
• Type-safe configuration
• Composable configuration
• No runtime dependencies

Usage

Install package:

# pnpm
pnpm install figue

# npm
npm install figue

# yarn
yarn install figue

Import:

import { defineConfig } from 'figue';

API

Basic example

Use the defineConfig function to define your configuration, here with valibot:

import { defineConfig } from 'figue';
import * as v from 'valibot';

const { config } = defineConfig(
  {
    env: {
      doc: 'Application current environment',
      default: 'development',
      schema: v.picklist(['development', 'production', 'test']),
      env: 'NODE_ENV',
    },
    port: {
      doc: 'Application port to listen',
      schema: v.pipe(v.union([v.number(), v.string()]), v.transform(Number)),
      default: 3000,
      env: 'PORT',
    },
    db: {
      host: {
        doc: 'Database server url',
        schema: v.pipe(v.string(), v.url()),
        default: 'http://localhost:5432',
        env: 'APP_DB_HOST',
      },
      username: {
        doc: 'Database server username',
        schema: v.string(),
        default: 'pg',
        env: 'APP_DB_USERNAME',
      },
      password: {
        doc: 'Database server password',
        schema: v.string(),
        default: '',
        env: 'APP_DB_PASSWORD',
      },
    },
  },
  {
    envSource: process.env,
  },
);

console.log(config);
// {
//   env: "development",
//   port: 3000,
//   db: {
//     url: "https://localhost",
//     username: "pg",
//     password: "",
//   },
// }

You can see more examples in the demo folder.

• Figue with zod: demo/figue-zod.ts
• Figue with valibot: demo/figue-valibot.ts

Load environnement

Use the envSource key of the second argument of defineConfig to specify the source of the environment variables:

const { config } = defineConfig(
  {
    /* ... */
  },
  {
    envSource: process.env,
  },
);

In some case you don't have access to a process.env variable, like with vite, just simply load what stores your env variables :

const { config } = defineConfig(
  {
    /* ... */
  },
  {
    envSource: import.meta.env,
  },
);

You can even specify you custom environment storage as long as it's a simple flat object map, for example:

const { config } = defineConfig(
  {
    env: {
      doc: 'Application current environment',
      default: 'development',
      schema: z.enum(['development', 'production', 'test']),
      env: 'NODE_ENV',
    },

    /* ... */
  },
  {
    envSource: {
      NODE_ENV: 'development',
      PORT: '3000',
      APP_DB_HOST: 'localhost',
      APP_DB_USERNAME: 'pg',
      APP_DB_PASSWORD: '',
    },
  },
);

If, for some reason, you have multiple sources of environment variables, you can use the envSources key of the second argument of defineConfig to specify an array of sources:

const { config } = defineConfig(
  {
    /* ... */
  },
  {
    envSource: [import.meta.env, myEnvs],
  },
);

Environment variable fallback

You can specify multiple environment variable names for a single configuration field by providing an array of strings. Figue will use the first environment variable that is found in your environment sources.

This feature is particularly useful when:

• Supporting multiple deployment environments with different environment variable naming conventions
• Migrating from legacy environment variable names while maintaining backward compatibility
• Providing fallback options for missing environment variables

const { config } = defineConfig(
  {
    port: {
      doc: 'Application port to listen',
      schema: z.coerce.number(),
      default: 3000,
      // Will use PORT if available, otherwise APP_PORT, otherwise SERVER_PORT
      env: ['PORT', 'APP_PORT', 'SERVER_PORT'],
    },
    database: {
      host: {
        doc: 'Database host',
        schema: z.string(),
        default: 'localhost',
        // Useful for supporting legacy environment variable names
        env: ['DATABASE_HOST', 'DB_HOST', 'LEGACY_DB_URL'],
      },
    },
    workerId: {
      doc: 'Worker identifier',
      schema: z.string().optional(),
      // Or using some plateform specific environment variable
      env: ['WORKER_ID', 'HEROKU_DYNO_ID', 'RENDER_INSTANCE_ID'],
    },
  },
  {
    envSource: process.env,
  },
);

Some caveats:

• If none of the specified environment variables are found, Figue will fall back to the default as expected when no env key is present.
• If a variable is found but its value is nullish or falsy (like an empty string, or undefined), Figue will still consider it as set and use that value. If you want to ignore such values, you should handle that in your schema validation.
• Ensure that the order of environment variables in the array reflects their priority, as Figue will use the first one it finds.

Get defaults

You can use the getDefaults key of the second argument of defineConfig to specify a function that will be called to get some defaults:

const { config } = defineConfig(
  {
    env: {
      doc: 'Application current environment',
      default: 'development',
      schema: z.enum(['development', 'production', 'test']),
      env: 'NODE_ENV',
    },
    port: {
      doc: 'Application port to listen',
      schema: z.coerce.number().int().positive(),
      default: 3000,
      env: 'PORT',
    },
  },
  {
    envSource: {
      PORT: 3001,
    },
    // The config argument is build from the config definition defaults and the envSources
    // Typically you will use it to override some defaults based the config
    getDefaults: ({ config }) => ({
      port: config.env === 'test' ? 4444 : config.port,
    }),
  },
);

You can also use the defaults property of the second argument of defineConfig to specify some static defaults (for example taken from a json file):

const { config } = defineConfig(
  {
    /* ... */
  },
  {
    // Either an array of config partial...
    defaults: [
      {
        port: 4444,
      },
    ],

    // ... or a single config partial
    defaults: {
      port: 4444,
    },
  },
);

Cross-field validation

Sometimes a single schema isn't enough — a field's validity may depend on another field's value. For these cases, add a validate function to any field. It runs after every per-field schema check has passed, and receives the fully-validated config:

import { defineConfig, validator } from 'figue';
import * as v from 'valibot';

type Config = {
  adapters: { id: string; url: string }[];
  defaultAdapterId: string;
};

const { config } = defineConfig({
  adapters: {
    doc: 'Available resource adapters',
    schema: v.array(v.object({ id: v.string(), url: v.string() })),
    default: [],
    env: 'ADAPTERS',
  },
  defaultAdapterId: {
    doc: 'Default adapter id (must reference one of `adapters[].id`)',
    schema: v.string(),
    default: '',
    env: 'DEFAULT_ADAPTER_ID',
    validate: validator<Config>(({ value, config }) => {
      if (!config.adapters.some(a => a.id === value)) {
        return `must match one of adapters[].id (got "${value}")`;
      }
    }),
  },
});

Co-locating the rule with the field it belongs to keeps things readable, even when your config definition is split across modules.

Return contract — the function can either throw or return:

All issues from cross-field rules are aggregated into a single ConfigValidationError, just like schema errors.

Typing the config argument — by default config is loosely typed (any) so you don't have to declare anything. When you want full IntelliSense on the cross-referenced fields, wrap your function with the validator<Config>(...) helper as shown above. It's a no-op at runtime, purely a type hint.

Note — validate only runs once every field's schema has validated successfully, so you can trust that config is fully typed and coerced.

What's wrong with convict?

Convict is meant to be used in node based environnement, it needs to have access to global variables that may may not be present in some environnement (like process, global), and it also imports fs.

Figue?

Figue is the french for fig -> con-fig.

Development

• Clone this repository
• Install dependencies using pnpm install
• Run interactive tests using pnpm dev

Credits

This project is crafted with ❤️ by Corentin Thomasset. If you find this project helpful, please consider supporting my work.

Fig icons created by Freepik - Flaticon

License

This project is under the MIT license.