DOCSEARCHbyAlgolia
Submit Docs

Piral Documentation

website·Indexed 31 days ago

https://docs.piral.io/

Official documentation for Piral, a microfrontend framework. Includes guides for piral-core, pilet API integration, and a wide range of plugins for various frontend frameworks (React, Angular, Vue, Svelte, Ember, Mithril, Hyperapp, etc.) and utilities (urql, fetch, oauth2, oidc, axios).

Tokens
162.7K
Snippets
562
Records
1K
Agent score
45%

What's inside Piral

  1. Overview of the Full Piral Micro Frontend Example

    The Full Piral example demonstrates how to create a micro frontend shell using piral with a completely custom UI composed of standard functional components. Key architectural features demonstrated include:

    • Dynamic Pilet Fetching: Pilets are retrieved dynamically from a sample feed.
    • Virtual Pilets: Demonstrates how to bring in a virtual pilet using the attach API.
    • Data Loading & Communication: Shows how pilets interact with each other and load data.
    • Real Backend Integration: Unlike many mocks, this example interacts with real backend services (e.g., OpenWeather API) rather than a sample gateway.

    The sample pilets used in this demonstration are available in the official Piral repository and are also published on NPM for individual experimentation.

  2. Overview of Piral Application Shell and Pilets

    In the Piral ecosystem, a project typically consists of two main parts:

    1. Application Shell: The host application (Piral Instance) that provides the runtime environment, layout, and services.
    2. Pilet: A micro-frontend plugin that is executed within the Application Shell. Pilets allow you to extend the functionality of the shell dynamically.

    This tutorial sequence covers creating an Application Shell using the Piral CLI and then creating a basic pilet to run inside that shell.

  3. Overview of Piral CLI executables

    The Piral CLI is a Node.js-based tool for automating Piral instance and pilet management. It provides three main shell executables:

    • pb: A generic "Piral build" script that accepts any command (including those suffixed with -piral or -pilet).
    • piral: Specifically for Piral instance commands.
    • pilet: Specifically for pilet commands.

    If the CLI is not installed globally, use npx to run the locally installed version within a pilet or Piral instance directory.

    # Using global installation
pb [any-command]
piral [piral-command]
pilet [pilet-command]

