# @submitium/badges

The Submitium badge wall: the official badge of every directory that lists your product, in one block on your homepage. Submitium adds and removes badges as your listings change, so you never paste a badge again.

Your server fetches the wall with your project's API key. The package checks our signature and the data, then renders plain links and images with your framework's own elements. We never send HTML, CSS or scripts: no `dangerouslySetInnerHTML`, no `v-html`, no `{@html}`, nothing that runs in the browser.

## Install

```bash
npm install @submitium/badges
```

Create an API key on the Badge wall page of your Submitium dashboard, and put it in your server's environment:

```bash
SUBMITIUM_API_KEY=sbk_live_…
```

It is a secret: keep it on the server. It can only read this project's badge wall. Never expose it to the browser (no `NEXT_PUBLIC_`, `PUBLIC_` or `VITE_` prefix). Revoke it from the dashboard if it leaks; the site shows no wall until it has a new key.

Put the wall on your **homepage**, usually in the footer. That's the page directories check.

## Next.js (App Router)

```tsx
import { SubmitiumBadges } from "@submitium/badges/react";

export function Footer() {
  return (
    <footer>
      <SubmitiumBadges />
    </footer>
  );
}
```

`<SubmitiumBadges />` is an async Server Component. It reads `SUBMITIUM_API_KEY`, and keeps the wall for a minute (`revalidate`), so new badges show within a few minutes of an order.

### With Cache Components

New Next.js 16 apps set `cacheComponents: true` in `next.config.ts`. With it, `next build` fails on any component that fetches data, unless that component is cached with `"use cache"` or placed inside `<Suspense>`. Cache the wall, so the badges stay in the static HTML of the page:

```tsx
import { cacheLife } from "next/cache";
import { SubmitiumBadges } from "@submitium/badges/react";

async function Badges() {
  "use cache";
  cacheLife("minutes");
  return <SubmitiumBadges />;
}

export function Footer() {
  return (
    <footer>
      <Badges />
    </footer>
  );
}
```

With `cacheLife("minutes")`, Next.js fetches the wall again at most once every 60 seconds, in the background, when the page is visited. Keep the key in `SUBMITIUM_API_KEY` and pass no props to `<Badges />`: the props of a `"use cache"` component become part of its cache key.

Placing `<SubmitiumBadges />` inside `<Suspense>` instead also builds, from version 1.3.0. Next.js then renders the wall on each request and sends it at the end of the HTML, inside an element with the `hidden` attribute, and a React script moves it into place. A checker that reads the HTML without running scripts finds the badges inside that hidden element. `await connection()` is not needed in either case.

## Nuxt

```ts
// server/api/badges.get.ts
import { fetchWall } from "@submitium/badges";

export default defineEventHandler(() => fetchWall());
```

```vue
<script setup lang="ts">
import { BadgeWall } from "@submitium/badges/vue";

const { data: wall } = await useFetch("/api/badges");
</script>

<template>
  <footer>
    <BadgeWall v-if="wall" :wall="wall" />
  </footer>
</template>
```

## SvelteKit

```ts
// src/routes/+layout.server.ts
import { fetchWall } from "@submitium/badges";
import { env } from "$env/dynamic/private";

export async function load() {
  return { wall: await fetchWall({ apiKey: env.SUBMITIUM_API_KEY }) };
}
```

```svelte
<script lang="ts">
  import BadgeWall from "@submitium/badges/svelte";

  let { data, children } = $props();
</script>

{@render children()}

<footer>
  {#if data.wall}
    <BadgeWall wall={data.wall} />
  {/if}
</footer>
```

## Astro

```astro
---
import SubmitiumBadges from "@submitium/badges/astro";
---

<footer>
  <SubmitiumBadges />
</footer>
```

It reads `SUBMITIUM_API_KEY` from `import.meta.env`. A static build fetches the wall when it builds: rebuild once a day to keep it current.

## Any other server

`fetchWall()` returns the checked wall, or `null`. `wallToHtml(layoutWall(wall))` turns it into an HTML string where every value is escaped, to print in your template.

```ts
import { fetchWall, layoutWall, wallToHtml } from "@submitium/badges";

const wall = await fetchWall();
const html = wall ? wallToHtml(layoutWall(wall)) : "";
```

## `fetchWall` options

| Option | Default | |
|---|---|---|
| `apiKey` | `SUBMITIUM_API_KEY` | Your project's API key. |
| `timeout` | `3000` | Milliseconds to wait for the API. Past that, no wall, and your page carries on. |
| `revalidate` | `60` | Seconds a wall is kept before asking again (in memory, and as Next.js `revalidate`). A static Next.js page is rebuilt as often when visited: raise it to rebuild less, and new badges take as long to show. |
| `apiUrl` | `https://api.submitium.com` | For local development only. |

The format (`ribbon`: one gliding line in the footer bar; `window`: a small gliding window under your logo) and the theme are settings you change in the dashboard. Your code stays the same. The "Badge wall by Submitium" line is always `rel="nofollow"`: a link repeated in many sites' footers must not pass ranking credit (Google's link spam policies).

## What the package guarantees

- **Signed.** Every wall is signed with Ed25519. The package checks the signature against our public keys, pinned in its code, before it reads anything. A wall from anyone else, or changed on the way, renders nothing.
- **Checked.** The wall must match a strict contract (`parseWall`): https links that point to the directory's own domain, https images, a closed list of `rel` values, plain text with a length limit, and a wall that hasn't expired (a week at most). Anything else and the whole wall is refused, not repaired.
- **Plain elements only.** The wall becomes links, images, a few spans and one scoped `<style>`, all written by this package from numbers (no CSS comes from the API). React, Vue, Svelte and Astro write each element themselves and escape every value.
- **In your HTML.** The badges are in the HTML your server sends, which is what directory checkers read. No client JavaScript: motion is pure CSS. It pauses on hover and keyboard focus, and stands still under `prefers-reduced-motion`.
- **Up to date within minutes.** Your server keeps the wall for a minute, then asks again: badges a new order adds show within a few minutes, and a busy site asks us once a minute at most, per server. A static build (Astro, `next export`) shows them at its next build.
- **Visible from day one.** Before your first order the wall has no badge yet: it shows one gliding line, "Directory badges will appear here as this product gets listed.", where the badges will be. Badges replace it as directories are ordered.
- **Never breaks your page.** If the API is slow, down or answers anything unexpected, the last good wall is kept, or nothing renders.
- **Fair to directories.** Each badge links to its directory with the directory's official `rel`, the image loads from the directory's own URL, and no badge is hidden or duplicated. Badges a directory wants in view at all times never move.
- **Attribution.** One discreet "Badge wall by Submitium" link, dofollow by default; you can make it nofollow in the dashboard.

## License

MIT. Source and how it works: https://submitium.com/badge-wall
