設定

プロジェクトルートの murasaki.config.ts（または .js / .mjs）は、アプリの識別情報、ウィンドウ、ビルド設定を記述します。

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,
    backendCapabilities: ['api:POST:/api/documents'],
  },
  capabilities: ['dialog:openFile', 'clipboard:writeText'],
})

defineConfig は型推論のために受け取ったオブジェクトをそのまま返し、宣言されたウィンドウのラベルとルートを同期的に検証します。await は不要です。

トップレベルのフィールド

about

about を省略すると、OS 標準のコンパクトな About ダイアログがそのまま使われます。macOS では、これを宣言した場合だけカスタマイズ可能なネイティブ AppKit パネルに切り替わります。Windows / Linux では、現時点では標準のメタデータダイアログを使い続けます。

about: {
  name: 'My App',
  width: 520,
  height: 680,
  paragraphs: [
    '作業に集中できるデスクトップワークスペース。',
    'Murasakiで構築されています。',
  ],
  paragraphSpacing: 16,
  details: [
    { label: 'Build', value: '15212' },
    {
      label: 'Commit',
      value: '332b2aefc',
      href: 'https://github.com/example/app/commit/332b2aefc',
    },
  ],
  buttons: [
    { label: 'Docs', href: 'https://docs.example.com' },
    { label: 'GitHub', href: 'https://github.com/example/app' },
  ],
},

外部リンク先は、認証情報を含まない絶対 http、https、mailto の URL に限定されます。アプリアイコンは macOS がインストール済みのバンドルから解決するため、About パネルは Finder や Dock と同じマスク済みのアイコン表示になります。

window

windows

window は、予約ラベル main を持つプライマリウィンドウです。セカンダリウィンドウは windows に宣言します。各エントリはプライマリ専用の console を除いて同じ形式を受け付け、ルート、初期表示、コマンドの許可リストをそれぞれ個別に設定できます。

window: {
  route: '/',
  capabilities: ['window:open', 'window:list', 'window:manage'],
  backendCapabilities: ['api:POST:/api/settings'],
},
windows: {
  settings: {
    route: '/settings',
    width: 720,
    height: 560,
    createOnLaunch: false,
    capabilities: [],
    backendCapabilities: ['api:GET:/api/settings'],
  },
},

ラベルは安全な 1〜64 文字で、main は予約済みです。セカンダリウィンドウはデフォルトで createOnLaunch: true を使い、非表示の状態で作成されます。false にすると、Node Main が windows.create(label) を呼び出すまで宣言を休止状態にできます。プライマリウィンドウは常に起動時に作成されます。セカンダリウィンドウはトップレベルの権限を一切継承しません。console フィールドはアプリケーション全体の Windows バックエンドコンソールを制御するオプションのため、セカンダリで指定すると拒否されます。ライフサイクルとレンダラー API については、ウィンドウと権限を参照してください。

webview

これらの設定は、開発時およびパッケージ化された macOS / Windows アプリのすべてのネイティブ WebView に適用されます。ウィンドウ単位のオーバーライドはサポートされていません。

webview: {
  userAgent: 'AcmeDesktop/1.4 Murasaki',
  incognito: true,
  proxy: {
    protocol: 'socks5',
    host: '127.0.0.1',
    port: 1080,
  },
},

プロキシの URL や認証用フィールドは意図的にサポートしていません。スキーム、パス、user@host、ユーザー名、パスワード、未知のプロキシフィールドは設定の検証で拒否されます。認証が必要なプロキシを使う場合は、Murasaki の外側で設定するか、認証なしのローカル転送プロキシを使用してください。設定は Wry のネイティブ WebKit / WebView2 ビルダーへ渡され、Rust ホスト側でも再検証されます。

プラットフォームごとの制約は次のとおりです。

• macOS のプロキシ機能は Wry の mac-proxy 機能を使用し、macOS 14 以降が必要です。古い macOS でプロキシを設定すると、WebView の起動が明示的に失敗します。プライベートセッションには WebKit の非永続データストアを使用します。
• Windows のプロキシ機能は WebView2 のブラウザ引数を使用します。カスタム User-Agent には WebView2 86.0.616.0 以降、プライベートモードには 101.0.1210.39 以降が必要で、古いランタイムでは WebView2 がこれらの設定を無視します。
• Linux では、開発時と AppDir / AppImage / .deb の配布ビルドのどちらでも、これらの設定を Wry / WebKitGTK へ渡します。実際の挙動は、対象ディストリビューションに含まれる WebKitGTK のバージョンでも確認してください。

