npm package: @locale-labs/miniapp-builder
Description: Build tool for Localé Mini-Apps
Latest version: 0.1.5

# @locale-labs/miniapp-builder

The official CLI tool to package and build Localé Mini-Apps.

This tool takes your compiled assets (HTML, CSS, JS) and the Localé SDK, and bundles them into a **Single File Artifact** (`index.html`) ready for deployment to the Localé Kernel.

## 📦 Installation

This package is usually installed as a dev dependency in your Mini-App project.

```bash
bun add -d @locale-labs/miniapp-builder
```

## 🚀 Usage

Add a build script to your `package.json`:

```json
{
  "scripts": {
    "build": "locale-miniapp-builder"
  }
}
```

Or run it directly:

```bash
bun x locale-miniapp-builder
```

## ⚙️ How it Works

The builder acts as the **final step** in your build pipeline. It assumes previous steps (like `esbuild` or `tailwindcss`) have already run and placed their outputs in a `.temp/` directory.

### 1. Input Requirements

The builder looks for the following files relative to your project root:

- `.temp/index.html`: The base HTML structure.
- `.temp/output.css`: Compiled Tailwind/CSS.
- `.temp/alpine.js`: Compiled Application Logic (Alpine.js bundle).

### 2. The Process

1.  **Reads Assets**: Loads the HTML, CSS, and JS files from the `.temp/` folder.
2.  **Resolves SDK**: Automatically finds the installed version of `@locale-labs/miniapp-sdk`.
3.  **Cleans HTML**: Removes development scripts (e.g., Tailwind CDN, unbundled Alpine.js tags).
4.  **Inlines Everything**:
    - Injects CSS into a `<style>` block in `<head>`.
    - Injects the **Localé SDK** into a `<script>` block.
    - Injects your **App Bundle** into a `<script>` block.

### 3. Output

The result is a single, self-contained file:

- `build/index.html`

This file contains everything your Mini-App needs to run within the Localé Kernel's iframe sandbox.

## 🛠 Configuration

Currently, the builder uses a "Zero Config" approach with opinionated defaults (expecting the `.temp/` structure).

### Debugging

You can verify which SDK path is being resolved by looking at the console output during the build process. The builder checks:

1.  `LOCALE_SDK_PATH` environment variable.
2.  `node_modules/@locale-labs/miniapp-sdk`
3.  Local fallback paths.

## 📦 Deployment

The builder can be deployed to npm using the `publish` GitHub Action. This will automatically build the package and publish it to the npm registry.

- When you push a commit to the `main` branch, the `publish` GitHub Action will be triggered and the package will be published to the npm registry.
- When you push a commit to the `dev` branch, the `publish` GitHub Action will be triggered and the package will be published to the npm registry with the `beta` tag.

The package will be published to the npm registry with the version number that is specified in the `package.json` file (that is automatically bumped by the [`semantic-release`](https://github.com/semantic-release/semantic-release) plugin).

> [Commit Message Conventions](https://github.com/angular/angular/blob/main/contributing-docs/commit-message-guidelines.md)

- Patch/Fix release: `fix: update readme` (1.0.0 -> 1.0.1)
- Minor/Feature release: `feat: add new feature` (1.0.0 -> 1.1.0)
- Major release: (1.0.0 -> 2.0.0)

  ```
  perf: improve performance of x

  BREAKING CHANGE: The graphiteWidth option has been removed.
  The default graphite width of 10mm is always used for performance reasons.
  ```

---

Developed with ❤️ by **Locale Labs**.