electron-incremental-update 3.0.0-beta.5 → 3.0.0

package/README.md

@@ -1,107 +1,100 @@
 # Electron Incremental Update
 
-This project is built on top of [vite-plugin-electron](https://github.com/electron-vite/vite-plugin-electron), offers a lightweight update solution for Electron applications without using native executables.
+Lightweight incremental update tools for Electron applications built with Vite. The package provides a Vite plugin, an Electron startup wrapper, update providers, bytecode protection, and utilities for common Electron app paths.
+
+## Contents
 
 - [Electron Incremental Update](#electron-incremental-update)
-  - [Key Features](#key-features)
-    - [Dual Asar Architecture](#dual-asar-architecture)
-    - [Update Process](#update-process)
-    - [Additional Features](#additional-features)
-  - [Getting Started](#getting-started)
-    - [Install](#install)
-    - [Project Structure](#project-structure)
-    - [Setup Entry](#setup-entry)
-    - [Setup `vite.config.ts`](#setup-viteconfigts)
-    - [Modify package.json](#modify-packagejson)
-    - [Config `electron-builder`](#config-electron-builder)
-  - [Usage](#usage)
-    - [Use In Main Process](#use-in-main-process)
-      - [Alternative Provider Setup](#alternative-provider-setup)
-      - [Custom logger](#custom-logger)
-      - [Beta Channel Updates](#beta-channel-updates)
-    - [Use Native Modules](#use-native-modules)
-      - [Example](#example)
-      - [Result in app.asar](#result-in-appasar)
-    - [Bytecode Protection](#bytecode-protection)
-      - [Benefits](#benefits)
-      - [Limitation](#limitation)
-    - [Utils](#utils)
-      - [Electron Utilities](#electron-utilities)
-      - [Crypto Utilities](#crypto-utilities)
-      - [Zip Utilities](#zip-utilities)
+  - [Contents](#contents)
+  - [Why](#why)
+  - [How It Works](#how-it-works)
+  - [Installation](#installation)
+  - [Quick Start](#quick-start)
+    - [Entry Process](#entry-process)
+    - [Main Process](#main-process)
+  - [Vite Configuration](#vite-configuration)
+    - [Plugin Options](#plugin-options)
+  - [Electron Builder](#electron-builder)
+  - [Runtime Usage](#runtime-usage)
+  - [Providers](#providers)
+    - [Testing The Local Flow](#testing-the-local-flow)
+  - [Update Artifacts](#update-artifacts)
+  - [Native Modules](#native-modules)
+    - [Result in app.asar](#result-in-appasar)
+  - [Bytecode Protection](#bytecode-protection)
+  - [Development Bundling](#development-bundling)
+  - [Utilities](#utilities)
+  - [API Reference](#api-reference)
   - [Credits](#credits)
   - [License](#license)
 
-## Key Features
-
-This solution provides a comprehensive update system for Electron applications, including:
-
-- **Vite Plugin** - Seamlessly integrates with your existing Vite build process
-- **Startup Entry Function** - Handles application initialization and update checking
-- **Updater Class** - Manages the complete update workflow with event-driven API
-- **Utility Functions** - Helper functions for file paths, version management, and more
+## Why
 
-### Dual Asar Architecture
+Electron applications are commonly shipped as full installers. This package keeps the installer stable and updates only the application asar file, which makes update packages smaller and keeps the runtime workflow explicit.
 
-The update system uses a two-file structure for efficient incremental updates:
+Key features:
 
-- **`app.asar`** - The application entry point that loads and initializes the updater
-- **`${electron.app.name}.asar`** - Contains your application code (main process, preload scripts, and renderer) that gets replaced during updates
+- Vite plugin based on `vite-plugin-electron/multi-env`
+- Dual asar runtime layout
+- Signed update metadata and asar verification
+- GitHub and local development providers
+- Optional V8 bytecode generation
+- Utilities for app paths, native modules, renderer loading, and Electron startup
 
-### Update Process
+## How It Works
 
-The update workflow follows these steps:
+The packaged app uses two asar files:
 
-1. **Check for Updates** - Query the remote server for available updates
-2. **Download and Verify** - Download the update asar file and verify it using RSA signatures
-3. **Prepare for Update** - The application quits to prepare for the update
-4. **Apply Update** - On next launch, replace the old `${electron.app.name}.asar` with the new version and load it
+- `app.asar`: the stable entry asar generated from `entry.files`
+- `${app.name}.asar`: the replaceable application asar generated from the Electron main, preload, and renderer build outputs
 
-### Additional Features
+The update flow is:
 
-- **Smaller Update Packages** - Package all native modules into `app.asar` to minimize the update file size and download time [see usage](#use-native-modules)
-- **Source Code Protection** - Leverage V8 bytecode compilation to obfuscate and protect your JavaScript source code [see details](#bytecode-protection)
+1. `createElectronApp()` starts from `app.asar`.
+2. If `${app.name}.asar.tmp` exists, it is renamed to `${app.name}.asar`.
+3. The configured main file is loaded from `${app.name}.asar`.
+4. Your main process calls `updater.checkForUpdates()`.
+5. The provider downloads `version.json`.
+6. The updater compares versions and emits `update-available` when a newer update exists.
+7. `updater.downloadUpdate()` downloads, decompresses, verifies, and writes `${app.name}.asar.tmp`.
+8. `updater.quitAndInstall()` restarts the app so the new asar can be installed on next launch.
 
-## Getting Started
-
-### Install
+## Installation
 
 ```sh
-npm install -D electron-incremental-update
+npm install -D electron-incremental-update @electron/asar @babel/core
 ```
 
 ```sh
-yarn add -D electron-incremental-update
+pnpm add -D electron-incremental-update @electron/asar @babel/core
 ```
 
 ```sh
-pnpm add -D electron-incremental-update
+yarn add -D electron-incremental-update @electron/asar @babel/core
 ```
 
-### Project Structure
+> Upgrading from `3.0.0-beta.x`? See [MIGRATION.md](./MIGRATION.md).
 
-Base on [electron-vite-vue](https://github.com/electron-vite/electron-vite-vue)
+## Quick Start
 
-```
+Recommended project layout:
+
+```txt
 electron
-├── entry.ts // <- entry file
+├── entry.ts
 ├── main
 │   └── index.ts
 ├── preload
 │   └── index.ts
-└── native // <- possible native modules
-    └── index.ts
+└── native
+    └── db.ts
 src
 └── ...
 ```
 
-### Setup Entry
-
-The entry is used to load the application and initialize the `Updater`
+### Entry Process
 
-`Updater` use the `provider` to check and download the update. The built-in `GithubProvider` is based on `BaseProvider`, which implements the `IProvider` interface (see [types](#provider)). And the `provider` is optional, you can setup later
-
-in `electron/entry.ts`
+`electron/entry.ts` is the stable startup file. It creates the updater and loads the real main process from `${app.name}.asar`.
 
 ```ts
 import { createElectronApp } from 'electron-incremental-update'
@@ -109,123 +102,177 @@ import { GitHubProvider } from 'electron-incremental-update/provider'
 
 createElectronApp({
   updater: {
-    // optional, you can setup later
     provider: new GitHubProvider({
-      username: 'yourname',
-      repo: 'electron',
+      user: 'your-github-user',
+      repo: 'your-repo',
     }),
   },
   beforeStart(mainFilePath, logger) {
-    logger?.debug(mainFilePath)
+    logger?.debug(`Starting app from ${mainFilePath}`)
   },
 })
 ```
 
-- [some Github CDN resources](https://github.com/XIU2/UserScript/blob/master/GithubEnhanced-High-Speed-Download.user.js#L34)
+### Main Process
 
-### Setup `vite.config.ts`
+The main entry must default-export one function wrapped with `startupWithUpdater()`.
 
-The plugin config, `main` and `preload` parts are reference from [electron-vite-vue](https://github.com/electron-vite/electron-vite-vue)
+```ts
+import { app, BrowserWindow, dialog } from 'electron'
+import { startupWithUpdater } from 'electron-incremental-update'
+import { getAppVersion, getPathFromPreload, loadPage } from 'electron-incremental-update/utils'
 
-- certificate will read from `process.env.UPDATER_CERT` first, if absent, read config
-- privatekey will read from `process.env.UPDATER_PK` first, if absent, read config
+export default startupWithUpdater(async (updater) => {
+  await app.whenReady()
 
-See all config in [types](#plugin)
+  const win = new BrowserWindow({
+    webPreferences: {
+      preload: getPathFromPreload('index.js'),
+    },
+  })
 
-in `vite.config.mts`
+  loadPage(win)
 
-```ts
-import { debugStartup, electronWithUpdater } from 'electron-incremental-update/vite'
-import { defineConfig } from 'vite'
+  updater.on('update-available', async ({ version }) => {
+    const { response } = await dialog.showMessageBox({
+      type: 'info',
+      message: `Version ${version} is available. Current version is ${getAppVersion()}.`,
+      buttons: ['Download', 'Later'],
+    })
 
-export default defineConfig(async ({ command }) => {
-  const isBuild = command === 'build'
-  return {
-    plugins: [
-      electronWithUpdater({
-        isBuild,
-        entry: {
-          files: ['./electron/entry.ts', './electron/native/index.ts'],
-        },
-        main: {
-          files: ['./electron/main/index.ts', './electron/main/worker.ts'],
-          // see https://github.com/electron-vite/electron-vite-vue/blob/85ed267c4851bf59f32888d766c0071661d4b94c/vite.config.ts#L22-L28
-          onstart: debugStartup,
-        },
-        preload: {
-          files: './electron/preload/index.ts',
-        },
-        updater: {
-          // options
-        },
-      }),
-    ],
-    server:
-      process.env.VSCODE_DEBUG &&
-      (() => {
-        const url = new URL(pkg.debug.env.VITE_DEV_SERVER_URL)
-        return {
-          host: url.hostname,
-          port: +url.port,
-        }
-      })(),
-  }
+    if (response === 0) {
+      await updater.downloadUpdate()
+    }
+  })
+
+  updater.on('download-progress', (info) => {
+    win.webContents.send('update-progress', info)
+  })
+
+  updater.on('update-downloaded', async () => {
+    const { response } = await dialog.showMessageBox({
+      type: 'info',
+      message: 'Update downloaded.',
+      buttons: ['Restart Now', 'Later'],
+    })
+
+    if (response === 0) {
+      updater.quitAndInstall()
+    }
+  })
+
+  updater.on('update-not-available', (code, message) => {
+    console.log(`[${code}] ${message}`)
+  })
+
+  updater.on('error', (error) => {
+    console.error(error)
+  })
+
+  await updater.checkForUpdates()
 })
 ```
 
-Or use the helper function
+## Vite Configuration
+
+Use `defineElectronConfig()` when the same Vite config owns the renderer and Electron processes.
 
 ```ts
 import { defineElectronConfig } from 'electron-incremental-update/vite'
 
 export default defineElectronConfig({
   entry: {
-    files: ['./electron/entry.ts', './electron/native/index.ts'],
+    files: './electron/entry.ts',
   },
   main: {
-    files: ['./electron/main/index.ts', './electron/main/worker.ts'],
-    // see https://github.com/electron-vite/electron-vite-vue/blob/85ed267c4851bf59f32888d766c0071661d4b94c/vite.config.ts#L22-L28
-    onstart: debugStartup,
+    files: './electron/main/index.ts',
   },
   preload: {
     files: './electron/preload/index.ts',
   },
   updater: {
-    // options
+    minimumVersion: '0.0.0',
+    paths: {
+      asarOutputPath: 'release/my-app.asar',
+      compressedPath: 'release/my-app-1.0.0.asar.br',
+      versionPath: 'release/version.json',
+    },
   },
   renderer: {
-    server:
-      process.env.VSCODE_DEBUG &&
-      (() => {
-        const url = new URL(pkg.debug.env.VITE_DEV_SERVER_URL)
-        return {
-          host: url.hostname,
-          port: +url.port,
+    server: process.env.VSCODE_DEBUG
+      ? {
+          host: '127.0.0.1',
+          port: 5173,
         }
-      })(),
+      : undefined,
   },
 })
 ```
 
-### Modify package.json
+Use `electronWithUpdater()` directly when you want to manage the renderer config yourself.
+
+```ts
+import { electronWithUpdater } from 'electron-incremental-update/vite'
+import { defineConfig } from 'vite'
+
+export default defineConfig({
+  plugins: [
+    electronWithUpdater({
+      entry: {
+        files: './electron/entry.ts',
+      },
+      main: {
+        files: './electron/main/index.ts',
+      },
+      preload: {
+        files: './electron/preload/index.ts',
+      },
+    }),
+  ],
+})
+```
+
+### Plugin Options
+
+Common options overview:
+
+- `entry.files`: entry process input. Required.
+- `main.files`: main process input. Required.
+- `preload.files`: preload process input. Optional.
+- `sourcemap`: defaults to development or `VSCODE_DEBUG`.
+- `minify`: defaults to production builds.
+- `bytecode`: `true` or bytecode options.
+- `notBundle`: externalizes Node modules in development. Defaults to `true`.
+- `external`: additional Vite/Rolldown externals. Use `true` to externalize `dependencies`.
+- `buildVersionJson`: generates update JSON. Defaults to CI only.
+- `localDevUpdate`: generates and serves a local update package during dev startup. Use `true`
+  for defaults, or pass `{ baseDir, packageJsonPath, chunkSize, chunkDelay }`. See [Testing The Local Flow](#testing-the-local-flow) for details.
+- `updater.minimumVersion`: minimum supported entry asar version. Defaults to `0.0.0`.
+
+> 📖 See [API.md → Plugin Options](./API.md#plugin-options) for the complete reference including all types, defaults, paths, keys, and generator overrides.
+
+## Electron Builder
+
+Set `package.json#main` to the entry output file:
 
 ```json
 {
-  "main": "dist-entry/entry.js" // <- entry file path
+  "main": "dist-entry/entry.js"
 }
 ```
 
-### Config `electron-builder`
+Minimal `electron-builder.config.cjs`:
 
 ```js
 const { name } = require('./package.json')
 
 const targetFile = `${name}.asar`
+
 /**
  * @type {import('electron-builder').Configuration}
  */
 module.exports = {
-  appId: 'YourAppID',
+  appId: `org.${name}`,
   productName: name,
   files: [
     // entry files
@@ -243,168 +290,149 @@ module.exports = {
 }
 ```
 
-## Usage
-
-### Use In Main Process
+## Runtime Usage
 
-The updater should be initialized in your main process. The startup function will automatically handle update checks and installation.
-
-**NOTE: There should only be one function and should be the default export in the main index file**
+```ts
+import { createElectronApp } from 'electron-incremental-update'
+import { GitHubProvider } from 'electron-incremental-update/provider'
 
-in `electron/main/index.ts`
+createElectronApp({
+  updater: {
+    provider: new GitHubProvider({
+      user: 'your-github-user',
+      repo: 'your-repo',
+    }),
+  },
+  beforeStart(mainFilePath, logger) {
+    logger?.debug(`Starting app from ${mainFilePath}`)
+  },
+})
+```
 
-```ts
-import { app, dialog } from 'electron'
-import { startupWithUpdater } from 'electron-incremental-update'
-import {
-  getPathFromAppNameAsar,
-  getAppVersion,
-  getEntryVersion,
-} from 'electron-incremental-update/utils'
+The full `Updater` API, `createElectronApp` options, `AppOption`, events, and error codes are documented in the API reference.
 
-export default startupWithUpdater(async (updater) => {
-  await app.whenReady()
+> 📖 See [API.md → Entry API](./API.md#entry-api) for the complete reference.
 
-  // Display current app information
-  console.table({
-    [`${app.name}.asar path:`]: getPathFromAppNameAsar(),
-    'app version:': getAppVersion(),
-    'entry (installer) version:': getEntryVersion(),
-    'electron version:': process.versions.electron,
-  })
+## Providers
 
-  // Listen for download progress
-  updater.onDownloading = ({ percent }) => {
-    console.log(`Download progress: ${percent}%`)
-  }
+The package includes GitHub-based providers (file, atom, API) and a local development provider.
 
-  // Listen for available updates
-  updater.on('update-available', async ({ version }) => {
-    const { response } = await dialog.showMessageBox({
-      type: 'info',
-      buttons: ['Download', 'Later'],
-      message: `Version ${version} update available!`,
-    })
-    if (response === 0) {
-      // 0 = Download button
-      await updater.downloadUpdate()
-    }
-  })
+- **GitHubProvider** — reads `version.json` from a repository branch, downloads asar from Releases.
+- **GitHubAtomProvider** — reads the latest release from `releases.atom`.
+- **GitHubApiProvider** — uses the GitHub Releases API (supports tokens for private repos).
+- **LocalDevProvider** — reads update artifacts from the local filesystem for dev testing.
 
-  // Handle no updates available
-  updater.on('update-not-available', (code, reason, info) => {
-    console.log('No update available:', reason)
-  })
+All GitHub providers support a `urlHandler` for mirrors and custom gateways.
 
-  // Handle download progress (alternative to onDownloading)
-  updater.on('download-progress', (data) => {
-    console.log('Download progress:', data)
-    // Send progress to renderer if needed
-    const [mainWindow] = BrowserWindow.getAllWindows()
-    if (mainWindow) {
-      mainWindow.webContents.send('update-progress', data)
-    }
-  })
+See the [API reference](./API.md#providers) for the complete provider constructor options and method signatures.
 
-  // Handle update completion
-  updater.on('update-downloaded', () => {
-    dialog
-      .showMessageBox({
-        type: 'info',
-        message: 'Update downloaded successfully!',
-        buttons: ['Restart Now', 'Later'],
-      })
-      .then(({ response }) => {
-        if (response === 0) {
-          updater.quitAndInstall()
-        }
-      })
-  })
+### Testing The Local Flow
 
-  // Handle errors
-  updater.on('error', (error) => {
-    console.error('Update error:', error)
-    dialog.showErrorBox('Update Error', error.message || 'Failed to check for updates')
-  })
+Prefer `localDevUpdate: true` in the Vite plugin over constructing `LocalDevProvider` manually.
+See [playground](./playground) as a complete local update test:
 
-  // Start checking for updates
-  updater.checkForUpdates()
-})
+```sh
+bun run play
 ```
 
-#### Alternative Provider Setup
+`bun run play` builds the package first, then starts the Vite dev server and Electron playground.
 
-You can also change the provider dynamically:
+Expected flow:
 
-```ts
-// In main.ts
-updater.provider = new GitHubProvider({
-  owner: 'your-username',
-  repo: 'your-repo',
-  // Custom URL handling for mirrors or private repos
-  urlHandler: (url) => {
-    url.hostname = 'mirror.ghproxy.com'
-    url.pathname = `https://github.com${url.pathname}`
-    return url
-  },
-})
-```
+1. The plugin builds the Electron main, preload, and entry outputs.
+2. The plugin creates `DEV.asar` and a local update archive.
+3. `createElectronApp()` installs any existing `DEV.asar.tmp`.
+4. The app starts from `DEV.asar`.
+5. The updater checks the generated `version.json`.
+6. The playground shows an available local update.
+7. Clicking download emits simulated progress events.
+8. Clicking restart installs `DEV.asar.tmp` and restarts Electron.
 
-#### Custom logger
+Explicit `updater.provider` values still take priority. If you set a provider manually, automatic
+local provider setup is skipped.
 
-```ts
-updater.logger = console
-```
+## Update Artifacts
 
-#### Beta Channel Updates
+The Vite plugin can generate:
 
-```ts
-updater.receiveBeta = true
-```
+- `${app.name}.asar`
+- `${app.name}-${version}.asar.br`
+- `version.json`
 
-### Use Native Modules
+Default `version.json` shape:
 
-To reduce production size, it is recommended that all the **native modules** should be set as `dependency` in `package.json` and other packages should be set as `devDependencies`. Also, `electron-rebuild` only check dependencies inside `dependency` field.
+```json
+{
+  "version": "1.0.0",
+  "minimumVersion": "0.0.0",
+  "signature": "...",
+  "beta": {
+    "version": "1.0.1-beta.1",
+    "minimumVersion": "0.0.0",
+    "signature": "..."
+  }
+}
+```
 
-If you are using `electron-builder` to build distributions, all the native modules with its **large relevant `node_modules`** will be packaged into `app.asar` by default.
+Stable releases update both the top-level fields and `beta`. Prerelease versions update only `beta`.
 
-Luckily, `vite` can bundle all the dependencies. Just follow the steps:
+Set `buildVersionJson: true` if you need metadata during non-CI builds.
 
-1. setup `entry.files` option
-2. Manually copy the native binaries in `entry.postBuild` callback
-3. Exclude all the dependencies in `electron-builder`'s config
-4. call the native functions with `requireNative` / `importNative` in your code
+> [!NOTE]
+> The **default** version parser supports `major.minor.patch[-prerelease[.number]]` (e.g. `1.0.0-beta.1`).
+> Build metadata (`+build`) and complex semver prerelease identifiers (e.g. `1.0.0-beta.1.2`)
+> are not supported by default.
+>
+> To use full semver or a custom version scheme, override
+> [`provider.isLowerVersion`](#providers) with your own comparator
+> (e.g. `semver.lt` from the `semver` package).
 
-#### Example
+## Native Modules
 
-in `vite.config.ts`
+To keep update packages small, put native modules and their native binaries in `app.asar`, then load them from the main process with `requireNative()` or `importNative()`.
 
 ```ts
-const plugin = electronWithUpdater({
-  // options...
-  entry: {
-    files: ['./electron/native/entry.ts', './electron/native/db.ts', './electron/native/img.ts'],
-    postBuild: ({ copyToEntryOutputDir, copyModules }) => {
-      // for better-sqlite3
-      copyToEntryOutputDir({
-        from: './node_modules/better-sqlite3/build/Release/better_sqlite3.node',
-        skipIfExist: false,
-      })
-      // for @napi-rs/image
-      const startStr = '@napi-rs+image-'
-      const fileName = readdirSync('./node_modules/.pnpm').find((p) => p.startsWith(startStr))!
-      const archName = fileName.substring(startStr.length).split('@')[0]
-      copyToEntryOutputDir({
-        from: `./node_modules/.pnpm/${fileName}/node_modules/@napi-rs/image-${archName}/image.${archName}.node`,
-      })
-      // or just copy specific dependency
-      copyModules({ modules: ['better-sqlite3'] })
-    },
-  },
-})
+import { readdirSync } from 'node:fs'
+
+import { electronWithUpdater } from 'electron-incremental-update/vite'
+
+export default {
+  plugins: [
+    electronWithUpdater({
+      external: false,
+      entry: {
+        files: ['./electron/entry.ts', './electron/native/db.ts'],
+        postBuild({ isBuild, copyToEntryOutputDir }) {
+          if (!isBuild) {
+            return
+          }
+
+          copyToEntryOutputDir({
+            from: './node_modules/better-sqlite3/build/Release/better_sqlite3.node',
+            skipIfExist: false,
+          })
+
+          const packageName = readdirSync('./node_modules/.pnpm').find((name) =>
+            name.startsWith('@napi-rs+image-'),
+          )
+
+          if (packageName) {
+            const archName = packageName.substring('@napi-rs+image-'.length).split('@')[0]
+            copyToEntryOutputDir({
+              from: `./node_modules/.pnpm/${packageName}/node_modules/@napi-rs/image-${archName}/image.${archName}.node`,
+            })
+          }
+        },
+      },
+      main: {
+        files: './electron/main/index.ts',
+      },
+    }),
+  ],
+}
 ```
 
-in `electron/native/db.ts`
+Use the copied native binding from entry asar:
 
 ```ts
 import Database from 'better-sqlite3'
@@ -414,38 +442,27 @@ const db = new Database(':memory:', {
   nativeBinding: getPathFromEntryAsar('./better_sqlite3.node'),
 })
 
-export function test(): void {
-  db.exec(
-    'DROP TABLE IF EXISTS employees; ' +
-      'CREATE TABLE IF NOT EXISTS employees (name TEXT, salary INTEGER)',
-  )
-
-  db.prepare('INSERT INTO employees VALUES (:n, :s)').run({
-    n: 'James',
-    s: 5000,
+export function testDatabase(): void {
+  db.exec('CREATE TABLE IF NOT EXISTS employees (name TEXT, salary INTEGER)')
+  db.prepare('INSERT INTO employees VALUES (:name, :salary)').run({
+    name: 'James',
+    salary: 5000,
   })
-
-  const r = db.prepare('SELECT * from employees').all()
-  console.log(r)
-  // [ { name: 'James', salary: 50000 } ]
-
-  db.close()
 }
 ```
 
-in `electron/main/service.ts`
+Load native helper modules from main:
 
 ```ts
 import { importNative, requireNative } from 'electron-incremental-update/utils'
 
-// commonjs
-requireNative<typeof import('../native/db')>('db').test()
+requireNative<typeof import('../native/db')>('db').testDatabase()
 
-// esm
-importNative<typeof import('../native/db')>('db').test()
+const nativeDb = await importNative<typeof import('../native/db')>('db')
+nativeDb.testDatabase()
 ```
 
-in `electron-builder.config.js`
+For `electron-builder`, exclude `node_modules` when you have bundled dependencies manually:
 
 ```js
 module.exports = {
@@ -457,7 +474,7 @@ module.exports = {
 }
 ```
 
-#### Result in app.asar
+### Result in app.asar
 
 Before: Redundant 🤮
 
@@ -525,114 +542,62 @@ After: Clean 😍
 └── package.json
 ```
 
-### Bytecode Protection
+## Bytecode Protection
 
-Use V8 cache to protect the source code
+Bytecode protection compiles JavaScript into V8 bytecode.
 
 ```ts
 electronWithUpdater({
-  // ...
-  bytecode: true, // or options
+  bytecode: true,
+  entry: {
+    files: './electron/entry.ts',
+  },
+  main: {
+    files: './electron/main/index.ts',
+  },
 })
 ```
 
-#### Benefits
+Notes:
 
-https://electron-vite.org/guide/source-code-protection
+- CommonJS only. Remove `"type": "module"` from `package.json` when enabling bytecode.
+- Main process bytecode is enabled by default.
+- To include preload scripts, use `bytecode: { enablePreload: true }`.
+- If preload bytecode is enabled, create the `BrowserWindow` with `sandbox: false`.
 
-- Improve the string protection (see [original issue](https://github.com/alex8088/electron-vite/issues/552))
-- Protect all strings by default
-- Minification is allowed
+## Development Bundling
 
-#### Limitation
+`notBundle` is enabled by default in development. It externalizes Node modules in entry and main builds to improve startup speed.
 
-- Only support commonjs
-- Only for main process by default, if you want to use in preload script, please use `electronWithUpdater({ bytecode: { enablePreload: true } })` and set `sandbox: false` when creating window
+```ts
+electronWithUpdater({
+  notBundle: false,
+  entry: {
+    files: './electron/entry.ts',
+  },
+  main: {
+    files: './electron/main/index.ts',
+  },
+})
+```
 
-### Utils
+## Utilities
 
-Utility functions of Electron helper, crypto, and file compression.
+Import from `electron-incremental-update/utils` for path helpers, platform checks, native module loading, crypto, compression, download, and version parsing utilities.
 
-```ts
-import {
-  // Electron utilities
-  isDev,
-  isWin,
-  isMac,
-  isLinux,
-  getPathFromAppNameAsar,
-  getPathFromEntryAsar,
-  getPathFromMain,
-  getPathFromPreload,
-  getPathFromPublic,
-  getAppVersion,
-  getEntryVersion,
-  requireNative,
-  importNative,
-  restartApp,
-  setAppUserModelId,
-  disableHWAccForWin7,
-  singleInstance,
-  setPortableDataPath,
-  loadPage,
-  beautifyDevTools,
-  handleUnexpectedErrors,
-
-  // Crypto utilities
-  hashBuffer,
-  aesEncrypt,
-  aesDecrypt,
-  defaultSignature,
-  defaultVerifySignature,
-
-  // Zip utilities
-  defaultZipFile,
-  defaultUnzipFile,
-} from 'electron-incremental-update/utils'
-```
+> 📖 See [API.md → Utilities API](./API.md#utilities-api) for the complete function list with signatures and descriptions.
+
+## API Reference
+
+For the full API documentation including all types, options tables, provider constructors, and plugin configuration, see the standalone reference:
 
-#### Electron Utilities
-
-- **isDev** - Compile-time dev check
-- **isWin** - Check if running on Windows
-- **isMac** - Check if running on macOS
-- **isLinux** - Check if running on Linux
-- **getPathFromAppNameAsar(...paths)** - Get joined path of `${electron.app.name}.asar`
-- **getPathFromEntryAsar(...paths)** - Get joined path from entry asar
-- **getPathFromMain(...paths)** - Get joined path from main dir
-- **getPathFromPreload(...paths)** - Get joined path from preload dir
-- **getPathFromPublic(...paths)** - Get joined path from public dir
-- **getAppVersion()** - Get app version (returns entry version in dev)
-- **getEntryVersion()** - Get entry version
-- **requireNative(moduleName)** - Load native module using require from entry asar
-- **importNative(moduleName)** - Load native module using import from entry asar
-- **restartApp()** - Restart the Electron app
-- **setAppUserModelId(id)** - Fix app model ID (Windows only)
-- **disableHWAccForWin7()** - Disable hardware acceleration for Windows 7
-- **singleInstance(window)** - Keep single instance and restore window
-- **setPortableDataPath(dirName, create)** - Set userData dir to exe dir for portable apps
-- **loadPage(win, htmlFilePath)** - Load dev server URL in dev or HTML file otherwise
-- **beautifyDevTools(win, options)** - Beautify devtools font and scrollbar
-- **handleUnexpectedErrors(callback)** - Handle all unhandled errors
-
-#### Crypto Utilities
-
-- **hashBuffer(data, length)** - Hash data using SHA-256
-- **aesEncrypt(plainText, key, iv)** - Encrypt text using AES
-- **aesDecrypt(encryptedText, key, iv)** - Decrypt text using AES
-- **defaultSignature(buffer, privateKey, cert, version)** - Generate RSA signature for asar file
-- **defaultVerifySignature(buffer, version, signature, cert)** - Verify RSA signature of asar file
-
-#### Zip Utilities
-
-- **defaultZipFile(buffer)** - Compress file using brotli
-- **defaultUnzipFile(buffer)** - Decompress file using brotli
+> 📖 **[API.md](./API.md)** — Auto-generated JSDoc extraction + manual reference sections.
 
 ## Credits
 
-- [Obsidian](https://obsidian.md/) for upgrade strategy
-- [vite-plugin-electron](https://github.com/electron-vite/vite-plugin-electron) for vite plugin
-- [electron-builder](https://github.com/electron-userland/electron-builder) for update api
+- [Obsidian](https://obsidian.md/) for the dual asar update strategy
+- [vite-plugin-electron](https://github.com/electron-vite/vite-plugin-electron) for the Vite Electron plugin foundation
+- [electron-builder](https://github.com/electron-userland/electron-builder) for Electron packaging
 - [electron-vite](https://github.com/alex8088/electron-vite) for bytecode plugin inspiration
 
 ## License