incognito が制御するのは、ローカルの WebView の永続化だけです。ネットワークの匿名化、プロキシ／サーバーからのクライアントの秘匿、アプリレベルの Node データのプライベート化は行いません。Murasaki はネイティブウィンドウごとにブラウザプロファイルを分離するため、cookie、ストレージ、ワーカーがウィンドウ別のバックエンド権限をまたぐことはありません。プライマリウィンドウは従来どおりのアプリプロファイルを維持し、セカンダリウィンドウのプロファイルは Windows / Linux と macOS 14 以降では永続化されます。macOS 11〜13 では分離された非永続ストアを使用します。そのため、ウィンドウ間でのセッション共有は意図的にサポートされていません。状態を共有したい場合は、Main / API を使って明示的に同期してください。セキュリティも参照してください。

capabilities

レンダラー向けのネイティブ API は、デフォルトですべて拒否されます。アプリが実際に使うコマンドだけを追加してください。未知の権限は何も許可しません。

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

完全な型付き一覧は NativeCapability です。プライマリウィンドウは window.capabilities ?? capabilities ?? [] を使い、各セカンダリウィンドウは自身のリストまたは [] を使います。許可は呼び出し元のレンダラーごとに評価され、別オリジンのページはネイティブブリッジを利用できません。ウィンドウ管理には window:getLabel、window:open、window:list、window:manage を使います。アプリケーションのプログラムによるシャットダウンには app:quit が必要です。組み込みのアップデーターを有効にすると、検証済みの再起動ハンドシェイク用としてプライマリウィンドウへ自動的に付与されます。ログイン時の自動起動は、読み取りと書き込みの権限が分離されています。status() だけを呼ぶウィンドウには autostart:read を、enable() や disable() を呼ぶ設定画面には autostart:write を付与してください。

