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.

$3

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`

---

Useful Links

- Piral Documentation
- Piral CLI Reference
- Creating a Pilet

---

License

MIT

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.

$3

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`

---

Useful Links

- Piral Documentation
- Piral CLI Reference
- Creating a Pilet

---

License

MIT