npm package: @odvi/lego-box
Description: A Piral instance (Shell/Emulator) for building micro-frontends
Latest version: 1.0.8

Shell -> pnpm release:patch

Pilet:
npm init pilet --source your-app-shell-name
pilet upgrade --source your-app-shell-name


if (process.env.NODE_ENV === 'development') {
  return fetch('http://localhost:1234/$pilet-api').then(res => res.json());
}



npm init pilet --source @odvi/lego-box

npx pilet debug


Debugging with "Remote" Pilets

Sometimes, a developer wants to see how their pilet looks alongside other pilets that are already published to your feed. They can use the --feed flag:
Bash

npx pilet debug --feed https://your-feed-url.com/api/v1/pilet/your-shell


# This updates the pilet's reference to use v2 of your shell
npx pilet upgrade --source your-app-shell-name@2.0.0

# From a parent directory containing pilet-a, pilet-b, and pilet-c
npx pilet debug pilet-a/src/index.tsx pilet-b/src/index.tsx pilet-c/src/index.tsx




# Lego Box - Piral Instance

A Piral Shell (Emulator) for building micro-frontends with React.

## What is Piral?

Piral is a framework for building micro-frontends. This instance (the "shell" or "emulator") provides the foundation for developing and integrating "pilets" (independent micro-frontend modules).

---

## For Consumers: Using This Piral Instance

Once published to npm, other developers can use this instance to scaffold their own pilets.

### Prerequisites

```bash
npm install -g piral-cli
# or
pnpm add -g piral-cli
```

### Scaffold a New Pilet

Create a new pilet targeting this published shell using the `--source` flag:

```bash
npm init pilet --source @odvi/lego-box
# or
piral new --source @odvi/lego-box my-pilet
```

You can also upgrade an existing pilet to use this shell:

```bash
pilet upgrade --source @odvi/lego-box
```

For local development, use the `--target` flag with the local path:

```bash
piral new --target ./path/to/lego-box my-pilet
```

### Develop Your Pilet

```bash
cd my-pilet
pnpm install
pnpm start
```

This will:
1. Start the pilet's development server
2. Automatically open the Piral emulator with your pilet injected

---

## For Maintainers: Publishing & Development

### Installation

```bash
pnpm install
```

### Development Scripts

| Command | Description |
|---------|-------------|
| `pnpm dev` | Start the Piral debug server (standard development) |
| `pnpm dev:pilets` | Start debug server with pilet feed support for local pilets |
| `pnpm start` | Alias for `pnpm dev` |

### Building the Emulator

```bash
pnpm build:emulator
```

This builds the emulator for distribution. The output is placed in the `dist/` directory.

### Publishing to npm

Before publishing, make sure you have:
1. A valid npm account
2. Run `npm login` (or `pnpm login`)
3. Updated the package name if using a scope (e.g., `@your-org/lego-box`)

#### Automated Release Scripts

| Command | Action |
|---------|--------|
| `pnpm release:patch` | Bump patch version (1.0.0 -> 1.0.1), build, and publish |
| `pnpm release:minor` | Bump minor version (1.0.0 -> 1.1.0), build, and publish |
| `pnpm release:major` | Bump major version (1.0.0 -> 2.0.0), build, and publish |
| `pnpm publish:emulator` | Manually publish the built emulator (requires build first) |

Each release command automatically:
1. Increments the version in `package.json`
2. Creates a git tag
3. Builds the emulator package
4. Extracts the emulator to `dist/emulator/`
5. Publishes to npm with `--access public` (required for scoped packages)

#### Manual Publishing

```bash
pnpm build:emulator
pnpm publish
```

---

## Local Pilet Integration Testing

To test your shell with local pilets before publishing:

### Method 1: Pilet Connects to Shell (Recommended)

Run the pilet's dev server and let it connect to your shell:

```bash
cd ../path/to/my-pilet
pnpm start
```

The pilet will automatically discover and use your local shell running on `http://localhost:1234`.

### Method 2: Using Local Feed (Multiple Pilets)

pilet new @odvi/lego-box --target my-pilet

1. Start the shell with local feed discovery:

```bash
pnpm dev:pilets
```

This uses `piral debug --all` which discovers pilets from local feeds.

2. Or specify a custom feed URL:

```bash
pnpm dev:feed http://localhost:9000/feed.json
```

### Method 3: Explicit Pilet Path

To load pilets from a specific external directory, you can use the `--base-href` option:

```bash
pnpm dev --base-href http://localhost:9000
```

Or via npx directly:

```bash
npx piral debug --base-href http://localhost:9000
```

### Directory Structure Example

```
playground/
├── lego-box/          # ← Your Piral Shell (this repo)
└── pilets/
    ├── pilet-a/       # ← External pilet
    └── pilet-b/       # ← External pilet
```

From `pilet-a`:
```bash
cd ../pilet-a
pnpm start
```

The pilet will connect to `lego-box` running on port 1234.

---

## Project Structure

```
lego-box/
├── src/
│   ├── index.html       # Entry HTML
│   ├── index.tsx        # Main application entry
│   └── ...              # Your shell components
├── dist/                # Built emulator (generated)
├── package.json
├── tsconfig.json
└── README.md
```

---

## Configuration

### Package Name with Scope

If publishing to an organization/scope, update `package.json`:

```json
{
  "name": "@your-org/lego-box",
  "publishConfig": {
    "access": "public"
  }
}
```

### Files Included in Publication

The following files are included when publishing to npm:
- `dist/` - Built emulator
- `src/` - Source files
- `package.json`
- `README.md`

---

## Useful Links

- [Piral Documentation](https://piral.io)
- [Piral CLI Reference](https://docs.piral.io/reference/cli)
- [Creating a Pilet](https://docs.piral.io/tutorials/01-getting-started)

---

## License

MIT