npm package: @ptahjs/build
Description: PtahJs Building Tool
Author: Bobby
Latest version: 1.1.6

<p align='center'>
<img src='https://www.ptahjs.com/assets/image/logo.png' alt="@ptahjs/build - PtahJs Building Tool"><br>
PtahJs Building Tool
</p>

# @ptahjs/build

A unified Vite build configuration tool for the PtahJs ecosystem. Provides ready-to-use build presets for Vue apps, Vapor apps, library mode, and Module Federation.

## Installation

```bash
pnpm add -D @ptahjs/build
```

## Quick Start

Create `vite.config.js` in your project root:

```js
import { buildConfig } from '@ptahjs/build'

export default buildConfig({
    mode: ['vue'],
})
```

## API

### `buildConfig(options)`

Returns a Vite config object (wrapped in `defineConfig`).

#### General Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `mode` | `string[]` | `['vue']` | Build mode. Accepted values: `vue` / `vapor` / `library` |
| `base` | `string` | `'./'` | Vite public base path |
| `external` | `string[]` | `[]` | Dependencies to exclude from the bundle |
| `input` | `string` | `''` | Custom entry file |
| `minify` | `boolean` | `true` | Minify output |
| `plugins` | `Plugin[]` | `[]` | Additional Vite plugins |
| `server` | `object` | `{}` | Vite dev server options (default host: `0.0.0.0`) |
| `resolveAlias` | `object` | `{}` | Path aliases |
| `developmentResolveAlias` | `object` | `{}` | Path aliases applied only in development mode |
| `pluginOption` | `object` | `{}` | Options for Vue / JSX Vapor plugins (`vueConfig` / `jsxVaporConfig`) |
| `codeSplitting` | `object[]` | `[]` | Rollup code splitting groups |
| `autoImport` | `object` | `{}` | Auto-import configuration (reserved) |
| `test` | `object` | `{}` | Vitest unit test configuration |

#### Library Mode (`mode: ['library']`)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `libraryEntry` | `string` | `'./src/index.js'` | Library entry file |
| `libraryFileName` | `string` | `'lib'` | Output filename (without extension) |
| `styleId` | `string` | `''` | Style ID used when injecting CSS into JS |

#### Module Federation (`remote: true`)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `remote` | `boolean` | `false` | Enable Module Federation remote module |
| `federation.exposes` | `object` | `{}` | Module map exposed to other apps |
| `federation.shared` | `string[]` | `[]` | Shared dependency list |

#### Code Obfuscation

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `obfuscator` | `boolean` | `false` | Enable code obfuscation |
| `obfuscatorLevel` | `0\|1\|2` | `1` | Obfuscation level: `0` no compression, `1` standard, `2` advanced |

#### Serve Configuration

| Option | Type | Description |
|--------|------|-------------|
| `serveConfig.path` | `string` | JSON config file path; enables `@ptahjs/vite-plugin-json` when set |
| `serveConfig.outputDirectory` | `string` | Output directory |
| `serveConfig.outputName` | `string` | Output filename |

#### License Validation

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `licenseValidator` | `boolean` | `false` | Inject license validation logic (used by core packages) |

## Examples

### Vue App

```js
import { buildConfig } from '@ptahjs/build'

export default buildConfig({
    mode: ['vue'],
    external: ['vue'],
    server: { port: 3000 },
})
```

### Vapor (JSX) App

```js
import { buildConfig } from '@ptahjs/build'

export default buildConfig({
    mode: ['vapor'],
    pluginOption: {
        jsxVaporConfig: { /* vue-jsx-vapor options */ },
    },
})
```

### Library Mode

```js
import { buildConfig } from '@ptahjs/build'

export default buildConfig({
    mode: ['library'],
    libraryEntry: './src/index.js',
    libraryFileName: 'my-lib',
    external: ['vue'],
    minify: true,
})
```

### Module Federation (Remote Module)

```js
import { buildConfig } from '@ptahjs/build'

export default buildConfig({
    mode: ['vue'],
    remote: true,
    federation: {
        exposes: {
            './Button': './src/components/Button.vue',
        },
        shared: ['vue'],
    },
})
```

### Code Splitting with Auto Version Injection

In `vue` / `vapor` mode, chunks listed in `codeSplitting` automatically have the corresponding package version injected into their filename:

```js
import { buildConfig } from '@ptahjs/build'

export default buildConfig({
    mode: ['vue'],
    codeSplitting: [
        { name: 'runtime', match: /^\/packages\/runtime\// },
    ],
})
// Output example: assets/runtime-1.2.3-abc123.js
```

## Built-in Plugins

| Plugin | Condition | Description |
|--------|-----------|-------------|
| `@vitejs/plugin-vue` | `mode` includes `vue` | Vue SFC support |
| `vue-jsx-vapor/vite` | `mode` includes `vapor` | Vue JSX Vapor support |
| `@module-federation/vite` | `remote: true` | Module Federation support |
| `StyleInjectPlugin` | `mode` includes `library` | Inlines CSS into JS output (library mode) |
| `ObfuscatorPlugin` | `obfuscator: true` | Code obfuscation via `javascript-obfuscator` |
| `LicenseCodePlugin` | `licenseValidator: true` | Injects license validation code |
| `VirtualLicensePlugin` | `licenseValidator: true` | Provides a virtual license module |
| `@ptahjs/vite-plugin-json` | `serveConfig.path` is set | Serves JSON configuration files |

## Notes

- `__VUE_OPTIONS_API__` is disabled by default in all modes to reduce bundle size.
- The dev server listens on `0.0.0.0` by default for LAN access.
- `developmentResolveAlias` only takes effect when `mode=development`, useful for local monorepo source debugging.