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 [email protected]

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:

1. Start the pilet's development server
2. 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:

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

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

1. Start the shell with local feed discovery:

pnpm dev:pilets

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

2. 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