A Piral instance (Shell/Emulator) for building micro-frontends
npm install @odvi/lego-boxShell -> 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
bash
npm install -g piral-cli
or
pnpm add -g piral-cli
`
$3
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
`
$3
`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
$3
`bash
pnpm install
`
$3
| 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 |
$3
`bash
pnpm build:emulator
`
This builds the emulator for distribution. The output is placed in the dist/ directory.
$3
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:
$3
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.
$3
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
`
$3
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
`
$3
`
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
$3
If publishing to an organization/scope, update package.json:
`json
{
"name": "@your-org/lego-box",
"publishConfig": {
"access": "public"
}
}
`
$3
The following files are included when publishing to npm:
- dist/ - Built emulator
- src/ - Source files
- package.json
- README.md`