Nasti

https://github.com/zixiao-labs/nasti
Admin
Nasti is a high-performance Web bundler and dev server built on Rolldown and OXC, offering Vite...
Tokens:94,715
Snippets:434
Trust Score:7.5
License:MIT
Update:7 hours ago
Show doc for...
Tokens:
Raw
### setup(api)

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/plugins.html

插件 setup 钩子，每次配置解析只执行一次。可使用 api.expose() / api.useExposed() 共享能力，并通过 pre / post 声明依赖顺序。

```APIDOC
## setup(api)

### Description
插件 setup 钩子，每次配置解析只执行一次。

### Method
setup

### Parameters
- **api** - Required - 插件 API 对象，提供 `expose` 和 `useExposed` 方法

### 使用示例
```javascript
const key = Symbol.for('example.config')

const provider = {
  name: 'example:provider',
  setup(api) {
    api.expose(key, { enabled: true })
  },
}

const consumer = {
  name: 'example:consumer',
  pre: ['example:provider'],
  setup(api) {
    const config = api.useExposed(key)
  },
}
```
```

--------------------------------

### Install and run Nasti commands

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Commands to install Nasti as a dev dependency, start the development server, and create a production build. Requires Node.js ^20.19.0 or >=22.12.0.

```bash
# 安装
npm install -D @nasti-toolchain/nasti

# 启动开发服务器
npx nasti dev

# 生产构建
npx nasti build
```

--------------------------------

### 插件 setup 与跨插件 API 示例

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/plugins.html

展示插件 setup 与跨插件 API 的使用，通过 api.expose() 和 api.useExposed() 共享能力，并用 pre 声明依赖顺序。

```javascript
const key = Symbol.for('example.config')

const provider = {
  name: 'example:provider',
  setup(api) {
    api.expose(key, { enabled: true })
  },
}

const consumer = {
  name: 'example:consumer',
  pre: ['example:provider'],
  setup(api) {
    const config = api.useExposed(key)
  },
}
```

--------------------------------

### Install monaco-editor

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Install the monaco-editor package as a dependency.

```bash
npm install monaco-editor
```

--------------------------------

### Electron main process example

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Example main process that creates a BrowserWindow. It uses ESM, so __dirname is derived from import.meta.url. In development, it loads the dev server URL from an environment variable; otherwise it loads the built renderer HTML.

```ts
// src/electron/main.ts
import { app, BrowserWindow } from 'electron'
import path from 'node:path'
import { fileURLToPath } from 'node:url'

// ESM 没有隐式 __dirname；此处路径相对于最终输出文件。
const currentDir = path.dirname(fileURLToPath(import.meta.url))

async function createWindow() {
  const win = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.join(currentDir, 'preload.cjs'),
      contextIsolation: true,
      sandbox: true,
    },
  })

  // 开发模式下 Nasti 会通过环境变量传入 dev server URL
  if (process.env.NASTI_DEV_SERVER_URL) {
    await win.loadURL(process.env.NASTI_DEV_SERVER_URL)
  } else {
    await win.loadFile(path.join(currentDir, 'renderer/index.html'))
  }
}

app.whenReady().then(createWindow)
```

--------------------------------

### Build and Run WebGPU Playground

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Commands to build and run the playground-webgpu example using vgpu.

```sh
pnpm build
pnpm --filter playground-webgpu dev
pnpm --filter playground-webgpu build
```

--------------------------------

### Install React and Nasti dependencies

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/react.html

Initializes a new project and installs React, React DOM, and the Nasti toolchain along with TypeScript type definitions.

```bash
# 初始化项目
npm init -y
npm install react react-dom
npm install -D @nasti-toolchain/nasti @types/react @types/react-dom typescript
```

--------------------------------

### Install vgpu Dependencies

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Install vgpu and @vgpu/wgsl in the consuming app workspace, not the monorepo root.

```sh
pnpm --filter <app> add vgpu
pnpm --filter <app> add -D @vgpu/wgsl @webgpu/types
```

--------------------------------

### Configure environments in defineConfig

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/config.html

Example showing how to define client and lynx environments within the Nasti configuration, including HTML entry points and external drivers.

```javascript
export default defineConfig({
  environments: {
    client: {
      html: 'src/renderer/index.html',
    },
    lynx: {
      consumer: 'client',
      driver: 'rspeedy',
    },
  },
})
```

--------------------------------

### Start Electron dev server with npx nasti electron

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/electron.html

Starts the renderer dev server and spawns Electron. Use --no-spawn to only compile main/preload without launching Electron (CI scenario), and --no-restart to disable auto-restart on main/preload changes.

