Deployment Guide

Deploy a custom Facets web component to GitHub Pages or other static HTTPS hosting, then register it in the Facets UI via the dashboard or API.

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:

Go to Settings > Pages
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:

Service	URL Pattern	Notes
GitHub Pages	`https://<org>.github.io/<repo>/<file>.js`	Free, CI/CD built-in
Amazon S3	`https://<bucket>.s3.amazonaws.com/<file>.js`	Set proper CORS headers
CloudFlare Pages	`https://<project>.pages.dev/<file>.js`	Global CDN, fast
Netlify	`https://<site>.netlify.app/<file>.js`	Auto-deploy from Git

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

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

Via UI

Go to Organization Settings (left sidebar)
Click Web Components
Click Add Component
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
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:

Make changes to your .js file
Commit and push to main
GitHub Actions will redeploy automatically
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

Issue	Solution
Pages returns 404	Ensure Pages is enabled with GitHub Actions source (not branch-based)
Workflow fails	Check that `permissions` block in YAML includes `pages: write` and `id-token: write`
CORS errors	Ensure your hosting service allows requests from your Facets domain
Component not loading	Check browser Network tab for the script URL -- verify it returns 200
Old version still showing	Hard-refresh the browser (Ctrl+Shift+R) to bypass cache