Configuration

Supported files

Keep one configuration file per configured directory:

fnspm initialize writes .mjs when the current manifest declares "type": "module"; otherwise it writes .cjs. A config file exports an object, and may specify only the settings you want to change.

Configuration executes as JavaScript. Load it only from projects you trust.

A complete CommonJS configuration

/** @type {import('fnspm').UserConfig} */
const config = {
    packageManager: {
        default: 'npm',
        detection: 'auto',
    },
    symlink: {
        enabled: true,
        addToGitIgnore: true,
        nosyncName: 'node_modules.nosync',
    },
    debug: {
        verbose: false,
    },
};

module.exports = config;

These are the built-in defaults. Omitted fields receive these values.

For ES modules, keep the object and replace the final line with:

export default config;

Every setting

Booleans must be actual JavaScript true or false, not strings. Unknown sections and unknown settings are rejected. Names containing path separators, reserved metadata names, or invalid Windows filename characters are rejected.

storagePath must be absolute. Its parent must already exist on the same filesystem, and the destination must be dedicated to this project. See Dependency storage.

Selecting a manager deliberately

To always use Bun unless the current command supplies --pm:

module.exports = {
    packageManager: { detection: 'bun' },
};

To always use the configured fallback:

module.exports = {
    packageManager: { default: 'pnpm', detection: 'default' },
};

Setting only default: 'pnpm' does not override a manager declared in the manifest when detection remains 'auto'.

How configuration is resolved

FNSPM searches upward for the nearest configuration, stopping at a Git boundary. A directory without its own config can inherit a parent's config. A nested Git repository creates a new boundary.

A section config overrides the parent config as a whole. FNSPM merges the selected file with built-in defaults, not with the parent's settings.

Suppose the root config sets Bun and disables conversion. If packages/web/fnspm.config.cjs contains only:

module.exports = {
    symlink: { nosyncName: 'web.nosync' },
};

Then that section uses automatic detection, npm as the fallback, and enabled conversion. Those values come from the built-in defaults. Repeat a parent's settings in the section if you want to keep them.

A local migration state file or generated section lockfile does not discard an otherwise inherited parent config. Project detection and config lookup are separate operations.

Inspect effective values and their origins

fnspm config --show
fnspm config --show --json
fnspm config --show --pm pnpm

The JSON report contains cwd, projectRoot, dependencyRoot, configurationFile, config, origins, packageManager, and dependencyStorage.

origins maps setting names such as symlink.enabled to the config file or built-in default. The packageManager object contains its name, selection reason, and detection root.

A CLI --pm override changes the manager chosen for the report; it does not rewrite your configuration.

Disabling future conversion

Edit the chosen config:

module.exports = {
    symlink: { enabled: false },
};

If dependencies are already converted, run fnspm restore to return them immediately. A later dependency-changing command through FNSPM also restores tracked local storage before execution, even when conversion is disabled. Native commands such as run do not necessarily trigger that restoration.

Initialization options

initialize and init-config accept the same options. Supplying any options selects noninteractive initialization; use no options for the terminal wizard.

Legacy boolean forms, such as --symlink true and --verbose false, remain supported. Existing configs are never overwritten by initialization; edit the file instead.