Configuration

murasaki.config.ts (or .js / .mjs) at your project root describes your app's identity, window, and build settings:

import { defineConfig } from 'murasaki'

export default defineConfig({
  appId: 'app.murasaki.example',
  productName: 'Murasaki App',
  version: '0.1.0',
  icon: 'assets/icon.png',
  window: {
    title: 'Murasaki App',
    width: 1000,
    height: 700,
  },
  capabilities: ['dialog:openFile', 'clipboard:writeText'],
})

defineConfig returns the same object for type inference and validates declarative window labels/routes synchronously. There is nothing to await.

Top-level fields

window

windows

window is the primary window with the reserved label main. Declare secondary windows in windows; each entry accepts the same shape except for the primary-only console option and gets its own route, initial visibility, and command allowlist:

window: {
  route: '/',
  capabilities: ['window:open', 'window:list', 'window:manage'],
},
windows: {
  settings: {
    route: '/settings',
    width: 720,
    height: 560,
    capabilities: [],
  },
},

Labels are 1–64 safe characters and main is reserved. Secondary windows are created hidden and inherit no top-level permissions. A secondary console field is rejected because that option controls the Windows backend console for the whole application. See Windows & permissions for lifecycle and renderer APIs.

capabilities

Native renderer APIs are deny-by-default. Add only the commands your app uses; unknown permissions do not grant anything:

capabilities: [
  'app:quit',
  'dialog:openFile',
  'clipboard:readText',
  'clipboard:writeText',
  'notification:show',
  'shell:openExternal',
  'window:setTitle',
]

The complete typed list is NativeCapability. The primary window uses window.capabilities ?? capabilities ?? []; each secondary uses its own list or []. Grants are evaluated for the calling renderer, and off-origin pages cannot use the native bridge. Window management adds window:getLabel, window:open, window:list, and window:manage. Programmatic application shutdown requires app:quit; enabling the built-in updater grants it to the primary window for the verified restart handshake.

systemPermissions

This config describes host-OS consent, not which renderer commands are trusted. For packaged macOS apps, Murasaki writes camera/microphone purpose text to Info.plist and can request selected permissions at launch:

systemPermissions: {
  macOS: {
    camera: {
      usageDescription: 'Use your camera for video calls.',
      requestOnLaunch: true,
    },
    microphone: {
      usageDescription: 'Use your microphone for voice calls.',
    },
    screenRecording: { requestOnLaunch: false },
    accessibility: { requestOnLaunch: false },
  },
},

Prefer a contextual systemPermission.request() over launch-time prompts when the user can first understand the feature. Runtime calls additionally require systemPermission:status / systemPermission:request in that renderer's capability list. Windows unpackaged desktop consent is usage-driven, so it has no equivalent generic launch prompt. Test macOS TCC behavior from a packaged app, not the terminal/Node identity used by murasaki dev.

main

Murasaki loads src/main.ts when it exists. Use main to choose another entry, change the graceful cleanup deadline, or disable Main discovery:

main: {
  entry: 'src/backend/main.ts',
  shutdownTimeoutMs: 15_000,
}
// main: false

See Node Main for lifecycle hooks and 'use main'.

protocols

Register custom URL schemes and receive matching URLs through Node Main's openRequested() hook:

protocols: [
  { scheme: 'violet', name: 'Violet Link' },
]

Duplicate or invalid schemes fail the build. macOS writes the registration into the packaged .app's Info.plist. Windows NSIS/MSI installers write the OS registration; a portable Windows archive does not. Linux registration is not implemented.

fileAssociations

Register one or more extensions as a document type:

fileAssociations: [
  {
    extensions: ['vnote', 'violet-note'],
    name: 'Violet Note',
    description: 'A note created with Violet',
    role: 'editor',
    mimeType: 'application/x-violet-note',
  },
]