# Using local installation via npx
npx pb [any-command]
npx piral [piral-command]
npx pilet [pilet-command]

  4. Overview of Kras for Backend Mocking in Piral

    Piral integrates kras to enable offline-first development. Kras acts as middleware at the development server (typically http://localhost:1234) and provides three main capabilities:

    1. HTTP Proxying: Forwarding requests to an arbitrary environment.
    2. Static Mocking: Replying to requests with predefined responses (using HAR or JSON formats).
    3. Dynamic Mocking: Using scripted responses to intercept and handle HTTP requests via Node.js logic.

    Configuration can be managed upfront via a .krasrc file or on-demand through the kras management endpoint, usually located at http://localhost:1234/manage-mock-server during a debugging session.

  5. Overview of Piral Loading Strategies

    Piral uses loading strategies to orchestrate how pilets are loaded and evaluated. Strategies are provided by the piral-base package. The choice of strategy affects when the loading spinner is removed and how much order is guaranteed during pilet evaluation.

  6. Overview of Cross-Framework Piral Components

    Piral supports integrating components from different frameworks within a single application using specific converters. This example demonstrates how to use piral-core as the host application to dynamically fetch and run pilets built with different frameworks, such as Angular (via piral-ng) and Vue (via piral-vue).

    Key features demonstrated in the cross-framework sample:

    • Dynamic pilet fetching.
    • Use of core pilet API functions.
    • Integration of framework-specific plugins (piral-ng for Angular and piral-vue for Vue).
    • Interaction between different framework-based extensions.

  7. Compare Parcel and Webpack for Piral projects

    When choosing a bundler for Piral, consider the following trade-offs:

    Parcel

    • Best for: Beginners and users who want a zero-configuration experience.
    • Pros: "Just works" out of the box; handles TypeScript, React, and Vue with minimal setup.
    • Cons: Less explicit configuration; can be difficult to implement complex requirements like custom Web Worker handling or specific Service Worker logic.

    Webpack

    • Best for: Advanced users, complex build requirements, or migration scenarios (e.g., Stencil or Next.js).
    • Pros: Highly flexible with a vast ecosystem of loaders and plugins; produces smaller release bundles.
    • Cons: Requires manual configuration for advanced needs; more complex build system management.

    Summary Table

    FeatureParcelWebpack (v5)
    SetupZero-configRequires configuration
    FlexibilityOpinionatedHighly extensible
    Release SizeLargerSmaller

  8. Understand Piral package hierarchy and selection

    Piral is modular, allowing you to choose between opinionated frameworks or low-level libraries depending on your requirements:

    • piral: The full framework. It is highly opinionated and includes a standardized set of plugins and dependencies. Use this for a quick start with 'batteries included'.
    • piral-core: A library-focused package that provides the main Piral functionalities and extends the pilet API with component APIs (registerPage and registerExtension). It uses React for its component model and routing but allows you to specify your own versions of react, react-dom, react-router, and react-router-dom via peer dependencies.
    • piral-ext: Provides a standardized set of plugins (e.g., piral-dashboard, piral-menu, piral-notifications).
    • piral-base: The most fundamental, dependency-free library. It provides the basic models (like the PiletApi) and loading strategies without any UI or framework support (no React dependency). Use this if you need to build a custom micro frontend architecture or use a non-React framework.

  9. Monorepo composition patterns in Piral

    When organizing a monorepo for Piral, you can choose one of three primary compositions:

    1. Shell Monorepo: Contains the Piral instance along with various helper libraries.
    2. Core Monorepo: Contains the Piral instance along with a selection of specific pilets.
    3. Domain Monorepo: Contains a collection of pilets (without the Piral instance itself).

    Choosing the right pattern depends on your specific organizational structure and resource availability.

  10. Compare Piral CSR vs SSR Performance

    Client-Side Rendering (CSR)

    In CSR, the client performs the following sequence:

    1. Load the website and scripts.
    2. Evaluate and execute JavaScript.
    3. Request pilet information from the feed service.
    4. Download and execute the retrieved pilets.

    Implication: There is a significant Round-Trip Time (RTT) delay between the initial script load and the application becoming interactive, as the client must fetch the pilet feed at runtime.

    Server-Side Rendering (SSR)

    In SSR, the webserver handles the aggregation:

    1. The webserver requests the pilet feed.
    2. The webserver aggregates the pilets.
    3. The webserver renders the application shell.
    4. The client receives a fully rendered HTML page.

    Implication: SSR improves startup performance and user experience by reducing the work the client needs to do before the first paint. However, it requires a running webserver instead of static storage and increases backend complexity.

    Hybrid Approach

    You can implement a hybrid model where the server performs the initial pilet feed aggregation (to include the data in the initial HTML), but the actual downloading and execution of the pilets still occur on the client-side.

  11. Understand Piral Architecture and Modularization

    Piral is designed to solve the 'frontend monolith' problem by using a modular architecture. Instead of a single giant codebase, a Piral instance acts as a thin orchestration layer that gathers user-relevant modules, called pilets, at runtime.

    Key architectural concepts:

    • Piral Instance: A thin layer delivered to the end-user that is responsible for gathering and integrating pilets.
    • Pilets: Modular npm packages containing libraries (JS files) and metadata. They can be developed in different repositories and owned by different teams.
    • Pilet Feed Service: A service that inspects and unpacks pilet packages to provide them to the Piral instance.
    • Runtime Loading: Pilets are loaded at runtime, allowing for incremental rollouts and distributed development without rebuilding the entire application.

  12. Distinguish between a Pilet and a Page in Piral

    A pilet is a micro frontend package containing all the necessary code, which can include one or many pages. A page is simply a component that is registered and accessed via a routing rule.