Deployment Guide

This guide covers deploying your web component to a static hosting service and registering it in Facets.

Repository Structure

A typical web component repository contains:

my-component/
  my-component.js          # Your web component (required)
  index.html               # Test page for local development
  .github/
    workflows/
      deploy.yml           # GitHub Actions workflow for Pages deployment
  README.md                # Optional documentation

GitHub Pages Deployment

Step 1: Create the Repository

gh repo create <your-org>/my-component --public --clone
cd my-component

Step 2: Add Your Files

Add your component .js file, index.html test page, and the GitHub Actions workflow.

Step 3: GitHub Actions Workflow

Create .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Pages
        uses: actions/configure-pages@v5

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: '.'

      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Step 4: Enable GitHub Pages

In your repository settings:

1. Go to Settings > Pages
2. Under Source, select GitHub Actions

Or via the GitHub CLI:

gh api repos/<your-org>/my-component/pages -X POST -f build_type=workflow

Step 5: Push and Deploy

git add .
git commit -m "Initial web component"
git push origin main

The workflow will trigger automatically. Check status with:

gh run list --limit 5

Step 6: Verify Deployment

Your component will be available at:

https://<your-org>.github.io/my-component/my-component.js

Verify with:

curl -s -o /dev/null -w "%{http_code}" https://<your-org>.github.io/my-component/my-component.js

A 200 status means it's deployed successfully.

Alternative Hosting Options

You can host your web component on any static file hosting service:

Requirements for any hosting service:

• File must be accessible over HTTPS
• File must be publicly accessible (no authentication required to fetch the .js file)
• CORS headers must allow loading from your Facets instance domain

Registering in Facets

After deploying your component, register it in the Facets platform:

Via UI

1. Go to Organization Settings (left sidebar)
2. Click Web Components
3. Click Add Component
4. Fill in the form:
   • Name: Your custom element name (e.g., my-component)
   • Type: NAV_APP (sidebar) or TAB_APP (tab)
   • Remote URL: https://<your-org>.github.io/my-component/my-component.js
   • Icon URL: (optional) URL to an icon image
   • Enabled: Toggle on
   • Tooltip: Brief description shown on hover
5. Click Add

Your component will appear in the sidebar immediately.

Via API

curl -X POST "https://<your-instance>.console.facets.cloud/cc-ui/v1/web-components" \
  -H "Content-Type: application/json" \
  -b "SESSION_COOKIE" \
  -d '{
    "name": "my-component",
    "type": "NAV_APP",
    "remoteURL": "https://<your-org>.github.io/my-component/my-component.js",
    "enabled": true,
    "tooltip": "My Custom Component"
  }'

Updating Your Component

To update an already-deployed component:

1. Make changes to your .js file
2. Commit and push to main
3. GitHub Actions will redeploy automatically
4. The component updates in Facets on next page load (the script URL doesn't change)

No re-registration is needed -- Facets fetches the script from the same URL each time.

Troubleshooting