Extensions must be unique across all entries; invalid extensions and MIME types fail the build. Matching files are delivered to Node Main's openRequested() hook. The same artifact limits as protocols apply: packaged macOS .app and installed Windows NSIS/MSI are supported, while portable Windows archives, Linux, and murasaki dev do not install associations.

See Deep links and file associations for delivery semantics, testing, and untrusted-input requirements.

bundle

Server/Main code is compiled for production. Static bare npm imports are detected and staged automatically; use these options for dependencies and assets whose runtime behavior cannot be discovered statically:

bundle: {
  external: ['computed-plugin'],
  noExternal: ['small-js-only-package'],
  resources: [
    'prisma/schema.prisma',
    { from: 'prisma/migrations', to: 'database/migrations' },
  ],
}

Do not place secrets in resources; everything in an app bundle is readable by the user. Test native addons on every target architecture.

build

build: {
  before: 'pnpm --filter @acme/database build && pnpm prisma generate',
  envPrefix: ['VITE_', 'NEXT_PUBLIC_'],
}

Only prefixed variables are client-public, but never put secrets under those prefixes: Vite replaces their values into shipped JavaScript. Packaged Node Main inherits the environment of the launcher; Murasaki does not copy .env files into the app. Put end-user runtime settings under context.paths.data or provide them through your deployment environment.

security

Murasaki injects one environment-specific Content Security Policy into both the framework shell and a user-owned index.html. Configure a complete replacement, or explicitly opt out:

security: {
  csp: "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self' https: wss:; object-src 'none'; base-uri 'none'; frame-src 'none'",
},

// Escape hatch when another layer owns the policy:
// security: { csp: false },

If index.html already contains a CSP <meta http-equiv> tag, Murasaki keeps that user-owned policy and moves it to the beginning of <head> so it applies before scripts or resources. Configure the policy in exactly one place: combining an existing tag with a security.csp string is a build error. Configured policies must be non-empty, single-line strings without control characters, double quotes, <, or >. See Security for defaults, migration guidance, and limitations of meta-delivered CSP.

updater

true is a complete, working setup for a normal OSS app — the GitHub repo is inferred from package.json's repository field, the public key from .murasaki/update-key.pub, channel defaults to 'stable', checked once at launch. The object form only needs to override what doesn't fit those defaults:

type UpdaterConfig =
  | boolean
  | {
      repo?: string                    // "owner/repo" — defaults to package.json#repository
      endpoint?: string                // self-hosted manifest URL — mutually exclusive with repo
      channel?: string                 // release channel, default 'stable'
      checkOnStart?: boolean           // check once at launch, default true
      checkInterval?: string | false   // e.g. '6h' — re-check on a timer, default '6h'
      publicKey?: string               // base64 Ed25519 public key — defaults to .murasaki/update-key.pub
    }

There is deliberately no provider field — GitHub vs. self-hosted is inferred from whether repo or endpoint is set, so it can't drift out of sync with the rest of the config. There is also no way to disable signature verification.

checkOnStart and checkInterval are driven by the update engine itself, so they apply whether or not anything in your UI ever calls check(). You can still call useUpdate().check() by hand — an in-flight check is never started twice concurrently.

Consumed by useUpdate() and <UpdateButton /> (both from murasaki) — see the full Auto-update guide for the manifest format, signing, and publishing releases.

installer

macOS DMG styling and Windows NSIS/MSI installer options. Omit entirely to use Murasaki's defaults.

installer.windows

sign

Murasaki signs with your certificate/provider — it ships none of its own. Notarization credentials and PFX passwords are read from environment variables, never from this config — see Distribution → Signing.

macOS fields

sign.windows

murasaki bundle --sign --target win32-x64 signs the app executable before the portable ZIP is made. murasaki installer --sign --target win32-x64 also signs each generated NSIS setup and MSI, then verifies every signature with the Authenticode policy. This step runs on Windows with SignTool.

All selectors also have CI environment overrides; see Windows installers and signing.

Next