@goil/badge

@goil/badge

Lightweight "Made with Goil" badge widget. Drops into any HTML page, React, or Next.js project.

• ~1.9 kB gzipped (IIFE script) — zero dependencies at runtime
• Shadow DOM for full style isolation — won't conflict with host site CSS
• Auto-detects color scheme (prefers-color-scheme) and browser language
• Catalan / Spanish / English translations
• Subtle glare hover animation

Usage

HTML / static site

<script src="https://cdn.goil.app/badge/goil-badge.iife.min.js"></script>

With config (set before the script tag):

<script>
  window.GoilBadgeConfig = {
    variant: 'auto',          // 'dark' | 'light' | 'auto'  (default: 'auto')
    lang: 'auto',             // 'en' | 'es' | 'ca' | 'auto' (default: 'auto')
    position: 'bottom-right', // 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'
    zIndex: 9999,
  };
</script>
<script src="https://cdn.goil.app/badge/goil-badge.iife.min.js"></script>

React / Next.js

npm i @goil/badge

import { GoilBadge } from '@goil/badge/react'

export default function Layout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <GoilBadge variant="auto" lang="auto" />
    </>
  )
}

The React component renders inline. Wrap it in your own positioned container if you need it fixed.

Vanilla JS (npm)

import { createGoilBadge } from '@goil/badge'

const { element, destroy } = createGoilBadge({ variant: 'auto', lang: 'auto' })
document.body.appendChild(element)

// later
destroy()

API

interface GoilBadgeOptions {
  variant?: 'dark' | 'light' | 'auto' // default: 'auto'
  lang?: 'en' | 'es' | 'ca' | 'auto'   // default: 'auto'
}

| variant | Background. auto follows prefers-color-scheme and updates live. | | lang | Caption language. auto reads navigator.language (falls back to en). |

Development

pnpm install
pnpm dev        # Vite dev server with live-reloading demo
pnpm build      # Builds dist/ — ESM + CJS + IIFE + .d.ts
pnpm typecheck  # tsc --noEmit

Project layout:

src/
  core.ts       — Vanilla createGoilBadge() — single source of truth, uses Shadow DOM
  react.tsx     — React wrapper (mounts the vanilla badge via useEffect)
  script.ts     — IIFE entry — auto-mounts with window.GoilBadgeConfig
  index.ts      — npm main entry (vanilla)
demo/
  index.html    — Vite dev preview
  main.ts

Two Vite configs:

• vite.config.ts — library build (ESM + CJS for index and react), plus the dev server
• vite.script.config.ts — IIFE/minified bundle for the <script> tag

Build output

dist/
  index.js / index.cjs / index.d.ts      — vanilla npm entry
  react.js / react.cjs / react.d.ts      — React wrapper
  goil-badge.iife.min.js                 — CDN script

Published as @goil/badge on npm. The ./script subpath resolves to the IIFE for self-hosted CDN deploys.

Releases

Versioning, CHANGELOG and publishing are automated via Changesets and GitHub Actions.

Contributor flow:

# after making your change
pnpm changeset           # describe the change + pick patch/minor/major
git commit -am "feat: ..."
git push                 # open PR, merge to main

When the PR is merged to main, a bot opens a "Version Packages" PR that bumps the version and regenerates CHANGELOG.md. Merging that PR triggers the release workflow, which:

• Publishes @goil/badge to npm
• Uploads the IIFE bundle to S3:
  • s3://goil-cdn/badge/v<version>/goil-badge.iife.min.js (immutable, 1y cache)
  • s3://goil-cdn/badge/latest/goil-badge.iife.min.js (mutable, 5min cache)

Consumers can pin a version:

<script src="https://goil-cdn.s3.eu-west-1.amazonaws.com/badge/v0.1.0/goil-badge.iife.min.js"></script>

…or always use the latest:

<script src="https://goil-cdn.s3.eu-west-1.amazonaws.com/badge/latest/goil-badge.iife.min.js"></script>

One-time setup

1. npm — Trusted Publishing (OIDC, no token)

The workflow uses npm's Trusted Publishing — short-lived OIDC tokens, no NPM_TOKEN to manage or rotate. Setup:

• First-time only: publish manually once with pnpm release (with a classic token) so the package exists on npmjs.com.
• On npmjs.com → @goil/badge → Settings → Trusted Publishers → Add GitHub Actions:
  • Owner: goil-app
  • Repository: web-widgets-badge
  • Workflow filename: release.yml
  • Environment: (leave empty)
• Done — every subsequent changeset publish from CI gets short-lived OIDC credentials automatically and publishes provenance attestations.

Requires Node ≥ 22.14 / npm CLI ≥ 11.5.1 (already pinned in the workflow).

2. AWS — OIDC role

Same pattern: no static keys, short-lived credentials via GitHub OIDC.

• Create an IAM OIDC provider for token.actions.githubusercontent.com (one-time per account).
• Create a role with trust policy scoped to repo:goil-app/web-widgets-badge:ref:refs/heads/main and permission to s3:PutObject on arn:aws:s3:::goil-cdn/badge/*.

3. Discord — release notifications

Create a webhook in your Discord channel and copy the URL.

4. GitHub repo settings

• Settings → Actions → General → Workflow permissions: Read and write + Allow Actions to create and approve pull requests.

Repo secrets and variables

Kind	Name	Value
Secret	DISCORD_WEBHOOK_URL	Discord channel webhook for release notifications
Var	AWS_ROLE_ARN	IAM role assumed via OIDC (e.g. arn:aws:iam::…:role/gh-actions-badge)
Var	AWS_REGION	eu-west-3 (matches existing Goil infra)
Var	S3_BUCKET	goil-cdn

No NPM_TOKEN, no AWS_ACCESS_KEY_ID, no AWS_SECRET_ACCESS_KEY — everything is OIDC.

License

MIT © Goil