ターゲットを持つコマンドを制限したい場合は、構造化された NativeCapabilityGrant を使います。deny は allow より優先され、ワイルドカードとして使えるのは末尾の /** だけです。

capabilities: [
  { permission: 'shell:openExternal', allow: { urls: ['https://example.com/help/**'] } },
  { permission: 'shell:showItemInFolder', allow: { paths: ['/Users/me/Documents/**'] } },
  { permission: 'window:manage', allow: { windows: ['settings', 'preview'] } },
  { permission: 'systemPermission:request', allow: { permissions: ['camera'] } },
  { permission: 'secureStorage:get', allow: { keys: ['account:*'] } },
  { permission: 'webview:writeCookies', allow: { urls: ['https://app.example.com/**'] } },
]

互換性のため、文字列形式の許可はターゲットに制限がありません。URL、パス、キー、ウィンドウ、OS 権限のスコープは、設定の読み込み時に検証され、Rust ホスト側でも再度強制されます。

backendCapabilities

レンダラーからローカルの Node リソースへのアクセスも、別途デフォルトですべて拒否されます。プライマリウィンドウは window.backendCapabilities ?? backendCapabilities ?? [] を使い、セカンダリウィンドウは何も継承せず、自身のリストまたは [] を使います。

backendCapabilities: [
  'main:src/backend/account.ts#loadAccount',
  'action:src/actions/save.ts#saveDocument',
  'api:POST:/api/documents/*',
  'updater:check',
  'events:sync.*',
  'diagnostics:renderer-error',
]

末尾に 1 つだけ * が付いた許可はプレフィックスワイルドカードとして扱われ、それ以外は完全一致になります。API リソースには大文字のメソッドを含めます。main:*、action:*、api:*、updater:*、events:* のような広い許可も有効ですが、本番環境では厳密なリソース指定の方が安全です。ネイティブのシャットダウン、アクティベーション、ウィンドウ制御のエンドポイントはレンダラーへ許可できません。セキュリティも参照してください。

systemPermissions

この設定が表すのは、信頼するレンダラーコマンドではなく、ホスト OS の同意です。パッケージ化された macOS アプリでは、用途説明を Info.plist に書き込み、ほとんどの権限を起動時に要求できます。

systemPermissions: {
  macOS: {
    camera: {
      usageDescription: 'ビデオ通話でカメラを使用します。',
      requestOnLaunch: true,
    },
    microphone: {
      usageDescription: '音声通話でマイクを使用します。',
    },
    screenRecording: { requestOnLaunch: false },
    accessibility: { requestOnLaunch: false },
    inputMonitoring: { requestOnLaunch: false },
    location: {
      usageDescription: '近くのスポットを表示します。',
      mode: 'whenInUse',
    },
    fullDiskAccess: { requestOnLaunch: false },
    photos: { usageDescription: '投稿に写真を添付します。' },
    contacts: { usageDescription: '友達を見つけます。' },
    calendar: { usageDescription: '予定を確認します。' },
    reminders: { usageDescription: 'リマインダーを確認します。' },
    speechRecognition: { usageDescription: 'ボイスメモを文字起こしします。' },
    bluetooth: { usageDescription: '近くのデバイスを見つけます。' },
    appleEvents: { usageDescription: '他のappを代わりに自動操作します。' },
    localNetwork: { usageDescription: 'このネットワーク上のデバイスを探します。' },
  },
},

ユーザーが先に機能の必要性を理解できる場合は、起動時プロンプトよりも文脈に沿った systemPermission.request() を優先してください。実行時の呼び出しには、そのレンダラーのケイパビリティリストに systemPermission:status / systemPermission:request も必要です。Windows のアンパッケージ版デスクトップでの同意は利用時に発生するため、汎用的な起動時プロンプトはありません。上記の 15 種類はすべて macOS 専用です — Windows と Linux には、これらの TCC 管理下プロンプトに相当する OS レベルの機能がありません。macOS の TCC の実際の挙動は、murasaki dev のターミナルや Node のアイデンティティではなく、パッケージ化されたアプリで確認してください。

Entitlements と App Sandbox

Murasaki が現在対応しているのは Hardened Runtime による署名であり、macOS の App Sandbox ではありません。sign.appSandbox をデフォルトの false のままにした場合、Murasaki は camera、microphone、location、photos、contacts、calendar/reminders、Apple Events に必要な Hardened Runtime のリソースアクセス用エンタイトルメントを systemPermissions.macOS から生成します。署名済みビルドには、これらのホストエンタイトルメントと、対応する Info.plist の用途説明の両方が必要です。この非サンドボックス構成では、Bluetooth と音声認識は用途説明だけを使用します。同梱の Node ヘルパーのみが JIT 用の Hardened Runtime 権限を受け取り、ネイティブアドオンには実行可能エンタイトルメントは付与されません。sign.appSandbox: true は、Apple のヘルパー継承規則と現在の組み込み Node / JIT アーキテクチャが両立しないため、fail-closed で拒否されます。カスタムの sign.entitlements / sign.helperEntitlements はそのまま使用され、指定したパスが存在しないか plutil の検証に失敗した場合はビルドが停止します。種類ごとの完全な対応表は、Native APIs → Entitlements と App Sandboxを参照してください。

main

src/main.ts が存在すると、Murasaki が自動的に読み込みます。main を使うと、別のエントリを指定したり、グレースフルシャットダウンの期限を変更したり、Main の自動検出を無効化したりできます。

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

ライフサイクルフックと 'use main' については、Node Mainを参照してください。

protocols

カスタム URL スキームを登録すると、一致する URL を Node Main の openRequested() フックで受け取れます。

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

重複したスキームや不正なスキームがあると、ビルドは失敗します。macOS では .app の Info.plist に、Windows では NSIS / MSI インストーラーに登録情報を書き込みます。Linux では .desktop ファイルへ対応する MimeType を記録し、.deb のインストール時にデスクトップデータベースへ登録します。展開しただけの AppDir / AppImage と、ポータブルな Windows アーカイブは、OS への登録処理を行いません。

fileAssociations

1 つ以上の拡張子をドキュメントタイプとして登録します。

fileAssociations: [
  {
    extensions: ['vnote', 'violet-note'],
    name: 'Violet Note',
    description: 'Violet で作成したノート',
    role: 'editor',
    mimeType: 'application/x-violet-note',
  },
]

拡張子はすべてのエントリ間で一意である必要があり、不正な拡張子や MIME タイプはビルドエラーになります。一致したファイルは Node Main の openRequested() フックに届きます。配布形式ごとの制約は protocols と同じです。パッケージ化された macOS の .app、インストール済みの Windows NSIS / MSI、インストール済みの Linux の .deb は関連付けを登録します。ポータブルな Windows アーカイブ、展開しただけの AppDir / AppImage、murasaki dev は OS への関連付けを登録しません。

配信の仕様、テスト方法、信頼できない入力の扱いについては、Deep Link と File Associationを参照してください。

bundle

サーバー／Main のコードは本番向けにコンパイルされます。静的な bare npm import は自動的に検出・ステージングされます。実行時の挙動を静的に検出できない依存関係やアセットには、次のオプションを使用してください。

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

resources に秘密情報を置かないでください。アプリバンドル内のものはユーザーが読み取れます。ネイティブアドオンは、対象となるすべてのアーキテクチャでテストしてください。

plugins

defineMurasakiPlugin を使うと、信頼されたビルド時拡張機能を宣言できます。プラグインは murasaki.config.ts と同じ Node.js 権限で実行されるため、信頼できるコードだけをインストールしてください。

import { defineConfig, defineMurasakiPlugin } from 'murasaki'
import inspect from 'vite-plugin-inspect'

const assetsPlugin = defineMurasakiPlugin({
  name: 'acme.assets',
  vite: inspect(),
  bundle: {
    external: ['native-addon'],
    resources: [{ from: 'models', to: 'models' }],
  },
  hooks: {
    async before({ command, target, projectRoot, config }) {
      // dev / build / bundle の前にfileを生成・検査する。
    },
    async after(context) {
      // command成功後に宣言順で実行する。
    },
  },
})

export default defineConfig({
  appId: 'app.murasaki.example',
  productName: 'Murasaki App',
  plugins: [assetsPlugin],
})

フックのコンテキストには、プラグインオブジェクトを除いた深く凍結された設定のスナップショット、絶対パスの projectRoot、command（dev / build / bundle）、そして bundle コマンド時の具体的な target が含まれます。プラグインオブジェクトや関数は murasaki-meta.json へシリアライズされません。

この SDK が拡張するのは ビルドパイプラインだけ です。ネイティブの Rust ABI、動的ライブラリローダー、レンダラー／ランタイムのプラグインサンドボックスではありません。ネイティブ機能は、引き続き Murasaki のネイティブホストとケイパビリティモデルに実装してください。

build

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

プレフィックスが付いた変数だけがクライアントに公開されますが、そこに秘密情報を置かないでください。Vite がその値を配布用の JavaScript に埋め込みます。

環境変数と.env

Murasaki CLI は、プロジェクトルートから次のファイルを自動的に読み込みます。後にあるファイルほど優先度が高く、ターミナルや CI からすでに渡されている環境変数は、すべての .env ファイルより優先されます。

.env
.env.local
.env.development          # murasaki dev
.env.development.local
.env.production           # build / bundle / installer
.env.production.local

レンダラーへ渡す値には、Murasaki 固有の MURASAKI_PUBLIC_ という名前空間を付け、import.meta.env から参照します。

MURASAKI_PUBLIC_API_ORIGIN=https://api.example.com
ACCOUNT_API_TOKEN=keep-this-private

const apiOrigin = import.meta.env.MURASAKI_PUBLIC_API_ORIGIN

プレフィックスのない値は、レンダラーのバンドルには一切含まれません。murasaki.config.*、プラグインフック、Node Main、Server Actions、API Routes では、通常の Node の環境変数として参照できます。

const token = process.env.ACCOUNT_API_TOKEN

MURASAKI_PUBLIC_ の値はビルド時に配布用の JavaScript へ埋め込まれるため、このプレフィックスを秘密情報には使用しないでください。パッケージ化された Node Main はランチャーの環境を継承しますが、Murasaki は .env ファイルをアプリへコピーしません。インストール済みアプリの秘密情報やエンドユーザー向けの実行時設定には、デプロイ環境、OS の認証情報ストア、secureStorage、または context.paths.data を使用してください。

security

Murasaki は、フレームワークのシェルとユーザー所有の index.html の両方に、環境ごとの Content Security Policy を 1 つ注入します。完全な置き換えを設定することも、明示的にオプトアウトすることもできます。

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'",
},

// 別layerがpolicyを管理する場合のescape hatch:
// security: { csp: false },

index.html にすでに CSP の <meta http-equiv> タグがある場合、Murasaki はそのユーザー所有のポリシーを維持しつつ、スクリプトやリソースより先に適用されるよう <head> の先頭へ移動します。ポリシーは必ず 1 か所で管理してください。既存のタグと security.csp の文字列を併用すると、ビルドエラーになります。設定する値は、空でない 1 行の文字列に限られ、制御文字、二重引用符、<、> は使用できません。デフォルト値、移行方法、meta 配信 CSP の制約については、セキュリティを参照してください。

updater

true は、通常の OSS アプリにとって完全に動作する設定です — GitHub リポジトリは package.json の repository フィールドから、公開鍵は .murasaki/update-key.pub から推論され、チャンネルはデフォルトで 'stable'、起動時に一度だけチェックします。オブジェクト形式では、これらのデフォルトに合わない部分だけを上書きすればよいです。

type UpdaterConfig =
  | boolean
  | {
      repo?: string                    // "owner/repo" — デフォルトは package.json#repository
      endpoint?: string                // セルフホストのマニフェスト URL — repo とは排他、https必須(loopback httpはローカルテスト用に許可)
      channel?: string                 // リリースチャンネル、デフォルト 'stable'
      checkOnStart?: boolean           // 起動時に一度チェック、デフォルト true
      checkInterval?: string | false   // 例 '6h' — タイマーで再チェック、デフォルト '6h'
      publicKey?: string               // base64 の Ed25519 公開鍵 — デフォルトは .murasaki/update-key.pub
      publicKeys?: string[]            // ローテーション用の追加pinned key(publicKeyと合わせて最大4つ)
      maxManifestAgeDays?: number      // この日数より古いmanifestを拒否、デフォルト90
      allowLegacyManifestsWithoutGeneratedAt?: boolean // migration用escape hatch、default false
    }

意図的に provider フィールドはありません — GitHub かセルフホストかは、repo と endpoint のどちらが設定されているかから推論されるため、設定の他の部分とずれることがありません。また、署名検証を無効化する方法もありません。セルフホストの endpoint は、認証情報を含まない https: である必要があります（http: はループバックホスト — 127.0.0.1、localhost、[::1] — に対してのみ、ローカルテスト用に許可されます）。この制約は設定の読み込み時と、フェッチ時の両方で強制されます。リプレイ保護のため、generatedAt はデフォルトで必須です。レガシー向けの回避策は、古い署名済みマニフェストを移行する期間だけ有効にしてください。

checkOnStart と checkInterval は更新エンジン自身が処理するため、UI 側で check() を呼ばなくても機能します。useUpdate().check() を手動で呼ぶこともできます — チェックが実行中のときに二重に走ることはありません。

useUpdate() と <UpdateButton />（どちらも murasaki からエクスポートされます）から利用されます。マニフェストの形式、署名、リリースの公開方法については、完全な自動更新ガイドを参照してください。

installer

macOS の DMG のスタイリングと、Windows NSIS / MSI インストーラーのオプションです。省略した場合は Murasaki のデフォルト値が使われます。

installer.windows

組み込みのアップデーターを有効にした Windows 配布では、意図的にユーザー単位の NSIS のみを使用します。MSI の生成はスキップされ、installMode: 'perMachine' は設定の読み込み時に拒否されます。MSI は updater を無効化し、MSI のメジャーアップグレードで管理する配布であれば引き続き利用できます。必要なプラットフォームのパッケージングツールからインストーラーが 1 つも生成されない場合、murasaki installer コマンドは失敗します。ポータブルな ZIP だけが必要な場合は murasaki bundle を使用してください。

sign

Murasaki はあなた自身の証明書または署名プロバイダーで署名し、独自の証明書は一切同梱しません。公証の認証情報と PFX のパスワードは、この設定ではなく常に環境変数から読み取ります — 詳しくはDistribution → Signingを参照してください。

macOS のフィールド

sign.windows

murasaki bundle --sign --target win32-x64 は、ポータブル ZIP を作成する前にアプリの実行ファイルへ署名します。murasaki installer --sign --target win32-x64 は、生成された各インストーラー（NSIS と、アップデーターが無効な場合の MSI）にも署名し、すべての署名を Authenticode ポリシーで検証します。この処理には Windows と SignTool が必要です。

すべての選択方法には CI 用の環境変数によるオーバーライドも用意されています。詳しくはWindows インストーラーと署名を参照してください。

次へ