nx.js

Usage

Installation

npm install @nx.js/install-title
pnpm add @nx.js/install-title
yarn add @nx.js/install-title
bun add @nx.js/install-title

Supported Formats

FormatDescription
NSPNintendo Submission Package (PFS0)
NSZCompressed NSP (contains NCZ-compressed NCAs)
XCIGameCard Image (HFS0 partitions)
XCZCompressed XCI (contains NCZ-compressed NCAs)

Example

src/main.ts
import { install } from '@nx.js/install-title';
import { NcmStorageId } from '@nx.js/ncm';

// Open a file from the SD card
const file = Switch.file('sdmc:/game.nsp');

// Install to SD card — format is auto-detected from magic bytes
for await (const step of install(file, NcmStorageId.SdCard)) {
    switch (step.type) {
        case 'start':
            console.log(`Starting: ${step.name}`);
            break;
        case 'end':
            console.log(
                `Done: ${step.name} (${(step.timeEnd - step.timeStart).toFixed(0)}ms)`,
            );
            break;
        case 'progress':
            console.log(`${step.name}: ${step.processed}/${step.total}`);
            break;
    }
}

console.log('Installation complete!');

All four formats work the same way — just point at the file:

src/main.ts
// NSP, NSZ, XCI, and XCZ are all auto-detected
const nsz = Switch.file('sdmc:/game.nsz');
const xci = Switch.file('sdmc:/game.xci');
const xcz = Switch.file('sdmc:/game.xcz');

for await (const step of install(nsz, NcmStorageId.SdCard)) {
    // ...
}

You can also specify the format explicitly:

src/main.ts
for await (const step of install(blob, NcmStorageId.SdCard, { format: 'xci' })) {
    // ...
}

Validation Warnings

The installer performs validation checks and emits warnings via the onWarning callback. If no callback is provided, warnings are treated as fatal errors and abort the installation.

src/main.ts
for await (const step of install(file, NcmStorageId.SdCard, {
    onWarning: async (warning) => {
        console.warn(`Warning: ${warning.message}`);
        // Return true to continue, false to abort
        return true;
    },
})) {
    // ...
}
Warning CodeDescription
already-installedThe exact title ID + version is already installed
nca-already-registeredA specific NCA is already in content storage
missing-ticketA .tik file is missing its corresponding .cert

How It Works

  1. Parse container — NSP/NSZ uses PFS0, XCI/XCZ uses HFS0
  2. Install content meta — Installs .cnmt.nca files, mounts them to read CNMT metadata
  3. Import tickets — Imports .tik and .cert files via the ES service
  4. Install NCAs — Writes NCA files to content storage via NCM placeholders. NCZ files (in NSZ/XCZ) are transparently decompressed and re-encrypted on the fly
  5. Push application records — Registers the title with the NS service

On this page

InstallationSupported FormatsExampleValidation WarningsHow It Works