Upgrading to v1

What changes in 1.0

Version 1.0 adds configuration inspection, safe repair previews, operation locks spanning the native command, and the Bun Windows path-alias fix. It preserves the documented 0.3 configuration fields, file formats, nearest-config lookup, section overrides, command forwarding, and local automatic conversion.

Read the Changelog for the release details and the JavaScript & types page for the stable public interface.

Upgrade from 0.3

First inspect the current layout using the existing installation:

fnspm --version
fnspm doctor

Install v1 and inspect the same project:

npm install -g fnspm@1.1.0
fnspm config --show
fnspm doctor

You do not need to regenerate a valid 0.3 config. Keep your recorded state beside its original project and storage. Restore before moving the project or editing its storage config manually. In 1.1, --relocate can change managed storage in place after validation; see Relocating managed storage.

Inspect each independently configured workspace section from its own directory. A section config still replaces the parent config and receives defaults for omitted fields.

Upgrade a legacy 0.2 link

Older projects may already have node_modules linked to the configured project-local nosync directory without .fnspm-state.json.

FNSPM can adopt this layout when the link matches the configured local name, the target is a regular directory, and the layout passes validation:

npm install -g fnspm@1.1.0
fnspm migrate --dry-run
fnspm migrate
fnspm doctor

Adoption records ownership without moving or deleting dependency files. After successful adoption, restore can return that directory to the native layout. Matching legacy links are also tracked before eligible clean installs when automatic conversion is enabled.

Broken links, foreign targets, and untracked external storage are not adopted automatically. Do not fabricate state to bypass the checks.

Behavior to review when coming from 0.2

Changes introduced in 0.3 also apply to v1:

• Node.js 22 or newer is required.
• Unknown config settings and unknown initialization options are rejected.
• Ambiguous manager lockfiles require an explicit selection.
• --no-sync-folder disables automatic migration.
• Existing destinations are never deleted to make room for migration.
• Restoration requires recorded ownership.
• Moving dependencies uses validation, operation locks, rollback attempts, and ownership state.

The earlier README's non-commercial restriction was inconsistent with the GPL license file and has been removed. The project uses GPL-3.0-only; consult the repository license for its terms.

Clean installs and disabled conversion

A tracked project can run clean installs through FNSPM. Before a dependency-changing command such as npm ci, FNSPM restores tracked local storage so the manager can replace node_modules normally.

This restoration also occurs when conversion is now disabled. After success, conversion happens only for locations whose configuration enables it.

fnspm --pm npm ci
fnspm doctor

For a workspace section, already tracked shared root storage is refreshed with the root's settings. Untracked ancestors and siblings are not newly managed.

The v1 compatibility boundary

New storage features in 1.1

Existing tracked installations can join the inventory with fnspm --storage register; no dependency move is required. Automatic external storage is opt-in through initialize --external or storagePath: 'auto'. Local conversion remains the default.

Relocation keeps migration state at schema version 1 and adds a local destination preference and a temporary recovery journal. Complete pending recovery before using an older CLI. Before downgrading to 1.0/0.3, restore dependencies, clear any relocation preference with --relocate --configured, and replace 'auto' with an older supported configuration. Older releases do not support the new flags or 'auto' setting.

Supported interface

The documented CLI, config settings and resolution, top-level exported types, and main function form the supported public interface. Internal dist/src modules and migration metadata are implementation details.

Breaking changes to that public interface after 1.0 require a new major version. No claim is made that cloud-client behavior or every historical native-manager layout is controlled by FNSPM.