Productify

Appearance

pfy pilet ​

Manage pilet packages for microfrontend applications.

Overview ​

The pilet command provides tools for managing pilet packages - microfrontend modules that can be dynamically loaded by Piral-based applications.

Commands ​

pfy pilet upload ​

Upload a pilet package to the ProductifyFW Manager.

Usage:

bash
pfy pilet upload \
  --project-id PROJECT_ID \
  --name PILET_NAME \
  --version VERSION \
  --file PATH_TO_FILE \
  [--description DESCRIPTION]

Flags:

FlagAliasRequiredDescription
--project-id-YesProject ID where the pilet belongs
--name-YesPilet package name (e.g., @myapp/dashboard)
--version-YesSemantic version (e.g., 1.0.0)
--file-YesPath to the pilet package file
--description-NoOptional description of the pilet

Examples:

Upload a simple pilet:

bash
pfy pilet upload \
  --project-id 550e8400-e29b-41d4-a716-446655440000 \
  --name @myapp/dashboard \
  --version 1.0.0 \
  --file dist/index.js

Upload with description:

bash
pfy pilet upload \
  --project-id 550e8400-e29b-41d4-a716-446655440000 \
  --name @myapp/settings \
  --version 2.1.5 \
  --file dist/index.js \
  --description "Settings management module"

Upload using environment variables:

bash
export PFY_MANAGER_URL=https://manager.example.com
export PFY_MANAGER_TOKEN=your-pat-token

pfy pilet upload \
  --project-id 550e8400-e29b-41d4-a716-446655440000 \
  --name @myapp/checkout \
  --version 3.0.0 \
  --file dist/index.js

Authentication:

Requires a valid Personal Access Token (PAT). Set via:

  1. --token flag
  2. PFY_MANAGER_TOKEN environment variable
  3. Login with pfy login

Output:

Success:

Pilet uploaded successfully: @myapp/dashboard@1.0.0

Verbose mode (-v):

Connecting to ProductifyFW manager...
Uploading pilet '@myapp/dashboard' version '1.0.0' to project '550e8400-e29b-41d4-a716-446655440000'...
Pilet uploaded successfully: @myapp/dashboard@1.0.0
  Project ID: 550e8400-e29b-41d4-a716-446655440000
  File: dist/index.js
  Description: Dashboard widget module

Pilet Package Format ​

Pilets are typically JavaScript bundles created by the Piral CLI:

bash
# Build with piral-cli
pilet build

# Results in dist/index.js

The package should be compatible with Piral v2 specification.

Workflow ​

1. Build Your Pilet ​

bash
cd my-pilet
pnpm install
pnpm build  # or: pilet build

2. Upload to Manager ​

bash
pfy pilet upload \
  --project-id YOUR_PROJECT_ID \
  --name my-pilet \
  --version 1.0.0 \
  --file dist/index.js

3. Enable in Application ​

In the ProductifyFW Manager UI:

  1. Navigate to your application settings
  2. Go to "Modules" section
  3. Add the pilet name to enabled modules list

4. Verify Loading ​

The pilet will be included in the feed response:

bash
curl http://your-app.example.com/pilet-feed/APP_ID

Response:

json
{
  "items": [
    {
      "name": "my-pilet",
      "version": "1.0.0",
      "link": "/pilets/PROJECT_ID/my-pilet/1.0.0",
      "hash": "abc123...",
      "spec": "v2"
    }
  ]
}

Integration with CI/CD ​

GitHub Actions Example ​

yaml
name: Deploy Pilet

on:
  push:
    tags:
      - "v*"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install dependencies
        run: pnpm install

      - name: Build pilet
        run: pnpm build

      - name: Upload to Productify
        env:
          PFY_MANAGER_URL: ${{ secrets.MANAGER_URL }}
          PFY_MANAGER_TOKEN: ${{ secrets.MANAGER_TOKEN }}
        run: |
          VERSION=${GITHUB_REF#refs/tags/v}
          pfy pilet upload \
            --project-id ${{ secrets.PROJECT_ID }} \
            --name @myapp/my-pilet \
            --version $VERSION \
            --file dist/index.js

GitLab CI Example ​

yaml
deploy:
  stage: deploy
  script:
    - pnpm install
    - pnpm build
    - |
      pfy pilet upload \
        --project-id $PROJECT_ID \
        --name @myapp/my-pilet \
        --version $CI_COMMIT_TAG \
        --file dist/index.js
  only:
    - tags
  variables:
    PFY_MANAGER_URL: $MANAGER_URL
    PFY_MANAGER_TOKEN: $MANAGER_TOKEN

Best Practices ​

Versioning ​

Use semantic versioning:

bash
# Patch release
pfy pilet upload --version 1.0.1 ...

# Minor release
pfy pilet upload --version 1.1.0 ...

# Major release
pfy pilet upload --version 2.0.0 ...

Scoped Packages ​

Use scoped package names for organization:

bash
pfy pilet upload --name @mycompany/feature-dashboard ...
pfy pilet upload --name @mycompany/feature-settings ...

Descriptions ​

Include helpful descriptions:

bash
pfy pilet upload \
  --description "User dashboard with charts and metrics" \
  ...

Validation ​

Verify the upload was successful:

bash
# Check the pilet feed
curl -H "Authorization: Bearer $TOKEN" \
  http://manager.example.com/pilet-feed/APP_ID

Troubleshooting ​

Upload Failed ​

Error: upload failed with status 401: Unauthorized

Solution: Check your PAT token is valid and has permission to upload pilets.

File Not Found ​

Error: failed to open file: no such file or directory

Solution: Verify the file path is correct. Use relative or absolute paths.

Version Conflict ​

Error: pilet version already exists

Solution: Increment the version number or delete the existing version first.

See Also ​