@stripezilla/configzilla

Configzilla is a flexible, type-safe configuration management framework designed to bring consistency and safety to both React frontends and Node backends. It allows teams to define a central configuration schema (config-definition) and use it as the single source of truth for all environment-specific settings.

Table of contents

• Overview
• Getting Started
• Next step ideas
• Configuration Definition Types
• Configuration Definition Utils

Overview

• Unified Configuration Schema: Define and update your configuration structure which is of type ConfigDefinition.

• Strong Type Safety: Enforced across both React and Node environments.

• Flexible Usage: Use static config files in development or dynamically load configs in production.

• CMS-Ready: If needed, build your own CMS or UI on top of this framework using provided types and utilities.

• Modular Design: Works in both frontend and backend independently or together.

Getting Started

• install the package

  npm i –save-dev @stripezilla/configzilla

• Create configzilla folder in your react project on the same level as src

• Create configzilla/configDefinition.js. Please check ConfigDefinition to understand how your ConfigDefinition should be structured.

  /*_ @type {import('@stripezilla/configzilla/client').ConfigDefinition} _/ const configDefinition = []; module.exports = configDefinition;

• Create configzilla/index.js:

  const path = require('path'); > const configzilla = require('@stripezilla/configzilla/server'); const configDefinition = require('./configDefinition'); > const getProjectConfig = async () => { const configFilePath = path.join(__dirname, '../src/projectConfig.js'); if (!fs.existsSync(configFilePath)) {

  fs.writeFileSync(configFilePath, 'export <br/>default {};\n', 'utf-8');<br/>

  } configzilla.validateConfigDefinition(configDefinition, configFilePath); }; getProjectConfig();

• Add a new script in package.json

  "configzilla:dev": "nodemon --watch configzilla --exec 'node configzilla/index.js'"

• Run this script in a separate terminal or with the start command using concurrently (best option. Code reference)

• Use src/projectConfig.js (configuration file created after running the script) for project configurations.

Tip: Instead of importing src/projectConfig.js wherever required, you can also create a store and access through it. > Example commit > Example

Next step ideas

• save projectConfig.js content in the db and fetch latest configuration from the db in the deployed projects.
• Use configzilla UI portal or create your own UI to change the configuration through UI.

Configuration Definition Types

ConfigDefinition

ConfigDefinition is an array of field, group and fieldGroup

export type ConfigDefinition = ConfigItem[];

ConfigItem

Each item in the ConfigDefinition

export type ConfigItem = ConfigGroupItem | ConfigFieldGroupItem | ConfigLeafItem;

Field

Configuration information and restriction like its type or options

export interface ConfigLeafItem { id: string; name?: string; type: 'field'; value: ConfigLeaf; description?: string; }

Group

Group of configurations that belong together. You can also create nested groups.

export interface ConfigGroupItem { id: string; name?: string; type: 'group'; value: ConfigItem[]; description?: string; }

FieldGroup

Special type of group. It creates configuration same as group. This type is created for CMS UI, where you may want to control multiple group of field in a single form.

export interface ConfigFieldGroupValueGroupItem extends Omit<ConfigGroupItem, 'value'> { value: ConfigLeafItem[]; } > export interface ConfigFieldGroupItem { id: string; name?: string; type: 'fieldGroup'; value: (ConfigFieldGroupValueGroupItem | ConfigLeafItem)[]; description?: string; }

ConfigLeaf

export interface ConfigLeafTextType {
  type: 'string';
  fieldType?: 'text';
  defaultValue?: string;
  enum?: string[];
}

export interface ConfigLeafTextAreaType {
  type: 'string';
  fieldType?: 'text-area';
  defaultValue?: string;
  enum?: string[];
}

export interface ConfigLeafNumberType {
  type: 'number';
  fieldType?: 'numeric';
  defaultValue?: number;
  enum?: number[];
}

export interface ConfigLeafCheckboxType {
  type: 'boolean';
  fieldType?: 'checkbox';
  defaultValue?: boolean;
}

export interface ConfigLeafToggleType {
  type: 'boolean';
  fieldType?: 'toggle';
  defaultValue?: boolean;
}

export interface ConfigLeafArrayTextType {
  type: 'array';
  fieldType?: 'text';
  defaultValue?: string[];
  itemsType: 'string';
}

export interface ConfigLeafArrayTextAreaType {
  type: 'array';
  fieldType?: 'text-area';
  defaultValue?: string[];
  itemsType: 'string';
}

export interface ConfigLeafArrayNumericType {
  type: 'array';
  fieldType?: 'numeric';
  defaultValue?: number[];
  itemsType: 'number';
}

export type ConfigLeafArrayType =
  | ConfigLeafArrayTextType
  | ConfigLeafArrayTextAreaType
  | ConfigLeafArrayNumericType;

export type ConfigLeaf =
  | ConfigLeafTextType
  | ConfigLeafTextAreaType
  | ConfigLeafNumberType
  | ConfigLeafCheckboxType
  | ConfigLeafToggleType
  | ConfigLeafArrayType;

Configuration Definition Utils

These functions return true or false.

Check ConfigItem type > isConfigLeafItem(value: ConfigItem) isConfigGroupItem(value: ConfigItem) isConfigFieldGroupItem(value: ConfigItem)

Check ConfigLeaf type > isConfigLeafItemText(value: ConfigLeaf) isConfigLeafItemTextArea(value: ConfigLeaf) isConfigLeafItemNumber(value: ConfigLeaf) isConfigLeafItemCheckbox(value: ConfigLeaf) isConfigLeafItemToggle(value: ConfigLeaf) isConfigLeafArrayNumberType(value: ConfigLeaf) isConfigLeafArrayTextType(value: ConfigLeaf) isConfigLeafArrayTextAreaType(value: ConfigLeaf)