```bash
# 启动渲染进程 dev server 并 spawn Electron
npx nasti electron

# 仅编译主/preload，不启动 Electron（CI 场景）
npx nasti electron --no-spawn

# 禁用主/preload 变更自动重启
npx nasti electron --no-restart
```

--------------------------------

### Vapor Mode 单文件 opt-in 示例

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/vue.html

通过在 script setup 或 template 上添加 vapor 属性启用 Vapor Mode。

```html
<!-- 在 script setup 上加 vapor -->
<script setup vapor>
import { ref } from 'vue'
const count = ref(0)
</script>

<template>
  <button @click="count++">{{ count }}</button>
</template>
```

```html
<!-- 或在 template 上加 vapor（纯 template SFC） -->
<template vapor>
  <div>hi</div>
</template>
```

--------------------------------

### Install Electron with npm

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Install Electron as a dev dependency. The version can be chosen as needed, with support for versions 41, 42, and 43+.

```bash
npm install -D electron@^41
```

--------------------------------

### Install monaco-editor and @nasti-toolchain/nasti

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/monaco.html

Install the monaco-editor package and the Nasti toolchain as a dev dependency. Required before using the monacoEditorPlugin.

```shell
npm install monaco-editor
npm install -D @nasti-toolchain/nasti
```

--------------------------------

### ESM main process usage with import.meta.url

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/electron.html

Shows how to use import.meta.url to get the current directory in an ESM main process, since __dirname is not available. Also demonstrates top-level await for initialization before app.ready. Avoid top-level await app.whenReady(); use app.whenReady().then(createWindow) instead.

```javascript
import path from 'node:path'
import { fileURLToPath } from 'node:url'

// 相对于最终输出文件；ESM 没有隐式 __dirname
const currentDir = path.dirname(fileURLToPath(import.meta.url))
const preload = path.join(currentDir, 'preload.cjs')

// app.ready 前必须完成的初始化要显式 await
await import('./setup.mjs')
```

--------------------------------

### Use pack API from electron-packager

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Example of using the 'pack' function from the experimental electron-packager package. It takes an input directory and output ASAR path, with an optional unpack list.

```js
// 在已链接该 workspace package 的构建工具中使用
import { pack } from '@nasti-toolchain/electron-packager'

await pack({
  input: '/absolute/staged-app',   // 已包含 package.json、main 和运行时依赖
  output: '/absolute/release/app.asar', // 父目录须存在；不覆盖已有输出
  unpack: ['node_modules/native-addon'],
})
```

--------------------------------

### Development commands for Electron

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Start the renderer dev server and Electron, with auto-restart on main/preload changes. Use --no-spawn to compile once and exit, suitable for CI.

```bash
# 同时启动渲染进程 dev server + Electron，主/preload 变更自动重启
nasti electron
```

```bash
# 一次性编译主/preload 后关闭服务器并退出（适合 CI）
nasti electron --no-spawn
```

--------------------------------

### Build native bindings for electron-packager

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Explicitly build the native bindings and optional CLI for the experimental Rust-based electron-packager. This is not done automatically during dependency installation.

```bash
pnpm --filter @nasti-toolchain/electron-packager build
```

--------------------------------

### startElectronDev

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/electron.html

启动开发模式，监听主进程和 preload 变更并自动重启。

```APIDOC
## startElectronDev

### Description
启动开发模式，监听主进程和 preload 变更并自动重启。

### Method
startElectronDev

### Endpoint
startElectronDev(options)

### Parameters
#### Options
- **root** (string) - Required - 项目根目录路径。

### Request Example
```js
await startElectronDev({ root: '.' })
```

### Response
#### Success Response
- 无返回值（Promise<void>）

```

--------------------------------

### Install Vue compiler-sfc optional dependency

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Required to enable Vue support in Nasti. Install as a dev dependency.

```bash
npm install -D @vue/compiler-sfc
```

--------------------------------

### buildStart / buildEnd

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/plugins.html

构建生命周期钩子。

```APIDOC
## buildStart / buildEnd

### Description
构建生命周期钩子。

### Method
buildStart, buildEnd

### Parameters
- **buildStart()** - 无参数
- **buildEnd(error?: Error)** - `error` (Error) - Optional - 构建失败时的错误对象

### Returns
- **void**
```

--------------------------------

### Electron main process (src/electron/main.ts)

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/electron.html

Creates a BrowserWindow with preload, contextIsolation, and sandbox enabled. Loads the dev server URL from NASTI_DEV_SERVER_URL in development, otherwise loads the built renderer index.html.

