cpconfig

cpconfig is a tiny toolkit that keeps project-specific configuration files in sync with disk. Give it the list of files you care about, and it will write them, ensure parent directories exist, and maintain a clearly marked block inside .gitignore.

The goal is to provide the ergonomic bootstrap experience of tools like coconfig without any custom module loading or complicated configuration layering—just code.

Features

• Deterministic sync – Declare files and their contents, cpconfig handles creation and updates.
• Managed .gitignore block – Automatically keeps tracked configs out of git with a dedicated annotated section.
• Safe by default – No implicit imports or magic; works with plain TypeScript/JavaScript data.
• Dry runs – Compute what would change without touching the file system.

Installation

yarn add @sesamecare-oss/cpconfig
# or
npm install @sesamecare-oss/cpconfig

Programmatic usage

import { syncConfigs } from '@sesamecare-oss/cpconfig';

await syncConfigs(
  {
    'config/.env.local': {
      contents: 'API_TOKEN=abc123',
    },
    '.secrets.json': {
      contents: () => JSON.stringify({ key: 'value' }, null, 2),
    },
  },
  {
    rootDir: process.cwd(), // optional, defaults to process.cwd()
  },
);

The call above writes the files if necessary and maintains this .gitignore block:

# Managed by cpconfig
config/.env.local
.secrets.json

Run the function as many times as you like—it is idempotent and only touches files when their content changes.

Package-driven configuration

Most projects keep their file definitions in a dedicated module and call the bundled CLI as part of postinstall:

{
  "name": "my-project",
  "scripts": {
    "postinstall": "cpconfig"
  },
  "config": {
    "cpconfig": "./cpconfig.config.mjs"
  }
}

The CLI walks up from the current working directory, finds the nearest package.json, and reads the config.cpconfig entry. The value must be a string pointing at a module—top-level cpconfig keys or inline objects are rejected. cpconfig resolves the module using standard Node.js rules and expects it to export one of:

• a default or named config object with { files, options };
• a plain object map of files;
• a factory function (sync or async) returning either of the above.

Factory functions receive two arguments: the entire package.json config object (so you can read sibling settings) and the raw CLI argument array (e.g. ['--json']). Use them to branch on runtime options or shared configurations.

For example, cpconfig.config.mjs might look like:

export default {
  files: {
    'config/.env.local': { contents: 'API_TOKEN=abc123' },
    '.secrets.json': { contents: '{\n  "key": "value"\n}' },
  },
};

• Run npx cpconfig manually whenever you need to refresh files.
• Add cpconfig to postinstall to keep developer machines in sync automatically.

Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | rootDir | string | process.cwd() | Base directory used to resolve all config paths. | | dryRun | boolean | false | When true, compute the diff without writing to disk. | | encoding | BufferEncoding | 'utf8' | Encoding used when reading and writing files. | | gitignorePath | string | <rootDir>/.gitignore | Custom location for the managed gitignore file. |

Each config file can optionally set gitignore: false to opt out of the managed block, or provide a mode (integer) that is applied when the file is first created. Add a sentinel string to embed your own marker inside the file (for example // @cpconfig or <!-- cpconfig -->). cpconfig only rewrites files that include their sentinel, so you never clobber hand-crafted files. Make sure the string appears in the requested contents. When an existing file is missing its sentinel, cpconfig leaves it untouched and prints a warning explaining why.

Result object

syncConfigs resolves with a structured result describing what happened:

const result = await syncConfigs(files);

result.files; // [{ path: 'config/.env.local', managed: true, action: 'created', gitignored: true }, ...]
result.gitignore; // { updated: true, added: ['config/.env.local'], removed: [] }

Use this information to log progress, emit metrics, or drive prompts.

CLI options

cpconfig --help

Options:
  --dry-run             Compute changes without writing files
  --json                Print the sync result as JSON
  --root <path>         Override the root directory used for file writes
  --gitignore <path>    Override the gitignore file path
  --config <path>       Load configuration from an explicit JSON file
  --help, -h            Show this message

Dry runs

Combine dryRun: true with the result payload to surface pending configuration changes without touching disk:

const preview = await syncConfigs(files, { dryRun: true });

if (preview.gitignore.updated || preview.files.some((file) => file.action !== 'unchanged')) {
  console.log('Configuration out of date. Run cpconfig to apply changes.');
}

License

UNLICENSED – tailor to your organisation’s distribution policy before publishing.