@odvi/lego-box

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

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:

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:

pilet upgrade --source @odvi/lego-box

For local development, use the --target flag with the local path:

piral new --target ./path/to/lego-box my-pilet

Develop Your Pilet

cd my-pilet
pnpm install
pnpm start

This will:

• Start the pilet's development server
• Automatically open the Piral emulator with your pilet injected

For Maintainers: Publishing & Development

Installation

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

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:

• A valid npm account
• Run npm login (or pnpm login)
• 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:

• Increments the version in package.json
• Creates a git tag
• Builds the emulator package
• Extracts the emulator to dist/emulator/
• Publishes to npm with --access public (required for scoped packages)

Manual Publishing

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:

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

• Start the shell with local feed discovery:

pnpm dev:pilets

This uses piral debug --all which discovers pilets from local feeds.

• Or specify a custom feed URL:

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:

pnpm dev --base-href http://localhost:9000

Or via npx directly:

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:

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:

{
  "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
• Piral CLI Reference
• Creating a Pilet

License

MIT