```typescript
// src/electron/main.ts
import { app, BrowserWindow } from 'electron'
import path from 'node:path'

async function createWindow() {
  const win = new BrowserWindow({
    width: 1200,
    height: 800,
    webPreferences: {
      preload: path.resolve(__dirname, 'preload.cjs'),
      contextIsolation: true,
      sandbox: true,
    },
  })

  // Nasti 在 dev 模式下会将渲染进程 URL 注入 NASTI_DEV_SERVER_URL
  if (process.env.NASTI_DEV_SERVER_URL) {
    await win.loadURL(process.env.NASTI_DEV_SERVER_URL)
  } else {
    await win.loadFile(path.resolve(__dirname, 'renderer/index.html'))
  }
}

app.whenReady().then(createWindow)
```

--------------------------------

### Configure monacoEditorPlugin in nasti.config.ts

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Example configuration for the monacoEditorPlugin, showing languageWorkers, customWorkers, publicPath, and globalAPI options.

```typescript
// nasti.config.ts
import { defineConfig, monacoEditorPlugin } from '@nasti-toolchain/nasti'

export default defineConfig({
  plugins: [
    monacoEditorPlugin({
      // 默认全部启用：editorWorkerService / css / html / json / typescript
      languageWorkers: ['editorWorkerService', 'json', 'typescript'],

      // 自定义 Worker（如 monaco-graphql）
      customWorkers: [
        { label: 'graphql', entry: 'monaco-graphql/esm/graphql.worker' },
      ],

      // Worker URL 前缀，可指向 CDN 绝对 URL
      publicPath: 'monacoeditorwork',

      // 兼容旧 API：将 monaco 暴露到 window.monaco
      globalAPI: false,
    }),
  ],
})
```

--------------------------------

### 启动开发服务器、构建和预览

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/getting-started.html

三个 CLI 命令：启动开发服务器（npx nasti dev）、生产构建（npx nasti build）和预览构建产物（npx nasti preview）。

```bash
# 启动开发服务器
npx nasti dev

# 生产构建
npx nasti build

# 预览构建产物
npx nasti preview
```

--------------------------------

### Build and pack with CLI (shell)

Source: https://github.com/zixiao-labs/nasti/blob/main/packages/electron-packager/README.md

Build the package with pnpm and run the optional CLI to pack a staged app into an ASAR. The CLI supports repeated --unpack flags for exact relative paths or directories.

```shell
# 仓库根，推荐使用与主工程一致的 Node 24 开发环境：
pnpm install --frozen-lockfile
pnpm --filter @nasti-toolchain/electron-packager build

cd packages/electron-packager
# 或单独 npm run build:binding / npm run build:cli

# 可选 CLI：普通 cargo build/test 不开启 binding、不需要 Node 动态符号
cargo build --release --locked
./target/release/nasti-electron-packager pack /absolute/staged-app /absolute/output/app.asar \
  --unpack node_modules/native-addon \
  --unpack assets/helper

# 仅诊断 CLI wrapper 调用已构建 binary：
npm run pack -- /absolute/staged-app /absolute/output/app.asar --unpack assets/helper
```

--------------------------------

### nasti electron-build 命令语法

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/cli.html

Electron 生产构建命令语法，等价于 nasti build --target electron。

```bash
nasti electron-build [root] [options]

# 产物:
# dist/renderer/   Web 渲染层
# dist/main.cjs    主进程
# dist/preload.cjs Preload
```

--------------------------------

### Force Vapor Mode at environment level

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Enable Vapor Mode for all <script setup> and pure template SFCs in the client environment via the vue.features.vapor option. Prints a beta disclaimer to terminal and browser console.

```ts
// 环境级强制：对 <script setup> / 纯 template SFC 启用 Vapor
export default defineConfig({
  framework: 'vue',
  environments: {
    client: {
      vue: { features: { vapor: true } },
    },
  },
})
```

--------------------------------

### Opt-in Vapor Mode per single-file component

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Add the 'vapor' attribute to the <script setup> tag to enable Vapor Mode for that component. Vapor Mode skips Virtual DOM and generates direct DOM operations.

```vue
<!-- 单文件 opt-in -->
<script setup vapor>
import { ref } from 'vue'
const count = ref(0)
</script>
```

--------------------------------

### buildElectron

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/electron.html

执行生产构建，编译 Electron 主进程、preload 和渲染进程代码。

```APIDOC
## buildElectron

### Description
执行生产构建，编译 Electron 主进程、preload 和渲染进程代码。

### Method
buildElectron

### Endpoint
buildElectron(options)

### Parameters
#### Options
- **root** (string) - Required - 项目根目录路径。

### Request Example
```js
await buildElectron({ root: '.' })
```

### Response
#### Success Response
- 无返回值（Promise<void>）

```

--------------------------------

### Use transformRequest and ssrLoadModule in server-consumer dev

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Shows how to transform and load SSR modules without starting an HTTP listener. transformEnvironmentRequest is equivalent to environments.ssr.transformRequest. The returned code is runner-ready with __vite_ssr_* helpers, not browser ESM; externalized modules return null.

```TypeScript
const server = await createServer({ /* Nasti config */ })
const transformed = await server.transformEnvironmentRequest('ssr', '/src/server.ts')
// 等价入口：server.environments.ssr.transformRequest('/src/server.ts')
const exports = await server.ssrLoadModule('/src/server.ts')
const graph = server.environments.ssr.moduleGraph
const entry = graph.getModuleByUrl('/src/server.ts')
// entry.importedModules / dependency.importers 是真实的双向依赖关系
await server.close()
```

--------------------------------

### Configure Rspeedy as external environment driver

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Use this configuration to let Rspeedy take over the 'lynx' environment while keeping Nasti's CLI, logging, and multi-environment orchestration. The bridge plugin is provided via pluginRspeedyBridge() and offers build, serve, watchChange, close, setup(api), api.expose/useExposed, and afterBuildApp(results, api, context).

```TypeScript
export default defineConfig({
  environments: {
    lynx: {
      consumer: 'client',
      driver: 'rspeedy',
    },
  },
  plugins: [pluginRspeedyBridge()],
})
```

--------------------------------

### Package.json for electron-builder

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Configuration for packaging with electron-builder. The main entry points to the built output, and the build script runs the Nasti build followed by electron-builder.

```json
{
  "main": "dist/main.mjs",
  "scripts": {
    "build": "nasti electron-build && electron-builder"
  },
  "build": {
    "files": ["dist/**"],
    "directories": { "output": "release" }
  }
}
```

--------------------------------

### rolldownOptions configuration for tree-shaking and manual code splitting

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/config.html

Set build.rolldownOptions to combine input-side options (treeshake, resolve, external) with output-side options (advancedChunks, chunkFileNames). Nasti takes over input and plugins, and output.dir is always set by build.outDir. The example marks modules under /barrel/ as having no side effects and groups node_modules dependencies into vendor chunks, with dynamic import inlining possible only for a single chunk output.

```javascript
export default defineConfig({
  build: {
    rolldownOptions: {
      // Tree-shaking（input 选项）
      treeshake: {
        moduleSideEffects: [{ test: /\/barrel\//, sideEffects: false }],
      },
      // 代码拆分（output 选项）
      output: {
        advancedChunks: {
          groups: [
            { name: 'react-vendor', test: /node_modules[\\/]react/, priority: 20 },
            { name: 'vendor', test: /node_modules/, priority: 10 },
          ],
        },
        chunkFileNames: 'assets/chunks/[name].[hash].js',
      },
    },
  },
})

```

--------------------------------

### 与 electron-builder 配合的 package.json 配置

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/electron.html

展示如何配置 package.json 以使用 electron-builder 打包，包括 main 入口指向 dist/main.mjs 和构建脚本。

```json
// package.json
{
  "main": "dist/main.mjs",
  "scripts": {
    "build": "nasti electron-build && electron-builder"
  },
  "build": {
    "files": ["dist/**"],
    "directories": {
      "buildResources": "build",
      "output": "release"
    }
  }
}
```

--------------------------------

### Build Electron production with npx nasti electron-build

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/electron.html

Builds the Electron app for production. Equivalent to `npx nasti build --target electron`. The output layout places renderer files in dist/renderer, main process in main.cjs (or main.mjs if mainFormat=esm), and preload in preload.cjs (or preload.mjs if preloadFormat=esm).

```bash
npx nasti electron-build
# 等价于：
npx nasti build --target electron
```

--------------------------------

### Enable ESM main process with mainFormat: 'esm'

Source: https://github.com/zixiao-labs/nasti/blob/main/website/pages/electron.html

Configures Nasti to use ESM for the main process while keeping preload as CJS for sandbox compatibility. Requires Electron 28 or higher; Nasti errors if Electron is below 28 and ESM is configured. ESM preload must be .mjs and require sandbox: false, and dynamic Node imports require contextIsolation: true.

```javascript
export default defineConfig({
  target: 'electron',
  electron: {
    mainFormat: 'esm',
    preloadFormat: 'cjs', // preload 保持 cjs 以兼容 sandbox
  },
})
```

--------------------------------

### Import WGSL Shader as String

Source: https://github.com/zixiao-labs/nasti/blob/main/README.md

Imports a .wgsl file as a raw string and creates a shader module after obtaining a GPUDevice.

```ts
import code from './compute.wgsl'

// 在取得 GPUDevice 后：
const shader = device.createShaderModule({ code })
```
Tokens:
Raw